@awak-app/simy-cli 0.5.10 → 0.5.12

package/README.md

@@ -424,6 +424,19 @@ Deploy this CLI and the web capability proxy before enabling the backend scope
 requirement. Older clients receive an explicit upgrade error, never an expanded
 organization-wide bundle.
 
+### Minimum functional completion
+
+Every CLI coding-loop promotion now requires a current two-layer observation
+matrix: the requested operation and result, plus independently checked final
+postcondition and integration. See the [minimum completion contract](src/codex-plugins/simy/skills/agentic-delivery-loop/references/minimum-completion.md)
+for the executable format. Missing mappings, mismatching observations, changed
+artifacts or stale revisions block promotion even when the executor reports
+success. Independent review checks original-request coverage and the test oracle.
+
+Existing v2 run history is retained; resumed/rechecked runs need the new evidence.
+The same checker ships in the standalone Delivery Loop skill, but it does not
+control the host's final response or establish deployment completion.
+
 ### Submit repaired local delivery evidence to SQM
 
 The bundled Delivery Loop maintains an external acceptance checklist with separate
@@ -444,3 +457,13 @@ session. `--dry-run` previews the exact document without uploading it. See the
 [local evidence contract](src/codex-plugins/simy/skills/agentic-delivery-loop/references/local-sqm-evidence.md).
 The receipt identifies the source digest and analysis job; it is not a declaration
 that an incident or blocking rule has been published.
+
+## Delivery Loop shared specification
+
+The [Delivery Loop system specification](docs/systems/delivery-loop/README.md)
+explains its purpose, As-Is and proposed To-Be through twelve linked views. Keep
+these as shared team documents; each change updates affected views and checks
+cross-view consistency. The skill requires independent design, implementation-to-
+To-Be and PR reviews, plus explicitly opted-in SQM before and after PR creation.
+The [workflow reference](src/codex-plugins/simy/skills/agentic-delivery-loop/references/shared-system-specifications.md)
+explains baseline updates, historical regression coverage and evidence limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awak-app/simy-cli",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Local SIMY executor for non-coding Local Tasks and Agentic Loop runs.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "check:auto-update": "node --check ./src/auto-update.js && node --check ./scripts/auto-update-e2e.js && npm run check:sqm",
     "check:sqm": "node --check ./src/sqm/canonical.js && node --check ./src/sqm/validation.js && node --check ./src/sqm/reliability.js && node --check ./src/sqm/repository.js && node --check ./src/sqm/checkers.js && node --check ./src/sqm/bundle-store.js && node --check ./src/sqm/proof.js && node --check ./src/sqm/evidence-client.js && node --check ./src/sqm/session.js && node --check ./src/sqm/index.js && node --check ./src/sqm/command.js && node --check ./src/sqm/agent-skill.js && node --check ./src/sqm/workflow-onboarding.js && node --check ./src/sqm/workflow-update.js && node --check ./src/sqm/review-worker.js && node --check ./scripts/sqm-complete-loop-e2e.js && node --check ./scripts/sqm-local-review-e2e.js",
     "check:real-provider-syntax": "node --check ./scripts/real-codex-probe.js && node --check ./scripts/real-claude-probe.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js",
