nccgs 1.3.0 → 2.0.0-rc.2

package/.claude/nccgs/protocols/standalone.md

@@ -0,0 +1,187 @@
+# Standalone Claude Code execution — 2.0 RC
+
+Read `.claude/nccgs/MEMORY.md`. NCCGS means New Claude Code Game Studio. Only
+real Claude Code execution supplies NCCGS orchestration evidence. Codex maintenance,
+synthetic tests, installed files and requested model aliases do not prove it.
+
+Read [task autonomy](task-autonomy.md). The task authorizes necessary shell commands,
+reports and outside-project operations without asking again. Start with `nccgs run`
+to activate native permissions; execution mode and evidence gates remain separate.
+
+## Select obligations before models
+
+`.nccgs/execution.json` selects standalone or compatibility, external review
+`off|advisory|required`, acceptance, observed-effort requirements and worker limit.
+`.nccgs/project.yaml` selects the model profile independently. Missing execution
+configuration means compatibility; never silently relax existing gates. New
+installs use standalone and `claude-standalone`. Astra is an optional reviewer.
+Policy and input hashes are pinned per task. Changed inputs require an explicit
+refresh/reclassification with invalidation. Changed execution policy requires
+restoring the pinned configuration for current work or explicitly scoped new work;
+preserve prior history and spent budgets. No prior approval carries over.
+
+## Intake and mode
+
+For `/design`, `/design-review` and `/story-readiness`, also follow the
+[design lifecycle](design-lifecycle.md). Before dependent feature implementation,
+use its reviewed design handoff. New installs require this through execution policy;
+a self-declared readiness value alone is insufficient. `task design-validate`
+checks document structure; the independent designer/reviewer process owns semantics.
+
+Use [delivery acceptance](delivery-acceptance.md) to distinguish implementing the
+brief from bot performance and product-specific balance research. Keep research
+questions outside delivery gates unless the task itself explicitly requests that
+research deliverable. Preserve fixed rules and concrete acceptance in the brief.
+
+Use `implement` for requested changes, `audit` for examination, and `plan` for
+design/planning. `/audit`, `/review`, diagnostic and specialist audit/review commands
+default to audit; `/design`, `/plan-feature`, `/qa-plan`, `/sprint-plan` default to
+plan. `/status` reads state without dispatch. Other entrypoints follow the user's
+requested outcome; never turn a review into a fix without authorization.
+
+Write a bounded intake JSON under `.nccgs/evidence/intake/` with `objective`,
+`mode`, `scope` (`local|feature|cross-system`), `systems`, `target`
+(`fix|learning-prototype|alpha-ready|production-change`), `readiness`
+(`ready|needs-inspection|needs-product-decision`), acceptance criteria,
+`requiredChecks`, `requiredArtifacts`, and `manualGates`. Audit/plan outputs belong
+only to explicitly listed `analysisArtifacts` under `.nccgs/evidence/analysis/`.
+Use `riskSignals` for discovered compatibility, security and other critical risks.
+Do not request irrelevant tests or multiple reviewers merely to fill a template.
+Map automatic criteria to JSON measurement assertions, including assistance/rule
+changes when natural gameplay is required. A check name or helper exit 0 alone is
+not acceptance. Mark only a small, actual delivery prerequisite `checkpoint: "early"`;
+do not make feature expansion depend on bot survival, victory or balance. Put late
+integration checks in final acceptance when independent work can proceed.
+Read `task acceptance-status`; preserve
+FAIL/UNVERIFIED and missing evidence in partial reports. Exact fields and examples
+are in [phase-2 operations](../../../docs/PHASE-2-OPERATIONS.md).
+
+Initialize and bind through the CLI:
+
+```text
+node .claude/nccgs/tools/task.mjs init --id TASK --intake .nccgs/evidence/intake/TASK.json
+node .claude/nccgs/tools/task.mjs bind --id TASK --session SESSION_ID
+node .claude/nccgs/tools/task.mjs inspect --id TASK
+```
+
+The rule-based classifier chooses a conservative tier with reasons and evidence;
+it is not a semantic oracle. Inspect the result. Unknown scope stays STANDARD;
+save/migration/authority/commerce/cross-system signals require CONTROLLED. Any
+override needs evidence and a reason. Reclassify when facts change, preserving
+spent review rounds, dispatches and history. Substantial product ambiguity blocks
+dependent work; independent inspection may proceed.
+
+## Reserve, execute, verify, review
+
+The main Claude Code session coordinates. Reserve every worker before invoking
+Agent; do not delegate recursively. A reservation request contains a stable
+`requestKey`, `kind` (`implementation|analysis|review`), known `agent`, concrete
+`reason`, and explicit `writePaths` (empty for analysis/review). Save requests under
+`.nccgs/evidence/requests/`. Use the returned reservation ID once:
+
+```text
+node .claude/nccgs/tools/task.mjs reserve --id TASK --request .nccgs/evidence/requests/TASK-work.json
+```
+
+Prefix the Agent prompt with `[NCCGS-DISPATCH:RETURNED_ID]`. Include the task's
+contract, route, owned paths, acceptance criteria and expected bounded handoff.
+The pre-tool hook claims the reservation using the actual session/tool-use ID.
+Use foreground Agent calls for this preview. Launch distinct roles sequentially
+through their start hooks; ambiguous start identities must not be guessed.
+Background Agent/Task calls are rejected.
+`nccgs run` also sets `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` to prevent native
+auto-backgrounding; an omitted `run_in_background` flag alone is insufficient.
+Launch one Agent call per coordinator message and wait for its final result before
+starting another. Do not mutate a dispatch from uncertain to running to bypass this.
+The environment setting also disables native background Bash tasks; use managed
+verification jobs or explicitly tracked bounded collectors for long-running checks.
+See https://code.claude.com/docs/en/env-vars for the native setting.
+For required handoff documents, declare
+fresh `handoffPaths` under `.nccgs/evidence/analysis/` in the reservation. Invocation
+completion with missing declared artifacts cannot satisfy a work stage; undeclared
+handoffs are unassessed, not automatically complete.
+Use the risk-selected implementation model/effort and configured review model.
+Aliases are requests; only resolved Claude model observations count as evidence.
+
+At most two implementation workers may run with disjoint path ownership. Review
+and analysis hold a stable source snapshot and cannot overlap writers. The review
+slot is unique per task. Failed/cancelled attempts still consume quota, including
+ancestor quota for child tasks. Do not split tasks to mint budget.
+New implementation budgets protect initial review plus one repair, read-only QA and
+re-review within the total cap. Use `purpose: "repair"` only against recorded negative
+feedback; `purpose: "qa"` is a read-only QA/verification dispatch. Ordinary delivery
+cannot consume the protected tail. Inspect `dispatch-status.deliveryBudget` and stop
+expansion before it runs out; more review rounds do not create more dispatch slots.
+
+Fresh repair reservations require a pinned `workPacket`, 1–4 exact existing source
+files and one fresh handoff path. Choose the correction before reserving; do not
+send an open-ended tuning investigation. `task dispatch-prompt --id TASK --dispatch ID`
+returns the bounded assignment; the launch hook injects the same prompt. Repair
+workers have at most 12 work tool calls (6 reads), 3 separate handoff writes and a
+10-minute tool-admission deadline. Shell/MCP/web/delegation are blocked for these
+workers. The coordinator runs declared checks after return. See
+[bounded repair](bounded-repair.md) for packet fields and limitations.
+These limits do not add native turns or reset dispatch quota.
+
+Use targeted objective checks appropriate to the request. The coordinator's
+`task verify` owns the command and captures a receipt on the first execution. For
+long commands use `--request-key ATTEMPT --background`; retain the returned job ID
+and use `job-status` or bounded `job-wait`. Reuse its receipt for QA and closure;
+do not rerun successful checks just to capture evidence. A helper's arguments after
+`--` belong to the helper, including its own `--project`. Audit/plan/review
+workers use read tools and declared analysis artifacts; arbitrary shell and unknown
+MCP tools are blocked. If a required analysis check needs command execution,
+provide externally run evidence or start a separately authorized implementation
+task. Do not loosen mode simply to bypass the guard.
+
+Record implementation/analysis with its completed `dispatchId`, current snapshot,
+checks, artifacts and captured runtime observation. Record independent review with
+a fresh completed review dispatch and explicit verdict/findings. The same dispatch
+cannot be consumed twice. Read `task inspect` and the task-gates schema documentation
+for exact payload fields in [standalone gates](standalone-gates.md). Missing observations block the relevant stage; never
+author runtime evidence to make it pass.
+
+## Report and stop
+
+Always permit an honest report outcome: `success`, `partial`, `blocked` or `failed`.
+Keep unresolved findings, absent tests, missing measurements and required decisions
+visible. Reporting does not imply DONE. Successful closure checks the final source,
+contract, verification, independent review, required artifacts and configured
+external/manual/acceptance gates. Stop once these gates pass; repeat work only for
+changed inputs, new findings or failed evidence.
+
+External review is file based. `off` adds no dependency. `advisory` retains findings
+without gating closure. `required` gates closure with a receipt tied to task,
+contract and source snapshot. External actors import their own decisions outside
+Claude. NCCGS does not launch Astra or send messages to another service.
+
+## Resume and evidence limits
+
+Use `checkpoint`, `resume`, `dispatch-status` and `telemetry`; do not edit task or
+ledger JSON. A background launch, missing callback or crashed worker retains its
+slot. Only correlated final provider evidence or external reconciliation releases
+it. No lease timeout refunds attempts. New local locks can recover only after the
+owner and all managed command descendants are verified dead, with an audit entry.
+Legacy/malformed/remote locks and uncertain spawn windows still need inspection.
+Restore missing/corrupt ledger
+history from a known checkpoint; never initialize a replacement to reset budgets.
+
+Native hooks observe resolved models and selected usage fields when Claude Code
+actually provides them. They do not prove effort when no effort field is available.
+Unknown values remain null with coverage; they are never zero-cost measurements.
+Time/token/cost summaries cover observed worker attempts, not unmeasured coordinator
+work, human waiting, account-wide spend or provider billing. Monetary/duration
+limits with missing measurements fail closed before another dispatch, but cannot
+interrupt a provider request already running. Hooks are workflow controls, not a
+hostile-code filesystem sandbox: shell/MCP writers still require independent diff
+review and objective checks.
+
+The optional external `nccgs run --supervise` launcher waits for managed jobs and
+performs bounded same-session continuation with cumulative cost tracking. It cannot
+invent missing native usage or release uncertain provider dispatches. A supervised
+session may yield while that external owner waits; an unsupervised premature Stop
+receives a bounded reminder to collect pending jobs. DONE still rejects pending jobs.
+
+This preview is ready for a fresh Claude Code pilot after framework fixture tests.
+It is not a completed real-runtime benchmark. Contaminated Vector Survivors CP0
+must not be scored or presented as an independent NCCGS implementation.

