Initial project import

docs/runbooks/1c-agent-coding-contract.md

@@ -1,7 +1,8 @@
 # 1C Agent Coding Contract
 
 This contract is the default rule set for coding agents that work through the
-1C adapter.
+1C adapter. The agent calls it only through the `onec_request` MCP tool; the
+REST SQL adapter is MCP's private downstream transport.
 
 ## Default View
 
@@ -13,6 +14,57 @@ This contract is the default rule set for coding agents that work through the
 - Objects can exist only in saved-state and can later be activated or canceled.
   Do not hide them from the agent view.
 
+### Empty saved-state layer
+
+An empty saved-state layer is normal before the first edit. In that case an
+agent still uses only public selectors and reports the adapter result; it must
+not obtain an active `ConfigCAS`/`Config` module reference and retry by hand.
+
+Known adapter limitation (2026-08-02): for an extension-owned object module
+with no prepared saved-state row, public `code.read` can return
+`source_missing` even though the active module is proven to exist. Treat this
+as an adapter defect, not as evidence that the 1C object or BSL is absent.
+Use a developer-owned diagnostic check to investigate it; do not expose its
+storage coordinates to a coding agent.
+
+## Required adapter acceptance fixture
+
+`upo_test` must contain one isolated extension-owned `Report` with a decoded
+`object_module`, a unique BSL anchor, and no shared business role. This fixture
+is created and maintained by a human in Configurator; the SQL-only adapter must
+not fabricate it. It is the required target for the public acceptance sequence:
+
+```text
+code.read(ref, extension, module_ordinal=1)
+→ code.write(old, new, apply_and_rollback)
+→ code.search verifies new text
+→ rollback and saved-state cleanup
+```
+
+The request must contain no `layer`, table, file name, module ref, payload hash,
+or stream index. Until the fixture exists, unit tests prove routing only; they
+do not prove a live extension Report write.
+
+### Verified base-module smoke
+
+On 2026-08-02 the public sequence was verified on `upo_test` against base
+`Report.АвтоматическиеСкидки`, `module_ordinal=1`: a unique comment replacement
+completed in about 25 seconds with `verified_and_rolled_back`. The adapter
+auto-prepared `ConfigSave`, read back the write, rolled back the BSL change,
+then removed the exact rows it had prepared. The public result contains the
+opaque `prepare_receipt_id` and `prepare_cleanup`; the final saved-state status
+was `empty`. This validates the base route only, not the extension Report route.
+Live check on 2026-08-02 found 19 extensions but zero extension-owned Reports
+in `upo_test`; therefore the required extension acceptance fixture is currently
+missing and the extension write branch remains unaccepted.
+
+Live check on 2026-08-13 found an extension BSL stream for
+`Report.УОП_ИнвентаризационнаяОпись`, but its `role_status=unconfirmed`.
+That is read-only evidence, not an acceptance fixture: do not write through an
+ordinal, storage reference, or guessed Configurator role. A human must add or
+identify one extension Report with a decoded `object_module` before the live
+extension `apply_and_rollback` test can run.
+
 ## Compare Views
 
 - Use `state=both` or `source_state=all` only when the task needs a comparison
@@ -33,6 +85,34 @@ Use public names and selectors:
 3. `code.read` with `state=working` to read the module or routine.
 4. `code.read` with `state=both` only for an explicit saved-vs-active check.
 
+For a report form, keep the descriptions separate:
+
+1. `metadata.object.forms(ref=Report.<name>, source_state=working)` lists the
+   report's form references.
+2. `metadata.object.form.details` with that same public report ref and the
+   returned form name reads the form description (attributes, parameters,
+   commands, items, and the form module).
+3. `metadata.form.decode(view=structure)` is an optional compact static
+   projection. It must retain `unresolved` parent/child links where no SQL
+   codec has proved them.
+
+A form command does not have its own module. Its handler is a named routine in
+the form module only when the decoder returns an evidenced command link.
+
+Use the `read_selector.selector_token` returned by discovery with the method
+declared in that selector. Do not copy GUIDs, module refs, table names, or file
+names into a follow-up request. A module ordinal, display name, or storage-derived role
+is not a Configurator-tree path. If a result has `role_status=unconfirmed` or
+`configurator_path_status=unconfirmed`, the agent must not name, write, or
+infer its tree owner; report the missing decoder evidence instead.
+
+When checking object commands, call `metadata.object.commands` with the same
+public `ref`/`kind`+`name` and `extension` selector. The adapter resolves the
+extension name and reads its active metadata itself. A prior `not_found` from a
+route that did not carry the extension context is not evidence that the report
+has no commands. Conversely, a BSL stream suffix alone is never evidence of a
+command or of its module path.
+
 Agents should ask for and report object names, routine names, and code text.
 They should not ask users for SQL tables, storage file names, stream indexes, or
 saved-state write flags during normal coding work.
@@ -52,12 +132,52 @@ Supported public edit shapes:
 say "save this code" and send the desired code text. It must not ask whether SQL
 saved-state apply flags are allowed.
 
+For extension object modules, preparation maps the active payload route to its
+canonical saved-state filename internally. A public `code.write` therefore
+continues with `extension`, `ref`, module role, and the proven replacement
+only; it must never ask the caller to supply the canonical filename or stream.
+
 Every successful `code.write` response must show:
 
 - `write_mode.target=saved_state`;
 - `write_mode.activation_state=not_activated`;
 - `write_mode.production_apply=false`.
 
+### Repository-controlled extension writes
+
+For a repository-controlled extension, use the public sequence below and stop
+when it asks for a human Configurator action:
+
+```text
+code.search(extension, ref, old fragment)
+→ repository.lock.plan(extension, ref)
+→ repository.lock.request
+→ human captures the exact object in Configurator
+→ repository.lock.confirm
+→ code.write(extension, ref, module_ordinal, old, new, repository_lock)
+→ code.search readback
+```
+
+The lock plan for `upo / фс_Отчеты1 /
+Report.фс_ПродовольственнаяКорзина` resolves exactly one object:
+`Отчет.фс_ПродовольственнаяКорзина`, in extension layer
+`extension:8e02accd-8a34-11f1-8294-005056b0d483`. SQL cannot prove a native
+Configurator capture; only a human confirmation can continue this route.
+
+`metadata.write.preflight` currently plans canonical high-level
+`metadata.write` targets and may return `needs_route` for this compatibility
+`code.write` shape before saved-state preparation. This is not permission to
+use its low-level payload hint. Use `code.write(mode=plan)` instead: a first
+extension edit may return public `needs_prepare`, which means to confirm the
+repository lock and reissue the same public request in an apply mode. Keep
+using the public `code.write` route; report any different route failure to
+adapter developers.
+
+If it returns `extension_saved_state_prepare_protocol_unproven`, do not retry
+or supply technical coordinates. The adapter has not yet proven the exact
+saved-state preparation codec for this extension layout; report it for adapter
+development. Do not infer that the extension was not saved in Configurator.
+
 ## Hidden Storage Details
 
 The form module container marker `///----` is adapter-owned storage syntax.