-    "check:syntax": "node --check ./src/index.js && node --check ./src/install-update.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
+    "check:syntax": "node --check ./src/index.js && node --check ./src/install-update.js && node --check ./src/agent.js && node --check ./src/browser.js && node --check ./src/web-api.js && node --check ./src/durable-local-task-worker.js && node --check ./src/durable-local-task-steps-contract.js && node --check ./src/bounded-local-task-subtasks-contract.js && node --check ./src/bounded-local-task-subtask-pool.js && node --check ./src/local-task-artifact-contract.js && node --check ./src/execution-capability-contract.js && node --check ./src/shutdown.js && node --check ./src/run-registry.js && node --check ./src/direct-executor.js && node --check ./src/execution-guardrail.js && node --check ./src/backend-executable.js && node --check ./src/provider-stream.js && node --check ./src/console/index.js && node --check ./src/console/app.js && node --check ./src/console/commands.js && node --check ./src/local-attachments.js && node --check ./src/repository-inventory.js && node --check ./src/session-store.js && node --check ./src/web-origin.js && node --check ./src/workspace-context.js && node --check ./src/orchestrator/index.js && node --check ./src/orchestrator/shared.js && node --check ./src/orchestrator/recovery.js && node --check ./src/orchestrator/risk.js && node --check ./src/orchestrator/contract.js && node --check ./src/orchestrator/completion-contract.js && node --check ./src/orchestrator/minimum-completion.js && node --check ./src/codex-plugins/simy/skills/agentic-delivery-loop/scripts/check-minimum-completion.mjs && node --check ./src/orchestrator/instruction.js && node --check ./src/orchestrator/problem-solving.js && node --check ./src/orchestrator/budget.js && node --check ./src/orchestrator/execution-io.js && node --check ./src/orchestrator/presentation.js && node --check ./src/orchestrator/result.js && node --check ./src/orchestrator/retry.js && node --check ./src/orchestrator/evidence.js && node --check ./src/orchestrator/independent-audit.js && node --check ./src/orchestrator/audit.js && node --check ./src/orchestrator/loop.js && node --check ./src/runner.js && node --check ./scripts/fixtures/completion-contract-fixture.js && node --check ./scripts/fixtures/fake-coding-backend.js && node --check ./scripts/e2e-terminal-evidence.js && node --check ./scripts/audit-gate-e2e.js && node --check ./scripts/completion-contract-e2e.js && node --check ./scripts/retry-circuit-e2e.js && node --check ./scripts/follow-up-charter-e2e.js && node --check ./scripts/task-routing-e2e.js && node --check ./scripts/executor-version-preflight-e2e.js && node --check ./scripts/blocked-recovery-e2e.js && node --check ./scripts/process-localization-e2e.js && node --check ./scripts/hypothesis-retries-e2e.js && node --check ./scripts/budget-enforcement-e2e.js && node --check ./scripts/local-task-default-workspace-e2e.js && node --check ./scripts/local-task-idempotency-e2e.js && node --check ./scripts/console-e2e-fixture.js && node --check ./scripts/console-e2e.js && node --check ./scripts/console-recovery-e2e-fixture.js && node --check ./scripts/console-recovery-e2e.js && node --check ./scripts/real-provider-console-fixture.js && node --check ./scripts/real-provider-console-e2e.js && node --check ./scripts/fullstack-cli-smoke.js && node --check ./scripts/check-package-contents.js",
     "check:package": "node ./scripts/check-package-contents.js",
     "build:macos-installer:dev": "bash packaging/build-macos-arm64.sh --unsigned-dev",
     "build:macos-installer": "bash packaging/build-macos-arm64.sh --production",

package/src/cli-contract.js

@@ -13,7 +13,7 @@ import {
 } from "./durable-local-task-steps-contract.js";
 import { buildExecutionCapabilityContract } from "./execution-capability-contract.js";
 