package/.claude/nccgs/protocols/task-autonomy.md

@@ -0,0 +1,55 @@
+# Task autonomy
+
+An NCCGS assignment preauthorizes the ordinary actions needed to finish that task:
+implementation, testing, tool execution, Bash/PowerShell, report generation,
+temporary files and required operations outside the Unity/project directory.
+Do not ask again merely because a command writes a report, uses shell redirection,
+changes directory, invokes an installed tool elsewhere, or accesses an authorized
+external task output. Choose routine implementation details and continue to a
+tested result and an honest report. Ask for missing requirements only when they
+cannot be resolved from the task; do not disguise a repeated permission request
+as clarification.
+
+## Activate the native session
+
+The external user/operator starts `nccgs run --project PATH -- [Claude arguments]`.
+With `.nccgs/autonomy.json` mode `full`, the launcher passes Claude Code's supported
+`--permission-mode bypassPermissions` and inherits installed tools and model routes.
+It does not install a restrictive Bash allowlist. The native mode cannot reliably
+be activated by a project `permissions.defaultMode` setting in current Claude Code.
+An already-running session must be resumed through the launcher by its external
+operator; do not nest another Claude CLI to change your own permissions.
+
+New installations select `full`. Updates preserve the recorded setting, and older
+installations without this file retain `guarded` until the owner requests
+`update --autonomy full`. `guarded` uses native default permissions. Installation
+or configuration alone is not evidence that a session executed in the selected mode.
+
+## Scope and evidence
+
+Task authority covers the assigned objective, including its external paths. Use
+the existing reserved implementation worker for shell operations outside the
+project; no extra user approval is needed for the location. Declare its intended
+external outputs in the dispatch prompt and handoff. Do not overlap other writers.
+Audit/plan/review source restrictions, dispatch budgets and independent review stay
+effective. The coordinator can record reports through the task CLI, including
+quoted semicolons and multiline summary text. When outside the project, use the
+absolute task CLI path and `--project` pointing to the original project.
+
+Hooks remain anchored to the starting project so external commands do not move
+the ledger, bypass gates or lose provider observations. External files are not
+automatically included in the project source snapshot: copy required evidence
+into `.nccgs/evidence/` and record its source path/hash. Do not claim external
+source coverage or performance merely because the shell command returned zero.
+
+This mode does not disable destructive-action guards, vendored-skill protection,
+immutable evidence, external sign-off requirements, or DONE checks. It does not
+turn a missing test into PASS or authorize an unrelated change. Explicit deny/ask
+rules and organization, OS and sandbox restrictions can still block an operation.
+Report the actual restriction; do not claim unrestricted machine access or try
+another command solely to evade a rejection. No user/global Claude settings are
+rewritten by the launcher.
+
+Wait for launched verification jobs and collect their actual result before ending
+a print-mode session. Task autonomy does not fix the provider's background-job
+lifetime or make a pending job complete.

