nccgs 2.1.1 → 3.0.0-rc.2

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

@@ -1,144 +0,0 @@
-> Historical development/reference document. Version, status, commands and plans
-> below describe their original scope, not the current package defaults. Read
-> [current release guidance](../MEMORY.md) before use. Research/benchmark proposals
-> do not automatically add requirements to a delivery contract.
-
-# Claude Code pilot and benchmark protocol
-
-Status: **prepared, not executed**. Framework version: **1.5.0-preview.1**.
-The authorized current work is framework development. Game work resumes later
-through Claude Code. Do not run a provider or change the game merely to fill this report.
-Evaluation scope follows [delivery acceptance](delivery-acceptance.md): measure
-brief fidelity, implementation, testing, review/repair and honest handoff. Balance
-research is a separate product assignment; bot outcomes are not studio scores.
-
-## Provenance and clean starting point
-
-Vector Survivors CP0 was built by Codex. Preserve it, label it contaminated, and
-exclude it from scored orchestration/efficiency results. A copy of its solution
-is not a fresh baseline. Prefer unseen tasks from later checkpoints or a new
-equivalent foundation with withheld solution code. Record solution exposure and
-exclude exposed tasks from independent quality/productivity claims.
-
-Freeze framework/package hash, game starting snapshot, contract, Unity version,
-machine, Claude Code version, permissions, model routes and available measurements
-before each run. Use real Claude Code agent identities and durable raw observations.
-Requested Sonnet/Opus aliases alone are insufficient. Label all synthetic fixture
-data separately; never import it into a real task as runtime evidence.
-
-## Start with a small real pilot
-
-1. Install the local preview into a fresh disposable Unity project. Review dry-run
-   and doctor results; preserve the existing CP0 game untouched.
-2. Start Claude Code, confirm managed hooks load, and read NCCGS memory.
-3. Run one fresh FAST fix in foreground with one worker and one reviewer. Confirm
-   PreToolUse -> SubagentStart -> PostToolUse IDs actually correlate. Inspect raw
-   metadata, model history, missing effort/cost and spent attempts. Do not fabricate
-   fields when the client does not provide them.
-4. Run one audit and one plan task. Attempt no source mutation; verify their outputs
-   and source baseline. Check a failed/blocked report as well as successful closure.
-5. Test an interrupted foreground/background worker, external reconciliation and
-   resume. Confirm no duplicate agent or refunded budget. Check one explicit policy
-   migration/rollback on a copy with pending legacy tasks.
-6. Only after these mechanics pass, run the size benchmark below. A blocked runtime
-   adapter is a pilot finding, not a reason to substitute Codex orchestration.
-
-## Five task sizes in the survivors game
-
-These are example *fresh* tasks. Freeze exact acceptance and withheld checks before
-dispatch; do not reuse a solved task from CP0. Shapes and simple colors are enough.
-
-| Size | Example | Expected route, subject to inspection | Required outcome |
-|---|---|---|---|
-| 1: tiny | Correct a HUD offset across fixed resolutions | implement / FAST if ready and local | Reference comparison, unchanged controls, one bounded fix |
-| 2: small prototype | Add one experimental weapon idea with a simple upgrade | implement / STANDARD | Playable loop and explicit learning questions; no production gate inflation |
-| 3: medium integration slice | Implement the specified timeline with progression, pause, loss/restart and feedback | implement / STANDARD; persistence raises risk | Deterministic state/timing tests, actual player integration checks, bug triage and a reproducible build; no bot-win requirement |
-| 4: medium-large system | Redesign spawning/pooling/performance or plan save-compatible progression | implement or plan / CONTROLLED when cross-system | Measured before/after, architecture rationale, relevant regressions and compatibility |
-| 5: large | Finish a large enemy/weapon/progression feature or audit the complete later game | implement or audit / CONTROLLED | Child contracts, integration/load tests, broad evidence and prioritized findings |
-
-For size 3, exercise normal operations from controlled, disclosed preconditions;
-check normal victory and defeat conditions independently of the bot's skill. A
-ten-minute game timer does not require every state test to wait ten real minutes.
-Verify shipped timer values and boundary logic, then cover the built player's
-relevant integration paths. Do not inject the expected terminal state itself.
-Human balance/feel studies, including participant count and sampling, belong to a
-separate research brief; do not make five playtesters a default NCCGS delivery gate.
-If a delivery brief explicitly requires human accessibility/usability inspection,
-retain that scoped obligation and record human waiting separately.
-For sizes 4–5, lock workload, seed where relevant, entity counts and
-machine/settings before profiling; measure p50/p95/p99 frame time, GC allocations,
-memory growth, restart stability, and relevant save/upgrade compatibility. Do not
-infer frame performance from framework snapshot timing.
-
-## Compare fairly
-
-Use two arms on matched, fresh work: plain Claude Code with a concise team workflow,
-and Claude Code with NCCGS preview. Keep model access, task acceptance and tools
-comparable; record actual route differences. Randomize order and use isolated
-projects/sessions so the second arm does not see the first solution. Blind quality
-review to the arm where practical. Astra is off for the primary benchmark; evaluate
-advisory/required review as a separate experiment, recording added benefit and delay.
-
-Start with two matched pairs per size (20 runs total) as an exploratory pilot. This
-is not enough to claim broad statistical superiority. Extend to the larger sample
-in the implementation plan only after runtime mechanics and task comparability pass.
-Failures, retries, abandoned attempts and intervention remain in the denominator.
-Do not replace failed tasks with easier ones or score only completed work.
-
-## Record useful efficiency and overthinking metrics
-
-| Dimension | Measure | Interpretation |
-|---|---|---|
-| Correctness | Acceptance pass rate; severity-weighted escaped defects | A cheap but incorrect result is not efficient |
-| Delivery | End-to-end elapsed, active executor time, human wait separately | Never compare worker time with another arm's whole task |
-| Resource use | Observed tokens/cost per accepted outcome, coverage and billing source | Unknown is null; report partial coverage |
-| Coordination | Dispatch count, useful specialist contributions, repeated reads, repeated unchanged reviews | Identify overhead that changed no decision or output |
-| Rework | Failed checks, accepted/rejected findings, fix/review rounds | Count every attempt and actual recovery work |
-| Autonomy | Human interventions and reasons; incorrect vs necessary escalations | Don't reward unsafe action or unexplained blocking |
-| Maintainability | Independent assessment of cohesion, clarity, tests and extension cost | Blind review with concrete evidence |
-| Resilience | Crash/resume, duplicate callback, missing evidence, budget conservation | No false success and no hidden attempt reset |
-
-Pre-register what counts as unnecessary analysis: e.g. a repeated unchanged-source
-review with no new evidence, repeated broad document loading with no decision
-dependency, or speculative refactor outside acceptance. A long task alone does
-not establish overthinking. Review whether extra reasoning prevented a real defect.
-
-Compute quality-adjusted productivity only when scope is comparable: accepted
-contract outcomes / total elapsed or observed spend. Show numerator, denominator,
-coverage and uncertainty. Do not fabricate monetary savings from model names.
-Preserve raw runs and per-size results; a single pooled average can hide tiny-task
-overhead behind large-task gains.
-
-## Promotion gates
-
-- **Preview -> stable 1.5:** real hook/identity/model evidence works on the supported
-  client; no known false-DONE, ownership, quota, migration or evidence-loss defect;
-  all five sizes have real results and documented failure recovery; scoped delivery
-  acceptance passes; measurements distinguish unknown values; owner accepts limitations.
-- **Consider 2.0:** demonstrate useful autonomy and repeatable quality/efficiency
-  gains across the agreed workload, including small tasks; assess migration/API
-  compatibility and maintenance cost; explicitly approve major-version scope.
-
-No version promotion is automatic merely because framework fixtures pass.
-
-## Run report template
-
-```text
-Run ID / arm / task size / mode / risk:
-Fresh baseline hash / solution-exposure declaration:
-Framework package hash / client version / Unity / machine:
-Contract + required checks + manual acceptance:
-Requested routes / actual models / missing fields:
-Dispatch IDs / all attempts / reviews / interventions:
-Outcome / accepted criteria / open findings / escaped defects:
-Requirement-to-code-to-test coverage / fixture interventions / independent review:
-Failure attribution: product code / verification helper / bot / orchestration / research:
-Separate product research questions and their status (not a delivery verdict):
-Elapsed / worker time / human wait:
-Tokens and cost / measurement coverage / raw source:
-Game profiling data when applicable:
-Unnecessary analysis observations and counterexamples:
-Recovery actions / budget before and after:
-Independent reviewer / Product Owner decision:
-Limitations and next concrete action:
-```

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