-export const CLI_VERSION = "0.5.10";
+export const CLI_VERSION = "0.5.12";
 export const CLI_API_CONTRACT_VERSION = 10;
 
 export function withCliContract(

package/src/codex-plugins/simy/skills/agentic-delivery-loop/SKILL.md

@@ -7,8 +7,11 @@ description: Drive complex repository changes from a frozen success charter and
 
 Use one Codex task as the controller for the complete delivery lifecycle. Shell,
 browser, API, log, database, and artifact operations may all run in the same
-task. Treat implementer, user actor, evidence collector, and verifier as logical
-roles; they do not require separate agents.
+task. The controller coordinates implementation and evidence collection. Every
+review verdict must come from an independent agent/session that did not author
+the reviewed implementation or specification; self-checks are useful diagnostics,
+not review approval. Give reviewers original sources and raw evidence, not a
+prescribed conclusion. The controller retains transition and authority ownership.
 
 ## Confirm the delivery level in chat
 
@@ -30,9 +33,20 @@ external-message authority and never weakens repository-required gates.
 
 ## Freeze the delivery charter
 
+Start with the beneficiary's experience, not the proposed solution. Read-only
+discovery may supply facts, but before solution design or coding freeze a compact
+experience contract: who is in what situation, what they are trying to achieve,
+the complete usable outcome, what they should understand and do next at each
+observable moment, recovery and forbidden experiences, and how each moment will
+be observed. Give each moment a stable UX/acceptance ID and carry those same IDs
+through the shared To-Be, implementation mapping, and results matrix. Do not use
+a list of components, endpoints, screens, or tasks as a substitute for the
+end-to-end experience.
+
 Before material action, record:
 
-- objective and user-visible success conditions;
+- objective, beneficiary, and the frozen experience contract with user-visible
+  success conditions;
 - authoritative acceptance sources that are independent of the candidate
   implementation, plus architecture boundaries and dependency direction;
 - repositories, latest base branches, dedicated worktrees, environments, and
@@ -51,11 +65,41 @@ Do not silently weaken explicit conditions. Add discoveries as a charter patch.
 A scope or success-condition change needs user direction when it materially
 changes the requested result.
 
+## Maintain the system's shared specification
+
+Before implementation, read [shared system specifications](references/shared-system-specifications.md).
+Find the team's canonical specification for this system; create it once if absent.
+Reconcile the frozen experience contract with the current As-Is, then update only
+the affected To-Be views. Preserve the purpose, beneficiary, current pain,
+intended user experience, observable success, and stable UX/acceptance IDs.
+Maintain the twelve-view inventory, stable IDs and cross-view impact links in the
+shared source, not twelve new task-local copies. Unaffected views retain their
+version; unknown As-Is facts remain unknown. Review changes through the team's
+normal version control and preserve concurrent work.
+
+Use independent agents for design review (including consistency across diagram
+kinds), implementation-to-To-Be review, and final PR/evidence review at **every**
+level. Reviewers inspect the full affected path and unchanged linked views. Fix
+findings and obtain independent re-review. A changed requirement or baseline
+invalidates affected approval; do not rewrite To-Be to disguise a failed result.
+
+PR creation and post-creation verification include the SQM loop described in the
+reference. Announce this requirement when starting Delivery Loop. Running SQM
+still follows its explicit opt-in/authority rules; if opt-in or access is absent,
+retain the unmet SQM gate and continue independent work. Ordinary PR work outside
+Delivery Loop does not activate this workflow. Record known incident coverage and
+unknown coverage separately; a green proof with no applicable rules does not prove
+that historical failures cannot recur.
+
 ## Maintain the acceptance checklist outside the conversation
 
 Before implementation, read [acceptance evidence](references/acceptance-evidence.md)
 and persist a criterion-by-criterion checklist. Bind the criteria and both
 verification layers to independent acceptance sources in a frozen charter.
+Use the experience contract as the user-facing slice of these same criteria, not
+as a parallel checklist. Every observable moment from the real trigger through a
+usable outcome and applicable recovery path must map to at least one criterion;
+working components do not prove that the combined experience is complete.
 Use a separate current-results matrix for observations, status, evidence,
 unmet reasons, and next actions. Render a readable table alongside the JSON;
 checklists held only in chat or the model's memory are insufficient.
@@ -72,11 +116,36 @@ values, ownership, authorization, and duplication. HTTP 500/network failures are
 failure evidence; absence of a 500 or presence of a 200 does not prove persistence.
 Record justified non-applicability before execution, not after a failed test.
 
+After building the exact candidate in the production-like local environment,
+execute the complete experience and regenerate the readable table. It must let a
+reviewer compare, for every stable ID, the persona/context and expected visible
+outcome, the actual user observation, the independent technical postcondition or
+integration result, evidence, status, and the next repair. Inspect the table as a
+whole to catch gaps between individually working parts. Any missing, pending,
+failed, stale, or unverifiable applicable experience row blocks
+`user_like_local_verified` and returns the loop to the smallest affected repair.
+
 Run the packaged acceptance validator before promoting a relevant verification
 gate and before issuing the completion receipt. A missing, pending, failed, stale,
 or unverifiable applicable row prevents promotion. Matrix completeness is one
 necessary gate, not proof of deployment, authority, or overall completion.
 
+## Enforce the minimum functional floor
+
+At every delivery level, use [minimum completion](references/minimum-completion.md)
+for requested-outcome verification. Map all requirements to implementation and
+actual operation/result plus independent postcondition/integration observations.
+For persistence, require reload/session return and stored values/ownership. A
+working control, success message or HTTP 200 alone is insufficient.
+
+The bundled minimum checker extends the acceptance matrix with structured
+observations. Compare the original request to the stable criterion-ID list independently so
+omitted requirements cannot disappear before validation. A missing, failed or
+stale floor check prevents verified completion at any level. The CLI now enforces
+this before implementation/PR promotion and on recheck; the standalone command
+validates evidence but cannot intercept the host application's final response.
+Do not call a standalone result host-enforced completion or overall delivery.
+
 ## Check existing rules before implementation
 
 Before implementation, publish a compact rule inventory in the charter record.
@@ -221,13 +290,13 @@ Run focused regression tests first, then formatting, lint, type checking, unit
 tests, and the actual affected runtime. Apply only the relevant lanes from
 [the change-boundary matrix](references/change-boundary-matrix.md).
 
-For medium/high-risk work, run an independent blocker/P1 review after local
-verification. Fix findings narrowly and re-review only the fixes and directly
-affected behavior.
+After local verification at every level, have an independent agent compare the
+implementation and observed user outcomes to the frozen To-Be and original request.
+Include cross-view consistency, omissions and applicable historical regressions.
+Fix findings narrowly and independently re-review the affected behavior.
 
 Give the independent verifier the acceptance sources and raw evidence, not just
-the implementer's summary. Use a separate session/agent as required by risk and
-repository rules; another model can help but model count is not quality evidence.
+the implementer's summary. Use a separate session/agent for every review; another model can help but model count is not quality evidence.
 
 Treat deleted tests, weakened assertions, changed expected values, disabled
 checks, and relaxed CI or security policy as changes to the verification
@@ -239,9 +308,12 @@ production configuration, and CI or security-policy changes.
 
 ### 4. Coordinate through Draft PR and integration state
 
+Before creating a PR, pass the independent To-Be review and pre-PR SQM loop.
 After authority for the required remote changes exists, record reproduction,
 tests, evidence, companion revisions, skipped checks, and remaining gates in the
-Draft PR. Before Ready or merge, combine the latest base with required companion
+Draft PR. After creation, run a fresh SQM loop bound to the actual PR head/base
+and have an independent agent review the PR diff, proofs and incident coverage.
+Before Ready or merge, combine the latest base with required companion
 and parallel changes, rerun the affected path, and confirm current CI and
 mergeability. Without combined-state proof, report `pr_only_verified`, not
 `integration_verified`.
@@ -254,6 +326,12 @@ the charter permits, then have Codex operate the user's Chrome through the
 browser extension as a normal user. Do not replace this gate with direct API
 calls or a fixed selector-only test.
 
+Immediately after the journey, refresh and inspect the experience/acceptance table
+for the same candidate revision, environment, fixture, and input. Compare the
+entire trigger-to-usable-outcome path, including what the user understands and can
+do next, with the frozen experience contract. Do not promote the local journey
+because its individual controls, requests, or services worked in isolation.
+
 Read [Codex Chrome user verification](references/chrome-user-verification.md)
 before running this phase.
 
@@ -295,7 +373,9 @@ and validation ordering still require Delivery Loop execution controls.
 ### 8. Clean up and issue the receipt
 
 Remove scoped fixtures and prove the residual count is zero. Deliver a compact
-completion receipt containing repository revisions, PR and CI, independent
+completion receipt containing shared-spec baseline/To-Be revisions and status,
+cross-view and implementation review results, pre/post-PR SQM proofs and historical
+coverage gaps, repository revisions, PR and CI, independent
 review, container/runtime results, local Chrome evidence, merge and deployment
 identity, deployed Chrome evidence, artifacts, cleanup, skipped gates, and
 residual risk. Convert recurring findings into the smallest maintainable rule,

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/acceptance-evidence.md

@@ -2,6 +2,14 @@
 
 ## Before implementation
 
+Freeze the user experience before proposing the solution. Read-only discovery may
+inform it, but the first authored success record states the beneficiary and
+context, their goal, the complete usable outcome, what they should see,
+understand, and be able to do next at each observable moment, applicable recovery
+and forbidden experiences, and how those moments will be observed. Assign stable
+UX/acceptance IDs. A screen, component, endpoint, task, or stored row is an
+implementation detail unless it is tied to this experience.
+
 The controller externalizes every acceptance condition with a stable ID, observable
 outcome, source independent of the candidate, and required checks. For each
 verification gate, freeze its applicable criteria in `charter.json` and record the
@@ -9,6 +17,13 @@ SHA-256 of the exact file bytes in the controller-owned snapshot. Reconcile the
 gate charters against the overall delivery charter so no requirement disappears.
 Do not choose a convenient subset after observing failures.
 
+Use these criteria as the structured form of the experience contract rather than
+creating a second UX checklist. Cover the full path from its real trigger to its
+usable outcome and the applicable recovery path. When several parts must work
+together for the beneficiary to succeed, include an end-to-end criterion in
+addition to narrower diagnostic criteria. Independent coverage review compares
+the experience contract and original request to the frozen rows before coding.
+
 Each criterion has two layers:
 
 - `user`: a goal-driven user journey with visible interactions and evidence of the
@@ -49,6 +64,15 @@ After every evaluated action (test, repair, review or changed inputs):
 All rows, including pending/failed ones, stay visible. A green matrix cannot advance
 an unrelated gate or prove merge/deployment. Validate again for the final environment.
 
+After the exact candidate is built in a production-like local environment, run
+the complete experience and regenerate `checklist.md` for that same revision,
+environment, fixture, and input. Read the user and system rows together as a
+single experience table: expected outcome, actual user observation, independent
+postcondition/integration result, evidence, status, and next repair. Missing,
+pending, failed, stale, or unverifiable applicable rows prevent
+`user_like_local_verified`. Individually working components cannot override a
+failed or absent end-to-end row.
+
 ## File contract
 
 Charter example (illustrative values must be replaced with actual requirements):
@@ -59,7 +83,7 @@ Charter example (illustrative values must be replaced with actual requirements):
   "run_id": "save-run-42",
   "criteria": [{
     "id": "SAVE-1",
-    "outcome": "The owner can recover the saved note after returning",
+    "outcome": "An owner returning to the task sees the saved note, understands it was retained, and can continue editing",
     "acceptance_source": "Approved issue acceptance criteria, revision 3",
     "layers": {
       "user": {"applicability": "required", "method": "Save in Chrome, reload, sign in again and compare the note"},
@@ -126,5 +150,6 @@ a collector told the truth, a criterion is adequate, or a system is deployed.
 Hashes are not signatures. The controller must protect the frozen digest, verify
 requirement coverage and genuine non-applicability, and inspect raw evidence.
 Independent review checks the oracle and findings; the validator is an additional
-gate within this skill, not a globally installed hook or the CLI orchestrator's
-completion authority.
+gate within this skill, not a globally installed hook. The CLI now additionally
+uses [minimum completion](minimum-completion.md) to enforce current functional
+evidence at its promotion boundary; this basic validator alone is insufficient.

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/delivery-levels.md

@@ -39,7 +39,7 @@ messages.
 | --- | --- | --- | --- |
 | 1 | Maximum assurance | Authentication, payments, destructive or irreversible changes, production security/configuration, sensitive data, and risky migrations | Exercise all affected and adjacent invariants, failure/recovery and rollback paths; require the broadest applicable independent review and repository gates. |
 | 2 | Protected | Persistence, permissions, shared contracts, external side effects, cross-repository changes, and medium-risk migrations | Verify both evidence layers for every affected outcome, shared boundaries, retry/idempotency and recovery; require independent review of the change and affected integrations. |
-| 3 | Balanced (default) | Normal features and bug fixes with bounded, reversible impact | Run focused regressions, applicable static checks, the real affected runtime and main user journey; use risk- and repository-required independent review. |
+| 3 | Balanced (default) | Normal features and bug fixes with bounded, reversible impact | Run focused regressions, applicable static checks, the real affected runtime and main user journey; require independent design/To-Be/PR review, scoped to the affected path. |
 | 4 | Fast | Small, isolated, reversible UI or implementation changes | Run the direct regression and real affected path; add broader checks only for touched shared boundaries; keep mandatory review and evidence gates. |
 | 5 | Fastest | Copy, documentation, comments, metadata, or similarly trivial changes with no runtime/data/security effect | Verify the changed artifact, final diff, packaging/link integrity where applicable, and every repository-mandated check; do not claim untested runtime behavior. |
 
@@ -69,8 +69,12 @@ always choose a lower numbered, safer level.
 Every level preserves:
 
 - frozen success criteria and independent acceptance sources;
+- shared system As-Is/To-Be, cross-view consistency and independent agent reviews;
+- pre/post-PR SQM gates under explicit opt-in, with historical coverage reported;
 - honest state transitions and current revision/context binding;
 - required user/system evidence for applicable outcomes;
 - protection of user work, secrets, data integrity, and tenant boundaries;
 - explicit failure, pending, skipped, and non-applicable reporting;
 - repository-required tests, reviews, CI, and approval/authority boundaries.
+
+All levels retain the [minimum functional floor](minimum-completion.md): requirement mapping, actual operation/result, and independent postcondition/integration observations. Persistence requires reload and stored-state checks. Non-runtime work verifies its real consumer/artifact; no imaginary DB or API checks are added. The minimum checker has no level-based bypass.

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/minimum-completion.md

@@ -0,0 +1,146 @@
+# Minimum functional completion
+
+Every level must prove that the requested work exists, actual operations reach
+the intended result, and necessary persistence/integration works. Speed changes
+adjacent verification breadth, never this floor. The CLI requires this matrix for
+all coding-loop attempts, including legacy v2 resumes/rechecks. No opt-out field
+in an executor result or assurance-level selection disables the gate.
+
+## Collect real observations
+
+Before implementation, reconcile the original request, acceptance criteria and
+planned operations against the frozen experience contract. Preserve every
+observable moment from the real trigger to a usable result, including applicable
+recovery and forbidden experiences; a missing requirement must
+be added through the controller's charter process, not omitted from the matrix.
+The independent auditor compares original-request coverage and checks the oracle
+against raw evidence. Machine mapping checks cannot discover an omitted idea in
+natural language or authenticate what an evidence collector observed.
+
+For each stable criterion ID record implementation_refs (repository-relative file
+paths). New UX-first charters preserve the IDs supplied by the experience
+contract; legacy charters without explicit IDs retain deterministic `AC-N` IDs.
+Then:
+
+- user/operation: operate the actual UI or CLI/consumer. Expected is true; actual
+  is whether the intended operation really executed, not just whether a click
+  command succeeded. Include screenshots/traces where relevant.
+- user/result: observe the requested visible outcome, including reload and session
+  return for a saving feature. Compare expected and actual values, user
+  understanding, and the next action the experience makes available.
+- system/postcondition: independently inspect the final state; for persistence,
+  include the saved values and ownership, not a toast or HTTP status.
+- system/integration: inspect the necessary combined path through APIs, storage,
+  workers or consumers. Job acceptance is not job completion. Use the same input
+  and execution context across layers; cite trace/runtime identities in subject
+  and additional evidence.
+
+For document-only work these mean opening the actual consumer and checking content,
+links and packaged bytes. No DB/API is required if none participates. Both generic
+layers remain required; there is no post-failure waiver. Tests, permissions or
+runtime unavailable means pending/blocked. Never fabricate expected/actual equality.
+Passing narrower rows for controls, APIs, services, or artifacts cannot substitute
+for the end-to-end row when the requested experience depends on their combination.
+
+## Executable contract
+
+`check-minimum-completion.mjs` and `check-acceptance.mjs` ship together under the
+installed skill's scripts directory. The CLI instruction supplies controller input
+JSON; save it as charter.json for the standalone command. It contains id,
+requirement, repository, acceptance_criteria, completion_contract (version 2), and
+thread_state.original_request. For standalone use the controller freezes the same
+fields independently of implementation. The matrix otherwise follows
+[acceptance evidence](acceptance-evidence.md).
+
+To derive the frozen specification/context, import `minimumCharter(charter)` and
+`minimumContext(charter, fullHeadSha)` from the minimum script; import `sha256`
+and `contextDigest` from check-acceptance.mjs. The charter digest is
+`sha256(Buffer.from(JSON.stringify(minimumCharter(charter))))`.
+The context digest is `contextDigest(minimumContext(charter, fullHeadSha))`.
+The CLI derives both itself; it never takes expected digests from executor output.
+
+The current CLI context is one local checkout, its full HEAD, controller charter
+ID and request digest. A clean checkout is required and checked again after
+collection. This is not automatic multi-repository deployment identity discovery.
+For companion services, verify the combined path and record the pinned service
+identities in the evidence; the independent reviewer must validate their current
+identity. Do not claim that this single-checkout gate automatically re-reads a
+companion service's Git HEAD or production environment.
+
+Every matrix row uses the same stable criterion ID and adds
+`implementation_refs: ["src/example.js"]`. Each required
+user/system cell's **first** evidence file is JSON with this shape (user example):
+
+```json
+{
+  "criterion_id": "AC-1",
+  "context_sha256": "<current context digest>",
+  "checks": {
+    "operation": {"subject": "Save clicked and request observed for fixture run", "expected": true, "actual": true},
+    "result": {"subject": "Note after reload and session return", "expected": "requested text", "actual": "requested text"}
+  }
+}
+```
+
+The system file uses `postcondition` and `integration` instead. Each has `subject`,
+non-null `expected` and actual observed `actual`. Values may be objects/arrays to
+compare saved values and ownership together. The checker compares values exactly;
+missing fields or mismatches fail regardless of a cell's passed flag. Additional
+cell evidence may contain screenshots or logs; all artifact hashes are validated.
+Keep raw evidence local and use synthetic data, never credentials/personal data.
+
+Store matrix and evidence under ui_evidence_root, or under repository `.artifacts`
+when no root was specified. All artifact paths are relative to the matrix directory.
+Return `delivery_evidence_path` in SIMY_RESULT_JSON, absolute under that root or
+relative to it. Source mappings must resolve to files inside the current repository.
+Evidence must be bounded regular files; path escapes/symlinks are rejected.
+
+Standalone invocation, with controller-owned trusted digests:
+
+```text
+node <installed-skill>/scripts/check-minimum-completion.mjs charter.json matrix.json context.json <trusted-charter-sha256> <trusted-context-sha256>
+```
+
+Exit 0 is evidence_complete; 1 is evidence_incomplete; 2 means invalid/unavailable
+inputs. JSON includes a readable checklist and floor failures. Check the top-level
+status, not only individual base-matrix rows. The standalone checker validates
+mapping structure; only the CLI additionally resolves mappings in its checkout.
+Neither file hashes nor a passed report authenticate the collector or prove an
+oracle matches the original requirement. Independent coverage/oracle review is
+required by the CLI and must inspect the raw evidence. The standalone command
+cannot stop Codex/Claude's final chat response and does not install global hooks.
+
+## State, review and recovery
+
+The CLI's implementation gate includes the minimum report before independent
+review. The review returns coverage_review with requirements_complete,
+unmapped_requirements and a concrete observation. The controller binds that
+review to the matrix digest, then recollects evidence. Changing the matrix after
+review requires a new review; changing HEAD or dirtying the tree invalidates the
+proof. A concurrent call using the same run ID is rejected, including cloned snapshots.
+A repeated start rechecks evidence without executing the implementation again;
+explicit resume remains the repair path. Cross-process
+execution remains subject to existing runner/host ownership controls.
+
+PR recheck clears prior completion flags and reruns the floor. Missing evidence
+never promotes an old successful audit. The old history is retained; do not rewrite
+it as verified under the new floor. Fix the named criterion, collect fresh evidence
+and resume within the retry budget. Reconcile ambiguous external side effects
+before retrying. The minimum pass is a prerequisite for existing CI/review/authority
+gates, not merge, deployment or a complete production delivery.
+
+Rollback: restoring the older CLI removes this additional enforcement. Retain the
+versioned evidence/history and report that limitation; never relabel old evidence
+as verified by this floor. Monitor minimum-completion findings and subsequent
+reviewer-discovered gaps through existing local run records; no new telemetry or
+external provider calls are introduced.
+
+## Shared specifications and independent review
+
+The floor's stable criterion rows trace back to requirement IDs in the team's shared
+As-Is/To-Be specification. Follow [shared system specifications](shared-system-specifications.md)
+for purpose, user experience, cross-view consistency, independent reviews and
+pre/post-PR SQM. These are controller workflow obligations, not fields magically
+validated by the minimum checker. The CLI gate verifies minimum structured evidence;
+it does not launch every design review or SQM phase on its own. Standalone hosts
+remain responsible for executing this skill and cannot claim an enforced host hook.

package/src/codex-plugins/simy/skills/agentic-delivery-loop/references/shared-system-specifications.md

@@ -0,0 +1,151 @@
+# Shared system specifications and delivery review
+
+Read before planning a Delivery Loop change. The specification belongs to the
+system and its team, not to a single run. Use existing team paths and conventions;
+if none exist, start `docs/systems/<system-id>/` with an index and the applicable
+views below. Repository paths here are a convention, not a demand to move existing
+documents or to create a new service. Keep one canonical source for each concept.
+
+## Shared baseline and proposed change
+
+The system index records its owner/maintainers, repository/document links, stable
+system ID, As-Is source revision(s) and environment, verified date, and gaps.
+Distinguish source-code behavior, locally observed behavior, and deployed behavior.
+An old design or green PR is not proof of current production behavior.
+
+At the start of each run:
+
+1. Freeze the experience contract from the original request before proposing a
+   solution: beneficiary/context, goal, complete usable outcome, observable
+   moments with what the person sees, understands, and can do next, recovery and
+   forbidden experiences, and the observation method. Read-only discovery may
+   inform this record. Give every moment a stable UX/acceptance ID.
+2. Read the existing index and current linked views. Reconcile relevant As-Is with
+   code and actual behavior; label unknowns, cite evidence, and correct documented
+   drift without claiming that the drift was part of the requested feature.
+3. Reconcile why the change matters against that contract: current difficulty,
+   observable success, and non-goals. Preserve the user's original request as an
+   independent acceptance source; do not replace their outcome with a component
+   or implementation inventory.
+4. Prepare a proposed To-Be on a branch/change proposal linked from the shared
+   system index. Record its baseline revision, affected stable IDs, before/after
+   behavior, dependencies and acceptance oracles. Reuse unchanged views by reference;
+   do not copy the whole specification into every run or generate empty diagrams.
+5. Link each experience ID to workflow, screen/control, state/sequence, API/event,
+   data/relationship, permission and runtime boundaries as applicable. Map these
+   stable system IDs to the run's criterion rows and implementation/evidence locations.
+6. Obtain independent design review before implementation. Supply the original
+   request, shared baseline, To-Be and linked unchanged views. Missing evidence or
+   contradictory views remains pending/failed, never silently accepted.
+
+After the exact local candidate is built, update the existing acceptance matrix
+and its readable table for those same experience IDs. Compare expected experience,
+actual user observation, independent system result, evidence, status, and next
+repair across the whole journey. This is a view of the canonical acceptance data,
+not another specification. A gap between working parts blocks local user-journey
+promotion even if every part passed a narrower test.
+
+The twelve-view index must account for every category: present (with a canonical
+link), unchanged (with a revision), not applicable (with a reason), or unknown
+(with an owner/next action). Only create/update a diagram where it describes a
+real system concept. For CLI/skill systems, chat/terminal interactions can be the
+interface views; do not invent application screens, APIs, tables or infrastructure.
+
+| View | Primary content | Consistency checks against other views |
+| --- | --- | --- |
+| art-01-screen-inventory-final | Screens or user interaction surfaces and stable IDs | Every referenced screen/control in workflows, transitions and wireframes exists |
+| art-02-screen-transitions | Navigation, entry/exit, failure/recovery | Reachable inventory entries, correct permission guards and state conditions |
+| art-03-wireframes | Controls, content, empty/loading/error/success states | Each action has a requirement, transition and downstream sequence; no dead control |
+| art-04-functional-requirements | Purpose, beneficiary, outcomes, invariants, acceptance | Every request maps to implementation and evidence through the other affected views |
+| art-05-state-machines | Legal states, guards, terminal outcomes, retry/cancel | Sequences/events trigger legal transitions; UI messages match actual final state |
+| art-06-permissions | Actor/role, action, resource, authority boundary | UI guards, API checks, ownership and execution roles agree |
+| art-07-user-workflows | User goal, steps, completion and recovery experience | Requirements covered end to end through screens, APIs, persistence and runtime |
+| art-08-data-dictionary | Fields, meaning, type, requiredness, lifecycle and owner | API/event payloads, ER cardinality and state invariants use the same definitions |
+| art-09-sequences | Calls/events through components, errors, asynchronous completion | API names/payloads, states, authorization and deployed component boundaries agree |
+| art-10-api-design | Existing APIs, commands or file contracts, errors and compatibility | Sequence inputs/outputs, data meanings and permission checks agree |
+| art-11-er-diagram | Entities, relationships, ownership and cardinality | Dictionary and API reads/writes agree; label logical artifact models as non-DB |
+| art-12-infrastructure | Repositories, execution environments, services and trust boundaries | Every sequence participant has an actual host/owner; revision/rollout dependencies align |
+
+## Review evidence and neutral agents
+
+All reviews use independent agents/sessions, including design, cross-view
+consistency, implementation-versus-To-Be, verification changes and PR review.
+An agent must not approve work it authored. A reviewer can re-review fixes to its
+findings if it did not implement the fixes. Supply raw sources, not desired answers;
+require inspected references, discrepancies, uncertainty and a reasoned verdict.
+Use the repository-required model (gpt-5.5 / xhigh where mandated and available).
+If independent review is unavailable, report that gate as blocked.
+
+Persist a compact review receipt: reviewer/session identity, review kind, original
+request and shared baseline/To-Be references, candidate revisions, inspected views
+and evidence, findings, result, and re-review links. An independent reviewer checks:
+
+- coverage of the original request, user benefit and acceptance oracles;
+- consistency for every affected cross-view link, including unchanged neighbors;
+- behavior after actual operation, reload/session return and final persistence or
+  integration outcome where applicable;
+- implementation and tests against the proposed To-Be, not just against each other;
+- missing/extra functionality, stale evidence and unresolved historical regressions.
+
+A diagram syntax/link checker helps, but cannot replace semantic cross-view review.
+Do not declare neutral review merely by renaming the implementer's role.
+
+## SQM before and after PR creation
+
+Use the installed SQM loop skill. Respect explicit SQM opt-in, existing session and
+service authority. Explain unavailable gates; do not install global hooks, weaken
+rules, force an upload or switch organizations to obtain a pass.
+
+For each phase use fresh, separate local paths outside the diff (for example an
+ignored `.artifacts/delivery/<run>/sqm/pre-pr/` or `post-pr/` directory):
+
+```sh
+simy sqm min-check --base <actual-pr-base> --output <phase>/min.json
+simy sqm check --base <actual-pr-base> --min-result <phase>/min.json --proof <phase>/proof.json --signed-evidence <phase>/proof.json.signed.json
+```
+
+Use supported no-upload options when required by the authorized sharing scope.
+Read the proof and verify its repository, head, base, working-tree/diff identity,
+knowledge bundle version/digest and `outcome.status == passed`; verify the bound
+signature using SQM tooling. Exit zero alone is insufficient. Do not edit or commit
+between min-check and check. Pin the commit before the pre-PR check; writing proof
+into the committed diff would invalidate its identity.
+
+Before the pre-PR phase, inventory relevant known incidents from the team's shared
+incident records, SQM knowledge and repository regression history. Record incident
+or source ID, failure boundary, applicable/unaffected/unknown classification,
+regression command and result, SQM rule match/coverage, and residual gaps. Link this
+ledger from the shared specification so the next task can reuse and improve it.
+Separate confirmed incidents from synthetic risk scenarios; never invent history.
+A zero-match/no-applicable-rules proof does not establish historical coverage.
+Use concrete regressions for relevant uncovered incidents and have an independent
+reviewer assess coverage; keep missing incident history or untested boundaries
+visible. No finite test promises absence of all future bugs.
+
+Pre-PR: implementation-to-To-Be review and relevant regressions pass, then run SQM;
+repair findings within the bounded loop, re-review changed work, and rerun against
+the final candidate before creation. On unavailable/failed proof, withhold creation
+and report the exact blocker while continuing independent authorized preparation.
+
+Post-PR: fetch the actual PR head/base and check out/verify that combination, run
+both SQM phases again into new paths, inspect proof and current CI, and obtain
+independent PR/evidence review. The pre-PR proof cannot stand in for this run.
+If it fails, retain the PR as draft/not-ready with unmet gates recorded, repair and
+rerun affected independent reviews and SQM. A changed head/base/spec or relevant
+bundle invalidates affected approvals and proofs; preserve old receipts as history.
+Promote Ready only with current required gates, including applicable combined-state
+verification. Merge and deployment still require their own authority and evidence.
+
+## Team maintenance after verification
+
+Merge reviewed specification changes with the corresponding implementation through
+the normal team review process. Record proposed, implemented locally, merged and
+verified-in-environment status separately. Advance As-Is only for the revision and
+environment actually verified; a merged To-Be is not automatically production As-Is.
+Preserve the prior baseline and decisions in version history. If another change
+updates a shared view, reconcile its semantics and re-review affected links even
+when Git reports no textual conflict. Do not overwrite concurrent edits.
+
+Each run stores pointers, deltas and evidence in its receipt, not another competing
+master specification. Record unresolved drift with an owner, source and next action.
+Never lower the intended outcome merely to make an implementation match a diagram.