package/.claude/nccgs/protocols/task-gates.md

@@ -1,5 +1,9 @@
 # Executable task gates
 
+This document specifies compatibility/schema-1 gates. For standalone/schema-2
+contracts and payloads use [the standalone gate guide](standalone-gates.md) and
+[standalone execution](standalone.md). Existing tasks retain their original gates.
+
 Run the installed tool as `node .claude/nccgs/tools/task.mjs COMMAND ...`, or use
 `nccgs task COMMAND ...`. Paths in evidence are project-relative POSIX paths.
 
@@ -9,17 +13,24 @@ Run the installed tool as `node .claude/nccgs/tools/task.mjs COMMAND ...`, or us
    to the hash of the reviewed project.yaml. A missing/stale mapping blocks task init.
    Optional `--requirements FILE.json` adds the same arrays for this task. These
    manifests are hashed; changing obligations invalidates the current task.
-2. `task init --id feature-1 --plan .nccgs/features/feature-1.md` creates a task.
+2. `task init --id feature-1 --plan .nccgs/features/feature-1.md --risk STANDARD`
+   creates a task. Risk is FAST, STANDARD, or CONTROLLED; omission defaults to
+   STANDARD. The task pins `risk`, `implementationRoute` (class/model/effort), and
+   `reviewBudget` (`used`, `limit`, `extensions`) from `contract.taskTiers`.
 3. `task bind --id feature-1 --session SESSION_ID` connects hook telemetry to it.
 4. `task snapshot` prints the current source fingerprint. It covers files, names,
