nccgs 2.0.0 → 2.1.1

package/docs/NCCGS-1.5.md

@@ -1,237 +1,237 @@
-> Historical development/reference document. Version, status, commands and plans
-> below describe their original scope, not the current package defaults. Read
-> [current release guidance](RELEASE-STATUS.md) before use. Research/benchmark proposals
-> do not automatically add requirements to a delivery contract.
-
-# NCCGS 1.5 preview — implementation and operation
-
-Version: **1.5.0-preview.1**. Target executor: **Claude Code**.
-This is framework functionality with synthetic regression tests, pending real-runtime
-pilot validation. Read [MEMORY.md](../MEMORY.md) before interpreting evaluation results.
-
-The 2026-10-03 phase-1 maintenance patch adds managed verification jobs and optional
-supervised headless runs. [Phase-1 operations](PHASE-1-OPERATIONS.md) supersedes the
-older manual-lock and verification-operation details below. Its scoped native
-lifecycle smoke passed; historical game evaluation results stay frozen.
-
-[Phase-2 operations](PHASE-2-OPERATIONS.md) supersedes the check-only acceptance
-examples and 4/12/24 dispatch defaults below: automatic criteria need measured
-assertions, new FAST implementation tasks have a ceiling of 6, and new ledgers
-protect repair/QA/review capacity. A real Claude coordinator smoke confirmed that
-failed synthetic criteria block a success report. This does not validate game balance.
-
-## Policies and migration
-
-New installs use `.nccgs/execution.json`:
-
-```json
-{
-  "schemaVersion": 1,
-  "name": "standalone",
-  "externalReview": { "mode": "off" },
-  "acceptanceRequired": false,
-  "requireObservedEffort": false,
-  "maxParallelWorkers": 2
-}
-```
-
-Model profile lives separately in `.nccgs/project.yaml`; the default is
-`claude-standalone`. Its Sonnet/Opus aliases are requests, never resolved observations.
-Missing execution.json resolves to compatibility. Changing a model profile alone
-does not remove an external, acceptance or historical task obligation.
-
-Use `nccgs migrate-execution --to standalone --dry-run` after a framework update;
-remove `--dry-run` to apply. Add `--model-profile claude-standalone` to explicitly
-change models too. Configuration archives live under `.nccgs/backups/execution/ID`.
-`--rollback ID --dry-run` checks restoration; rollback refuses changed configuration
-or corrupted backup hashes. Tasks/evidence/budgets are preserved. See
-[UPGRADING.md](../UPGRADING.md) for failure recovery and legacy task handling.
-
-## Intake, classification and modes
-
-Example `.nccgs/evidence/intake/hud-fix.json`:
-
-```json
-{
-  "schemaVersion": 1,
-  "objective": "Correct the pause-button offset at the declared reference resolution",
-  "mode": "implement",
-  "scope": "local",
-  "systems": ["HUD"],
-  "target": "fix",
-  "readiness": "ready",
-  "acceptance": [{ "id": "HUD-01", "description": "Offset matches the reference", "check": "layout-reference" }],
-  "requiredChecks": ["layout-reference"],
-  "requiredArtifacts": [],
-  "manualGates": [],
-  "assumptions": ["Gameplay and input behavior remain unchanged"],
-  "reassessWhen": ["The layout defect crosses multiple UI systems"]
-}
-```
-
-This is a template, not evidence that the check ran. For `audit` or `plan`, declare
-`analysisArtifacts` such as `.nccgs/evidence/analysis/TASK-result.md`; source edits
-are prohibited. Include real `sources` paths to hash authoritative documents.
-Criteria with `check` add required objective checks; `{id,description,manual:true}`
-adds a manual acceptance gate. Project-level gate manifests remain mandatory.
-
-```text
-node .claude/nccgs/tools/task.mjs init --id hud-fix --intake .nccgs/evidence/intake/hud-fix.json
-node .claude/nccgs/tools/task.mjs bind --id hud-fix --session ACTUAL_SESSION_ID
-node .claude/nccgs/tools/task.mjs inspect --id hud-fix
-```
-
-The classifier is deterministic and conservative, not a general semantic model.
-Ready/local/fix can be FAST. Unknown or feature scope defaults to STANDARD.
-Save/serialization, migration, network authority, commerce and cross-system signals
-require CONTROLLED. The coordinator must inspect real risk and supply `riskSignals`,
-reason and evidence; keyword absence is not proof of safety.
-
-Explicit `reclassify --classification FILE` requires `reason` and `evidence`; optional
-`risk`, `scope`, `target`, `readiness`, `systems` and `riskSignals` explain the change.
-To change intake content, update the same file and use `refresh-inputs --reason TEXT`.
-Reclassification invalidates affected stages while retaining old evidence and spent
-review rounds. Source/input/policy changes never reuse old approval. Execution policy
-changes cannot be adopted by input refresh: restore pinned policy for current work
-or explicitly scope new work while retaining prior history and spent budgets. Audit/plan
-baseline hashing still detects source edits after canonical inputs are refreshed.
-
-## Dispatch, budget and evidence
-
-Save a request under `.nccgs/evidence/requests/`:
-
-```json
-{
-  "requestKey": "hud-fix-implementation-1",
-  "kind": "implementation",
-  "agent": "nccgs-fast-implementer",
-  "writePaths": ["Assets/Game/UI/PauseButton.cs"],
-  "reason": "One ready local layout fix with a targeted reference check"
-}
-```
-
-```text
-node .claude/nccgs/tools/task.mjs reserve --id hud-fix --request .nccgs/evidence/requests/hud-fix.json
-```
-
-Use the returned ID in the Agent prompt prefix `[NCCGS-DISPATCH:ID]`, select the
-specified role and task route, and include contract, inputs, ownership and acceptance.
-PreToolUse claims the slot with actual session/tool-use identity. SubagentStart binds
-an unambiguous agent ID. Foreground PostToolUse completion captures final telemetry.
-For this preview use foreground calls; background runs hold slots until correlated
-final evidence or external reconciliation. SubagentStop alone cannot prove model,
-effort or complete usage. Ambiguous same-role starts are not guessed.
-
-Review requests use `kind: "review"`, `agent: "nccgs-adversarial-reviewer"`, and
-empty writePaths. Analysis requests also have no source ownership. Dispatch ceilings
-are 4/12/24 for FAST/STANDARD/CONTROLLED by default; first reservation may explicitly
-set `limits.maxDispatches`, `maxDurationMs`, `maxCostUsd`. Limits are pinned, counted
-across descendants, and cannot be raised by another reservation. Review limits are
-2/3/3. Failed, cancelled and uncertain attempts remain spent. Extensions of review
-rounds require a reasoned external operator decision and never grant approval.
-
-At most two implementation workers can reserve disjoint paths; review/analysis
-cannot overlap source writers. Direct edit tools enforce ownership. Opaque shell/MCP
-operations are not OS-sandboxed by NCCGS; inspect their actual diff and test effects.
-Audit/plan/review block arbitrary shells and unknown tools. Use read tools, declared
-analysis artifacts and externally supplied command evidence when required.
-
-`task verify --id TASK --name CHECK -- EXECUTABLE ARGS` records the actual command,
-exit code, bounded timeout, log hash and before/after source snapshot. Claude may
-run it only for implementation tasks. The verifier must not change source.
-`task ref --file PATH` produces a `{path,sha256}` reference without inventing evidence.
-
-Record a completed work stage with a JSON payload (placeholders below must be
-replaced with returned values, never copied as observations):
-
-```json
-{
-  "snapshot": "ACTUAL_FINAL_SNAPSHOT",
-  "dispatchId": "ACTUAL_COMPLETED_DISPATCH_ID",
-  "runtime": { "path": ".nccgs/evidence/runtime/observations/ACTUAL.json", "sha256": "ACTUAL_HASH" },
-  "checks": [{ "name": "layout-reference", "status": "PASS", "evidence": { "path": ".nccgs/evidence/ACTUAL-check.json", "sha256": "ACTUAL_HASH" } }]
-}
-```
-
-Use `record --id TASK --stage implementation --evidence FILE`. Audit/plan use stage
-`analysis` and include `evidence` referencing the declared result artifact. Each
-accepted work/review dispatch can be consumed once, including across history.
-
-Review payload adds `verdict` (`PASS|CHANGES_REQUIRED|BLOCKED`), `criteriaMet`,
-`findings`, and a review-artifact `evidence` ref to snapshot/dispatchId/runtime.
-Findings include `severity` (`BLOCKER|HIGH|MEDIUM|LOW|INFO`), `status`
-(`OPEN|RESOLVED|ACCEPTED`) and `description`. An unresolved BLOCKER/HIGH or unmet
-required criterion prevents internal PASS. Review identity must differ from work.
-
-## Reporting, external review and closure
-
-```text
-node .claude/nccgs/tools/task.mjs report --id TASK --outcome blocked --summary "Actual blocker and missing evidence"
-node .claude/nccgs/tools/task.mjs check --id TASK --target done
-node .claude/nccgs/tools/task.mjs close --id TASK
-```
-
-Reports accept `success|partial|blocked|failed` even when successful closure is
-unavailable. Generated Markdown includes evidence status and unresolved gates.
-`record --stage report` can supply `artifacts` refs for required closure outputs.
-Success wording does not override failed checks. Only `close` with all current gates
-passing establishes DONE. `inspect` remains usable with changed/malformed policy.
-
-`export-external --out .nccgs/evidence/external/requests/UNIQUE.json` writes an
-immutable task/contract/snapshot packet. An external actor reviews it and imports
-a receipt through `import-external --file FILE` outside the Claude executor:
-
-```json
-{
-  "schemaVersion": 1,
-  "id": "REVIEW_ID",
-  "taskId": "TASK",
-  "contractHash": "EXPORTED_HASH",
-  "snapshot": "EXPORTED_SNAPSHOT",
-  "actor": "ACTUAL_EXTERNAL_REVIEWER",
-  "verdict": "PASS",
-  "findings": [],
-  "reviewedAt": "ACTUAL_ISO_TIMESTAMP",
-  "source": "ACTUAL_REVIEW_REFERENCE"
-}
-```
-
-Off ignores external closure dependency. Advisory retains current findings without
-blocking. Required evaluates all active current receipts; a later empty PASS cannot
-erase earlier blocking findings. To replace a prior decision, include
-`supersedes: ["PRIOR_RECEIPT_ID"]` and `supersessionReason` identifying the new
-evidence. Old findings remain traceable. Stale/duplicate/malformed receipts fail.
-
-If acceptance is required, an external Product Owner decision references taskId,
-contractHash, snapshot, `actor: "Product Owner"`, `decision: "ACCEPTED"`, decidedAt,
-statement, reference and each manual gate `{id,decision:"ACCEPTED",reference}`.
-Import via `record --stage acceptance` with its evidence ref. Claude cannot accept
-on the user's behalf. NCCGS neither launches Astra nor sends external messages.
-
-## Recovery and telemetry
-
-Use `checkpoint --reason TEXT`, `resume`, `dispatch-status` and `telemetry` with
-`--id TASK`. Resume preserves reservations, findings, attempts and budgets. A lost
-callback or dead worker does not refund a slot by timeout. An external operator can
-use `dispatch-reconcile --dispatch ID --request FILE` with `status: failed|cancelled`,
-reason and observed reference after confirming the process is no longer running.
-Never manually reset the ledger. Missing initialized history or altered durable
-evidence fails closed. A crashed lock requires operator inspection before recovery.
-
-Telemetry reports known subtotals and coverage for duration, tool calls, tokens and
-cost. Total is null if any started attempt lacks that metric. Observed zero remains
-zero. These are worker measurements; coordinator work, human delay and billing are
-not automatically covered. A configured spend/time ceiling cannot interrupt an
-already running provider request and refuses new dispatch with unknown measurements.
-
-Native capture follows the documented Claude Code [hook inputs and Agent tool
-response](https://code.claude.com/docs/en/hooks): resolvedModel/modelsUsed and native
-duration/token/tool-use fields when present. It does not invent effort or cost.
-Actual field availability and correlation must be confirmed by the real pilot.
-
-## Release boundary
-
-Framework tests and the synthetic five-size benchmark validate mechanics. They
-cannot measure model reasoning, game quality or end-to-end team productivity.
-Use [the pilot protocol](NCCGS-1.5-PILOT.md) before stable promotion. CP0 remains
-reference-only; it is not a valid scored run for this purpose.
+> Historical development/reference document. Version, status, commands and plans
+> below describe their original scope, not the current package defaults. Read
+> [current release guidance](RELEASE-STATUS.md) before use. Research/benchmark proposals
+> do not automatically add requirements to a delivery contract.
+
+# NCCGS 1.5 preview — implementation and operation
+
+Version: **1.5.0-preview.1**. Target executor: **Claude Code**.
+This is framework functionality with synthetic regression tests, pending real-runtime
+pilot validation. Read [MEMORY.md](../MEMORY.md) before interpreting evaluation results.
+
+The 2026-10-03 phase-1 maintenance patch adds managed verification jobs and optional
+supervised headless runs. [Phase-1 operations](PHASE-1-OPERATIONS.md) supersedes the
+older manual-lock and verification-operation details below. Its scoped native
+lifecycle smoke passed; historical game evaluation results stay frozen.
+
+[Phase-2 operations](PHASE-2-OPERATIONS.md) supersedes the check-only acceptance
+examples and 4/12/24 dispatch defaults below: automatic criteria need measured
+assertions, new FAST implementation tasks have a ceiling of 6, and new ledgers
+protect repair/QA/review capacity. A real Claude coordinator smoke confirmed that
+failed synthetic criteria block a success report. This does not validate game balance.
+
+## Policies and migration
+
+New installs use `.nccgs/execution.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "standalone",
+  "externalReview": { "mode": "off" },
+  "acceptanceRequired": false,
+  "requireObservedEffort": false,
+  "maxParallelWorkers": 2
+}
+```
+
+Model profile lives separately in `.nccgs/project.yaml`; the default is
+`claude-standalone`. Its Sonnet/Opus/Fable aliases are requests, never resolved observations.
+Missing execution.json resolves to compatibility. Changing a model profile alone
+does not remove an external, acceptance or historical task obligation.
+
+Use `nccgs migrate-execution --to standalone --dry-run` after a framework update;
+remove `--dry-run` to apply. Add `--model-profile claude-standalone` to explicitly
+change models too. Configuration archives live under `.nccgs/backups/execution/ID`.
+`--rollback ID --dry-run` checks restoration; rollback refuses changed configuration
+or corrupted backup hashes. Tasks/evidence/budgets are preserved. See
+[UPGRADING.md](../UPGRADING.md) for failure recovery and legacy task handling.
+
+## Intake, classification and modes
+
+Example `.nccgs/evidence/intake/hud-fix.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "objective": "Correct the pause-button offset at the declared reference resolution",
+  "mode": "implement",
+  "scope": "local",
+  "systems": ["HUD"],
+  "target": "fix",
+  "readiness": "ready",
+  "acceptance": [{ "id": "HUD-01", "description": "Offset matches the reference", "check": "layout-reference" }],
+  "requiredChecks": ["layout-reference"],
+  "requiredArtifacts": [],
+  "manualGates": [],
+  "assumptions": ["Gameplay and input behavior remain unchanged"],
+  "reassessWhen": ["The layout defect crosses multiple UI systems"]
+}
+```
+
+This is a template, not evidence that the check ran. For `audit` or `plan`, declare
+`analysisArtifacts` such as `.nccgs/evidence/analysis/TASK-result.md`; source edits
+are prohibited. Include real `sources` paths to hash authoritative documents.
+Criteria with `check` add required objective checks; `{id,description,manual:true}`
+adds a manual acceptance gate. Project-level gate manifests remain mandatory.
+
+```text
+node .claude/nccgs/tools/task.mjs init --id hud-fix --intake .nccgs/evidence/intake/hud-fix.json
+node .claude/nccgs/tools/task.mjs bind --id hud-fix --session ACTUAL_SESSION_ID
+node .claude/nccgs/tools/task.mjs inspect --id hud-fix
+```
+
+The classifier is deterministic and conservative, not a general semantic model.
+Ready/local/fix can be FAST. Unknown or feature scope defaults to STANDARD.
+Save/serialization, migration, network authority, commerce and cross-system signals
+require CONTROLLED. The coordinator must inspect real risk and supply `riskSignals`,
+reason and evidence; keyword absence is not proof of safety.
+
+Explicit `reclassify --classification FILE` requires `reason` and `evidence`; optional
+`risk`, `scope`, `target`, `readiness`, `systems` and `riskSignals` explain the change.
+To change intake content, update the same file and use `refresh-inputs --reason TEXT`.
+Reclassification invalidates affected stages while retaining old evidence and spent
+review rounds. Source/input/policy changes never reuse old approval. Execution policy
+changes cannot be adopted by input refresh: restore pinned policy for current work
+or explicitly scope new work while retaining prior history and spent budgets. Audit/plan
+baseline hashing still detects source edits after canonical inputs are refreshed.
+
+## Dispatch, budget and evidence
+
+Save a request under `.nccgs/evidence/requests/`:
+
+```json
+{
+  "requestKey": "hud-fix-implementation-1",
+  "kind": "implementation",
+  "agent": "nccgs-fast-implementer",
+  "writePaths": ["Assets/Game/UI/PauseButton.cs"],
+  "reason": "One ready local layout fix with a targeted reference check"
+}
+```
+
+```text
+node .claude/nccgs/tools/task.mjs reserve --id hud-fix --request .nccgs/evidence/requests/hud-fix.json
+```
+
+Use the returned ID in the Agent prompt prefix `[NCCGS-DISPATCH:ID]`, select the
+specified role and task route, and include contract, inputs, ownership and acceptance.
+PreToolUse claims the slot with actual session/tool-use identity. SubagentStart binds
+an unambiguous agent ID. Foreground PostToolUse completion captures final telemetry.
+For this preview use foreground calls; background runs hold slots until correlated
+final evidence or external reconciliation. SubagentStop alone cannot prove model,
+effort or complete usage. Ambiguous same-role starts are not guessed.
+
+Review requests use `kind: "review"`, `agent: "nccgs-adversarial-reviewer"`, and
+empty writePaths. Analysis requests also have no source ownership. Dispatch ceilings
+are 4/12/24 for FAST/STANDARD/CONTROLLED by default; first reservation may explicitly
+set `limits.maxDispatches`, `maxDurationMs`, `maxCostUsd`. Limits are pinned, counted
+across descendants, and cannot be raised by another reservation. Review limits are
+2/3/3. Failed, cancelled and uncertain attempts remain spent. Extensions of review
+rounds require a reasoned external operator decision and never grant approval.
+
+At most two implementation workers can reserve disjoint paths; review/analysis
+cannot overlap source writers. Direct edit tools enforce ownership. Opaque shell/MCP
+operations are not OS-sandboxed by NCCGS; inspect their actual diff and test effects.
+Audit/plan/review block arbitrary shells and unknown tools. Use read tools, declared
+analysis artifacts and externally supplied command evidence when required.
+
+`task verify --id TASK --name CHECK -- EXECUTABLE ARGS` records the actual command,
+exit code, bounded timeout, log hash and before/after source snapshot. Claude may
+run it only for implementation tasks. The verifier must not change source.
+`task ref --file PATH` produces a `{path,sha256}` reference without inventing evidence.
+
+Record a completed work stage with a JSON payload (placeholders below must be
+replaced with returned values, never copied as observations):
+
+```json
+{
+  "snapshot": "ACTUAL_FINAL_SNAPSHOT",
+  "dispatchId": "ACTUAL_COMPLETED_DISPATCH_ID",
+  "runtime": { "path": ".nccgs/evidence/runtime/observations/ACTUAL.json", "sha256": "ACTUAL_HASH" },
+  "checks": [{ "name": "layout-reference", "status": "PASS", "evidence": { "path": ".nccgs/evidence/ACTUAL-check.json", "sha256": "ACTUAL_HASH" } }]
+}
+```
+
+Use `record --id TASK --stage implementation --evidence FILE`. Audit/plan use stage
+`analysis` and include `evidence` referencing the declared result artifact. Each
+accepted work/review dispatch can be consumed once, including across history.
+
+Review payload adds `verdict` (`PASS|CHANGES_REQUIRED|BLOCKED`), `criteriaMet`,
+`findings`, and a review-artifact `evidence` ref to snapshot/dispatchId/runtime.
+Findings include `severity` (`BLOCKER|HIGH|MEDIUM|LOW|INFO`), `status`
+(`OPEN|RESOLVED|ACCEPTED`) and `description`. An unresolved BLOCKER/HIGH or unmet
+required criterion prevents internal PASS. Review identity must differ from work.
+
+## Reporting, external review and closure
+
+```text
+node .claude/nccgs/tools/task.mjs report --id TASK --outcome blocked --summary "Actual blocker and missing evidence"
+node .claude/nccgs/tools/task.mjs check --id TASK --target done
+node .claude/nccgs/tools/task.mjs close --id TASK
+```
+
+Reports accept `success|partial|blocked|failed` even when successful closure is
+unavailable. Generated Markdown includes evidence status and unresolved gates.
+`record --stage report` can supply `artifacts` refs for required closure outputs.
+Success wording does not override failed checks. Only `close` with all current gates
+passing establishes DONE. `inspect` remains usable with changed/malformed policy.
+
+`export-external --out .nccgs/evidence/external/requests/UNIQUE.json` writes an
+immutable task/contract/snapshot packet. An external actor reviews it and imports
+a receipt through `import-external --file FILE` outside the Claude executor:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "REVIEW_ID",
+  "taskId": "TASK",
+  "contractHash": "EXPORTED_HASH",
+  "snapshot": "EXPORTED_SNAPSHOT",
+  "actor": "ACTUAL_EXTERNAL_REVIEWER",
+  "verdict": "PASS",
+  "findings": [],
+  "reviewedAt": "ACTUAL_ISO_TIMESTAMP",
+  "source": "ACTUAL_REVIEW_REFERENCE"
+}
+```
+
+Off ignores external closure dependency. Advisory retains current findings without
+blocking. Required evaluates all active current receipts; a later empty PASS cannot
+erase earlier blocking findings. To replace a prior decision, include
+`supersedes: ["PRIOR_RECEIPT_ID"]` and `supersessionReason` identifying the new
+evidence. Old findings remain traceable. Stale/duplicate/malformed receipts fail.
+
+If acceptance is required, an external Product Owner decision references taskId,
+contractHash, snapshot, `actor: "Product Owner"`, `decision: "ACCEPTED"`, decidedAt,
+statement, reference and each manual gate `{id,decision:"ACCEPTED",reference}`.
+Import via `record --stage acceptance` with its evidence ref. Claude cannot accept
+on the user's behalf. NCCGS neither launches Astra nor sends external messages.
+
+## Recovery and telemetry
+
+Use `checkpoint --reason TEXT`, `resume`, `dispatch-status` and `telemetry` with
+`--id TASK`. Resume preserves reservations, findings, attempts and budgets. A lost
+callback or dead worker does not refund a slot by timeout. An external operator can
+use `dispatch-reconcile --dispatch ID --request FILE` with `status: failed|cancelled`,
+reason and observed reference after confirming the process is no longer running.
+Never manually reset the ledger. Missing initialized history or altered durable
+evidence fails closed. A crashed lock requires operator inspection before recovery.
+
+Telemetry reports known subtotals and coverage for duration, tool calls, tokens and
+cost. Total is null if any started attempt lacks that metric. Observed zero remains
+zero. These are worker measurements; coordinator work, human delay and billing are
+not automatically covered. A configured spend/time ceiling cannot interrupt an
+already running provider request and refuses new dispatch with unknown measurements.
+
+Native capture follows the documented Claude Code [hook inputs and Agent tool
+response](https://code.claude.com/docs/en/hooks): resolvedModel/modelsUsed and native
+duration/token/tool-use fields when present. It does not invent effort or cost.
+Actual field availability and correlation must be confirmed by the real pilot.
+
+## Release boundary
+
+Framework tests and the synthetic five-size benchmark validate mechanics. They
+cannot measure model reasoning, game quality or end-to-end team productivity.
+Use [the pilot protocol](NCCGS-1.5-PILOT.md) before stable promotion. CP0 remains
+reference-only; it is not a valid scored run for this purpose.