@@ -1,207 +0,0 @@
-# Standalone Claude Code execution — 2.0.0
-
-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
-
-When one implementation assignment is too broad, follow [task slices](task-slices.md).
-Preview and pin bounded assignments inside the same task and total budget. Preserve
-original criteria, reviewed rules and early checkpoints. Only final integration
-can supply whole-task implementation; intermediate handoffs are not acceptance.
-The independent reviewer must differ from all slice/repair contributors.
-
-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.
-Use `task dispatch-prompt --id TASK --dispatch RETURNED_ID` through the plain
-task CLI to generate that prompt and PARTIAL draft templates from the reservation.
-This prepares an assignment without launching it or authoring evidence. The
-worker writes its own handoff. See [handoff operations](../../../docs/HANDOFF-AUTOMATION.md).
-The pre-tool hook claims the reservation using the actual session/tool-use ID.
-Use foreground Agent calls in 2.0.0. 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`, exact file ownership
-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
-schema-1 packets retain 1–4 existing files, 12 work calls (6 reads), 3 handoff writes
-and a 10-minute admission deadline. Opt-in schema-2 unity-code/unity-editor packets
-support exact new files or pinned Editor operations with profile-specific limits,
-GUID preservation and project-wide exclusive ownership. Only the fixed
-repair-editor wrapper may execute their pinned Unity CLI steps; general shell,
-MCP, web and delegation remain blocked. 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. A running non-repair worker may use only the fixed
-`task handoff-validate` command for its own declared handoff; it checks structure
-without executing arbitrary code or recording a stage. 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 exact payload fields in
-[standalone gates](standalone-gates.md). Missing observations block the relevant
-stage; never author runtime evidence to make it pass.
-
-For a completed reviewer-owned handoff, `task record-review --id TASK --dispatch ID
---file PATH` imports the exact pinned result through the same record gate. It
-preserves negative verdicts, conditions, history and spent budgets. This command
-is coordinator-only; it does not report success or close the task.
-
-## 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.
-
-A fresh full Unity qualification of the exact 2.0.0 archive remains separate from
-framework fixture tests and frozen earlier-version qualifications. Contaminated Vector Survivors CP0
-must not be scored or presented as an independent NCCGS implementation.

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

@@ -1,55 +0,0 @@
-# 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,144 +0,0 @@
-# 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.
-
-1. Astra supplies the plan and project-specific acceptance obligations.
-   Astra maps existing project closure artifacts/manual gates to `.nccgs/gates.json`
-   (`requiredChecks`, `requiredArtifacts`, `manualGates`) and sets its `policySha256`
-   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 --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. Top-level generated roots
-   in pipeline.json and explicit Build/Builds output subdirectories from
-   `.nccgs/inputs.json` are excluded. Opt-in exact `unityGeneratedFiles` paths are
-   also excluded from source, with their before/after hashes retained in managed
-   verification receipts. 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. 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.
-8. `task check --id feature-1 --target report` must pass before final reporting.
-   Write the report and record stage `report` with snapshot and its evidence reference.
-   Store new report/evidence files under `.nccgs/evidence/` so producing evidence
-   does not change the reviewed source snapshot. Do not edit a hashed report to add
-   sign-offs; use separate decision files. Source or canonical document changes
-   outside excluded evidence directories require fresh implementation/review.
-9. Astra, outside Claude, checks the report and records stage `astra`. The evidence
-   reference points to JSON with actor `Astra`, decision `PASS`, taskId, snapshot,
-   decidedAt (ISO time), statement, and a source reference identifying the decision.
-10. After the user's explicit acceptance, outside Claude record stage `acceptance`
-    with an evidence file of the same shape: actor `Product Owner`, decision
-    `ACCEPTED`. Never generate a user's decision or infer it from a passed test.
-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.
-
-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,
-including modelsUsed so a mid-run fallback is visible. They do not copy prompts,
-credentials, full transcripts, or arbitrary tool output. Missing fields remain null.
-The documented Agent result does not guarantee an effort field, so native captures
-alone may be insufficient for a gate.
-
-Use `task observe --id feature-1 --file .nccgs/evidence/provider-observation.json`
-to import an explicit runtime observation when needed. That source JSON must contain
-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. 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.
-
-For a new Unity project, declare only known, wholly generated IDE/local metadata
-files in `unityGeneratedFiles` before init. Use exact project-root `.csproj`,
-`.sln`/`.slnx` paths, `.vscode/extensions.json`, `.vscode/launch.json`,
-`.vscode/settings.json`, `UserSettings/EditorUserSettings.asset` or
-`UserSettings/Search.settings`, as applicable. No folders or globs are accepted.
-Do not declare user-owned IDE configuration or project files consumed as build
-inputs; leave them tracked or register them as canonical inputs. Canonical/output
-overlaps are rejected. This opt-in policy is itself pinned; adding exclusions
-after a FAIL cannot make that old attempt pass or preserve stale approvals.
-
-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
-attestations need honest external source references. Claude sessions may not import
-their own external sign-offs. These tools do not send messages across applications.