-   additions, and deletions, including untracked files. Only the top-level generated
-   directories listed in pipeline.json are excluded. The plan and evidence files
-   are separately hashed. Never place source or canon in an excluded directory.
+   additions, and deletions, including untracked files. Top-level generated roots
+   in pipeline.json and explicit Build/Builds output subdirectories from
+   `.nccgs/inputs.json` are excluded. Requirements, decisions and registered canon
+   are pinned separately and included in the snapshot. The plan and evidence files
+   retain their own hashes. Never place source or canon in an excluded directory.
 5. `task ref --file .nccgs/evidence/check.log` prints a `{path, sha256}` reference.
 6. `task record --id feature-1 --stage implementation --evidence .nccgs/evidence/implementation.json`
    records implementation with `snapshot`, `runtime` (artifact reference), and
    nonempty `checks: [{name, status: "PASS", evidence: {path, sha256}}]`.
-7. Record `review` with `snapshot`, `runtime`, `verdict`, `criteriaMet`, `findings`
+7. Run `task check --id feature-1 --target review` before invoking Fable; proceed
+   only when allowed. The bound-task pre-agent guard also checks readiness and
+   remaining rounds. Record `review` with `snapshot`, `runtime`, `verdict`, `criteriaMet`, `findings`
    (each has severity/status), and `evidence` referencing the independent review.
    Only PASS with criteriaMet true and no unresolved BLOCKER/HIGH unlocks reporting.
    Corrections require fresh implementation evidence and independent review.
@@ -38,12 +49,50 @@ Run the installed tool as `node .claude/nccgs/tools/task.mjs COMMAND ...`, or us
 11. `task check --id feature-1 --target done` and `task close --id feature-1` enforce
     the entire chain. Changed source, plan, policy, or evidence invalidates old gates.
 
-Recording an upstream stage clears every downstream stage and preserves history.
+Initialize once; remediation stays on the same task. Recording an upstream stage
+clears every downstream stage and preserves history.
+It does not reset the review-round counter.
 The `check` command is read-only. A failed check exits nonzero and names the blocker.
 Stop-hook DONE checks are supplemental; task close is the canonical closing action.
 Waiting for Astra or the user is a valid stopping point, not a reason to keep an
 agent running. Do not write task JSON or external approvals through Write/Edit.
 
+## Review rounds and explicit extension
+
+The default limits are FAST 2, STANDARD 3, and CONTROLLED 3 recorded review rounds.
+Each valid review record consumes one round, including CHANGES_REQUIRED or BLOCKED.
+Malformed records or invalid runtime evidence are rejected without consuming a
+round. A PASS at the limit can proceed; the limit blocks the next review, not an
+already valid result. `task check` reports used, limit, and remaining rounds.
+
+Keep only one Fable review in flight per task; do not launch concurrent duplicate
+reviewers. The pre-dispatch guard checks the current recorded budget but does not
+reserve a round. Enforced limits count accepted review records, not parallel model
+invocations, tokens, or cost. The single-review-in-flight rule is orchestration
+policy, not an atomic execution cap.
+
+When no usable PASS remains and the budget is exhausted, stop with the current
+evidence, unresolved findings, and next decision. Do not silently reset the task,
+lower its risk, waive findings, or treat exhaustion as success. Re-recording
+implementation preserves the counter even though it clears stale review stages.
+
+After an explicit decision, an external operator can run:
+
+```text
+task extend-review --id feature-1 --reason "Approved another round to verify the save migration fix" --rounds 1
+```
+
+Use the command prefix described above. `--reason` must be nonempty; `--rounds`
+must be a positive integer no greater than that tier's base limit per extension.
+The command refuses a Claude Code session environment and records the timestamp,
+reason, added rounds, old/new limits, and history event. An extension authorizes
+more review attempts, not new product scope or acceptance. It does not supply PASS.
+
+Context and elapsed-time budgets are advisory planning limits. Review-round counts
+are enforced by the task tool. Older tasks without risk, route, or review budget
+must be replaced with a new task and fresh stage evidence; old sign-offs do not
+silently carry over. Preserve the old record as history.
+
 ## Runtime observations
 
 Agent lifecycle and Agent-tool hooks capture available native model telemetry,
@@ -58,7 +107,24 @@ taskId, snapshot, capturedAt, sessionId, agentId, observedModel, observedEffort,
 modelsUsed (if swapped), status `completed`, and provenance with kind `provider-log`
 or `operator-observation` and a nonempty reference. It must describe the actual run,
 not settings or the agent's requested model. The tool hashes the source and emits
-an observation reference for the stage record. Unknown effort remains blocked.
+an observation reference for the stage record. Both observation and raw bytes are
+stored under `.nccgs/evidence/runtime/` and must accompany a clean project copy.
+Unknown effort remains blocked. Use `task migrate-evidence --id ID` to copy existing
+legacy runtime evidence without deleting originals or changing run metadata.
+
+## Input freshness and bounded verification
+
+Before init, map all governing inputs in `.nccgs/inputs.json`; requirements.yaml
+and the decisions tree are always pinned. JSON mapping is explicit: arbitrary
+YAML and Markdown links are not automatically followed. Do not register generated
+task/evidence folders as canonical inputs. Configure per-check `timeoutMs` and
+explicit build output subdirectories in the same manifest.
+
+After an approved input change, or for a 1.4 task lacking input pins, run
+`task refresh-inputs --id ID --reason TEXT`. This archives the old state, clears
+stages, retains review consumption, and requires fresh observations/checks and
+approvals. It does not itself approve changed requirements. Closed legacy records
+remain historical. See the installed 1.4.1 migration guide in the package docs.
 
 Local files are an auditable workflow boundary, not cryptographic identity or a
 defense against a person who can rewrite the tool and all evidence. Astra/PO

package/.claude/nccgs/routing.generated.md

@@ -1,11 +1,29 @@
 # Generated routing — edit pipeline.json, then compile-policy.mjs
 
-| Stage | Owner/model | Effort |
+NCCGS runs in Claude Code. New installations use standalone execution; model aliases describe requested routes, not observed provider versions. Model selection in project.yaml and execution obligations in execution.json are separate policies.
+
+| Stage | Owner/model | Effort | Maximum review rounds |
+|---|---|---|---|
+| Intake, plan and documents | Claude Code | Routed by task | — |
+| FAST implementation | sonnet | medium | 2 |
+| STANDARD implementation | opus | medium | 3 |
+| CONTROLLED implementation | opus | high | 3 |
+| Independent review | opus | high | Shared task budget |
+| External review | Off by default; advisory or required when configured | External evidence | — |
+| Acceptance | Contract-defined Product Owner decision | Explicit when required | — |
+
+FAST: nccgs-fast-implementer. STANDARD: the relevant domain programmer. CONTROLLED: nccgs-unity-implementer with the affected specialists. Use nccgs-task-scout only for a bounded missing fact; it does not replace review.
+
+A task-wide review budget survives implementation retries and continuation. Exhaustion stops the loop; a reasoned extension is required. Report is available for blocked/partial work and is not approval. Missing runtime effort remains unknown unless supplied by observed evidence.
+
+Existing installations without execution.json retain compatibility execution: Astra plan/document ownership, required external check and Product Owner acceptance. Legacy astra-claude routes remain unchanged:
+
+| Risk | Model | Effort |
 |---|---|---|
-| Plan and documents | Astra | External session |
-| Implementation | claude-opus-5-5 | xhigh |
-| Independent review | fable | high |
-| Report check | Astra | External session |
-| Acceptance | Product Owner | Explicit decision |
+| FAST | sonnet | medium |
+| STANDARD | claude-opus-5-5 | medium |
+| CONTROLLED | claude-opus-5-5 | high |
+
+Legacy independent review: fable/high. Updating never converts historical approval into a current approval. Explicit migration preserves tasks and consumed budgets.
 
-Default active agents: 10. Full library: 45.
+Default active agents: 13. Full library: 47.