nccgs 1.1.0 → 1.3.0

package/docs/PROJECT-POLICY.md

@@ -8,7 +8,7 @@ verification, closure, or Unity execution for the project.
 
 - project stage and platforms;
 - enabled departments and bounded orchestration;
-- `quality`, `balanced`, or `inherit` model profile and fallback policy;
+- `astra-claude`, `quality`, `balanced`, or `inherit` model profile and fallback policy;
 - canonical sources for product, design, architecture, planning, art, narrative,
   audio, and release;
 - protected/user-owned/generated paths and hand-tuned settings;
@@ -19,13 +19,28 @@ verification, closure, or Unity execution for the project.
 
 ## Model policy
 
+The default `astra-claude` profile assigns planning and canonical documents to Astra,
+implementation to pinned Opus 5.5/xhigh, and independent review to Fable/high.
+The report is handed to Astra only after Fable PASS; Astra checks it before Product
+Owner acceptance. All these gates apply even to FAST work and lean closure. See
+[the protocol](../.claude/nccgs/protocols/astra-claude.md). No silent inherited model
+or lower effort may satisfy a required stage. Legacy profile selection explicitly
+opts out of this chain and ordinary updates preserve the existing selection.
+
 Use `quality` when result quality is primary and all model tiers are available. Use
 `balanced` when leadership coordination does not need Opus by default. Use `inherit`
 when subscription/context compatibility or explicit user control is more important
 than automatic routing.
 
-Project overrides may pin a specific role/class, but avoid full model IDs unless the
-project intentionally owns upgrade timing.
+The `models.overrides` field is reserved; the configurator does not apply it. Routing
+is compiled from `.claude/nccgs/pipeline.json`. The astra-claude profile intentionally
+pins Opus 5.5; changing its required stage models is a Product Owner policy decision.
+
+For the Astra profile, map the checks, artifacts and manual gates below into
+`.nccgs/gates.json` and pin its `policySha256` to this project policy. Task-specific
+requirements may add obligations. The executable manifest does not automatically
+translate YAML conditions: Astra must preserve and map all existing safeguards.
+See [task gates](../.claude/nccgs/protocols/task-gates.md) for evidence formats.
 
 ## Canonical sources and context
 

package/docs/WORKFLOWS.md

@@ -1,5 +1,13 @@
 # NCCGS workflows
 
+The default `astra-claude` profile applies the
+[Astra/Claude handoff protocol](../.claude/nccgs/protocols/astra-claude.md) to every
+workflow below. Astra owns planning and documents; Claude implements with
+Opus 5.5/xhigh; Fable/high independently reviews before the report goes to Astra.
+Astra checks the report and the Product Owner accepts before DONE. Each dispatcher
+loads only `references/astra.md` or `references/legacy.md` for the selected profile.
+Task records and executable gates follow the [1.3 guide](NCCGS-1.3.md).
+
 ## Risk tiers
 
 | Tier | Typical work | Required structure |
@@ -11,16 +19,13 @@
 ## End-to-end work
 
 ```text
-request
-  -> risk and domain routing
-  -> context packet and readiness
-  -> decisions/plan when needed
+request -> Astra plan/documents and gate manifest
+  -> Claude risk/domain routing and context readiness
   -> one-owner implementation nodes
-  -> independent verification
-  -> adversarial review for CONTROLLED work
-  -> evidence review
-  -> record synchronization
-  -> configured closure
+  -> verification evidence
+  -> independent Fable review for every code change
+  -> report -> Astra check -> Product Owner acceptance
+  -> task close after all executable gates pass
 ```
 
 The primary session composes modules automatically. Explicit specialized commands are
@@ -33,7 +38,7 @@ available when a user wants a bounded workflow or output.
 - **Design**: `design`, `design-review`, `balance-review`, `accessibility-review`,
   `ui-review`, `prototype-feature`, `playtest`.
 - **Technical**: `architecture-decision`, `dependency-review`,
-  `compatibility-review`, `code-review`, `performance-audit`, `security-audit`.
+  `compatibility-review`, `nccgs-code-review`, `performance-audit`, `security-audit`.
 - **Implementation/quality**: `work`, `qa-plan`, `test`, `bug-triage`,
   `evidence-review`, `review`, `asset-audit`, `closure`.
 - **Delivery/recovery**: `release-readiness`, `release`, `hotfix`,
@@ -42,14 +47,15 @@ available when a user wants a bounded workflow or output.
 
 ## Role composition examples
 
-A gameplay feature may use game designer → gameplay programmer and Unity systems
+Astra plans a gameplay feature; optional game-designer consultation may support it.
+Implementation may use gameplay programmer and Unity systems
 specialist in parallel where ownership differs → verification engineer. A UI feature
 may use UX designer and accessibility specialist for design, UI programmer and Unity
 UI specialist for implementation/integration, then independent verification.
 
-CONTROLLED network-save work adds technical architect, network programmer, security
-engineer, compatibility review, and adversarial review. It does not automatically
-spawn every director or department.
+CONTROLLED network-save work can enable optional technical architect, network
+programmer and security engineer roles. Fable reviews FAST, STANDARD and CONTROLLED
+code changes. Optional roles are activated explicitly; the default loads ten roles.
 
 ## Evidence states
 

package/package-assets/nccgs-project.gitignore

@@ -0,0 +1,2 @@
+backups/
+runtime/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nccgs",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Unity-first game-studio operating system for Claude Code",
   "license": "MIT",
   "type": "module",
@@ -29,8 +29,10 @@
   },
   "scripts": {
     "validate": "node scripts/validate.mjs",
-    "test": "node --test tests/framework.test.mjs",
-    "pack:check": "npm pack --dry-run"
+    "test": "node --test tests/*.test.mjs",
+    "pack:check": "npm pack --dry-run",
+    "policy:build": "node .claude/nccgs/tools/compile-policy.mjs --write",
+    "policy:check": "node .claude/nccgs/tools/compile-policy.mjs"
   },
   "keywords": [
     "claude-code",

package/scaffold/.nccgs/gates.json

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": 1,
+  "policySha256": null,
+  "requiredChecks": [],
+  "requiredArtifacts": [],
+  "manualGates": []
+}

package/scaffold/.nccgs/project.yaml

@@ -15,12 +15,15 @@ studio:
     independent_verification: true
 
 models:
-  profile: quality
-  allow_inherit_fallback: true
-  allow_automatic_escalation: true
+  profile: astra-claude
+  allow_inherit_fallback: false
+  allow_automatic_escalation: false
   notify_on_escalation: true
   overrides: {}
 
+# Profile contracts are resolved from this canonical configuration.
+pipeline_policy: .claude/nccgs/pipeline.json
+
 workflow:
   operating_mode: solo
   autonomy: high

package/scaffold/.nccgs/state.md

@@ -14,7 +14,7 @@ Updated: [timestamp]
 
 - Last completed checkpoint: NCCGS initialized
 - Current step: configure or migrate project policy
-- Next safe action: run `/migrate-project review` for an existing project
+- Next safe action: Astra prepares project policy, gate mapping and migration plan; Claude then runs `/migrate-project`
 
 ## Decisions pending
 

package/scaffold/.nccgs/templates/agent-handoff.md

@@ -23,3 +23,13 @@
 ## Next owner
 
 [role or workflow]
+
+## Model and review trace (astra-claude profile)
+
+- Requested model/effort:
+- Observed model/effort and session/agent reference:
+- Plan and working snapshot:
+- Fable review record and verdict:
+- Report path for Astra (after Fable PASS only):
+- Astra check: PENDING unless referenced
+- Product Owner acceptance: PENDING unless explicitly referenced

package/scaffold/.nccgs/templates/closure-record.md

@@ -49,3 +49,14 @@
 ## Known issues and residual risk
 
 - None
+
+## Astra/Claude chain (required for astra-claude)
+
+- **Final snapshot**: [commit plus dirty/untracked diff or file hashes]
+- **Fable review**: PENDING/PASS/CHANGES_REQUIRED/BLOCKED [record and snapshot]
+- **Report to Astra**: [path; issued only after Fable PASS]
+- **Astra check**: PENDING/PASS/CHANGES_REQUIRED [Astra reference and snapshot]
+- **Product Owner acceptance**: PENDING/ACCEPTED/REJECTED [user reference and snapshot]
+- **Current phase**: IMPLEMENTING/FABLE_REVIEW/AWAITING_ASTRA_CHECK/AWAITING_PO_ACCEPTANCE/CLOSED
+
+All sign-offs must cover the same final snapshot. Pending or stale gates prevent DONE.

package/scaffold/.nccgs/templates/feature-contract.md

@@ -33,3 +33,12 @@
 ## Open PO decisions
 
 - None
+
+## Astra/Claude ownership (astra-claude profile)
+
+- Plan and canonical documents: Astra [plan revision/reference]
+- Implementation and remediation: Claude Opus 5.5 / xhigh
+- Independent review: Fable / high
+- Report checking and document synchronization: Astra
+- Final acceptance: Product Owner [explicit decision required]
+- Review/report snapshot identification: [commit plus dirty/untracked diff or hashes]

package/scaffold/.nccgs/templates/implementation-report.md

@@ -0,0 +1,49 @@
+# Implementation report for Astra: [feature ID]
+
+- **Phase**: AWAITING_ASTRA_CHECK
+- **Task ID and record**: [ID; .nccgs/tasks/ID.json]
+- **Report gate**: [task check --id ID --target report result]
+- **Technical state**: IMPLEMENTED | VERIFIED | BLOCKED
+- **Astra plan and revision**: [path/reference]
+- **Implemented snapshot**: [SHA-256 from task snapshot]
+- **Implementation model / effort (requested)**: [from pipeline.json]
+- **Implementation model / effort (observed)**: [runtime evidence; unknown is not proof]
+- **Implementation session / agent**: [ID/reference]
+
+## Plan compliance and changes
+
+| Requirement | Changed files/behavior | Evidence and result | Deviations |
+|---|---|---|---|
+| [REQ-ID] | [change] | [direct reference] | [none or explanation] |
+
+## Verification
+
+- Commands/scenarios, environment, counts, failures, skips, runtime/build results:
+- Relevant regression and unverified behavior:
+
+## Independent Fable review
+
+- Requested model / effort: [review route from pipeline.json]
+- Observed model / effort and session / agent: [runtime evidence]
+- Reviewed snapshot: [must match implemented snapshot]
+- Verdict: PASS | CHANGES_REQUIRED | BLOCKED
+- Review record: [path or verbatim independent findings]
+- Findings, Opus fixes, repeated checks, and Fable re-review references:
+- Remaining non-blocking findings and residual risk:
+
+## Documents for Astra
+
+- Proposed canonical document updates with exact sections and reasons:
+- Changed scope or decisions requiring Astra/Product Owner resolution:
+
+## Downstream decisions — stored separately
+
+Do not amend this report after recording its hash. Astra check and Product Owner
+acceptance are separate JSON evidence files linked by the task record. Both are
+pending when this report is handed over; never author their decisions for them.
+
+- Reproduction/acceptance steps:
+
+## Next owner
+
+Astra. Do not mark DONE while either downstream sign-off is pending.

package/scripts/cli.mjs

@@ -19,14 +19,16 @@ if (command === "version" || command === "--version" || command === "-v") {
   process.exit(0);
 }
 
-if (!new Set(["install", "update", "doctor"]).has(command)) {
+if (!new Set(["install", "update", "doctor", "task", "agents", "policy"]).has(command)) {
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(2);
 }
 
-const script = command === "doctor" ? "doctor.mjs" : "install.mjs";
-const forwardedArgs = command === "update" ? ["--update-only", ...args] : args;
+const scripts = { doctor: "doctor.mjs", task: "../.claude/nccgs/tools/task.mjs", agents: "../.claude/nccgs/tools/configure-models.mjs", policy: "../.claude/nccgs/tools/compile-policy.mjs" };
+const script = scripts[command] || "install.mjs";
+let forwardedArgs = command === "update" ? ["--update-only", ...args] : args;
+if (command === "agents" && !args.includes("--project")) forwardedArgs = ["--project", process.cwd(), ...args];
 const result = spawnSync(process.execPath, [path.join(scriptDir, script), ...forwardedArgs], {
   cwd: process.cwd(),
   stdio: "inherit"
@@ -45,6 +47,9 @@ Usage:
   nccgs install [options]
   nccgs update [options]
   nccgs doctor [options]
+  nccgs task init|snapshot|ref|observe|verify|record|check|close|bind [options]
+  nccgs agents --enable <role> | --disable <role> [--project <directory>]
+  nccgs policy [--write]              Check/regenerate package routing
   nccgs --version
 
 Install target:
@@ -53,8 +58,8 @@ Install target:
 
 Options:
   --dry-run                         Preview without writing files
-  --force                           Back up and replace framework conflicts
-  --model-profile <profile>         quality, balanced, or inherit
+  --force                           Back up and discard detected project overrides
+  --model-profile <profile>         astra-claude (default), quality, balanced, inherit
   --project <directory>             Optional explicit target directory
   --allow-non-unity                 Allow a target without Unity markers`);
 }

package/scripts/doctor.mjs

@@ -1,39 +1,72 @@
 #!/usr/bin/env node
 
-import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { matchesFingerprint, sameFingerprint } from "../.claude/nccgs/tools/integrity.mjs";
+import { check as checkTask, snapshot, stages } from "../.claude/nccgs/tools/gates.mjs";
+import { contained, hash, json } from "../.claude/nccgs/tools/policy.mjs";
 
 const args = process.argv.slice(2);
 const projectIndex = args.indexOf("--project");
-const allowPolicyMigration = args.includes("--allow-policy-migration");
+const allowMigrationRequired = args.includes("--allow-migration-required") || args.includes("--allow-policy-migration");
 const warnings = [];
+const errors = [];
 if (projectIndex >= 0 && !args[projectIndex + 1]) {
   console.error("--project requires a directory path.");
   process.exit(2);
 }
 
 const project = projectIndex >= 0 ? path.resolve(args[projectIndex + 1]) : process.cwd();
-const errors = [];
 for (const marker of ["Assets", "Packages", "ProjectSettings"]) {
   if (!fs.existsSync(path.join(project, marker))) errors.push(`Missing Unity marker: ${marker}`);
 }
 
 const statePath = path.join(project, ".claude", "nccgs", "install-state.json");
-let state = null;
-if (!fs.existsSync(statePath)) errors.push("NCCGS install state is missing.");
-else {
-  try { state = JSON.parse(fs.readFileSync(statePath, "utf8")); }
-  catch (error) { errors.push(`Install state is invalid JSON: ${error.message}`); }
+const overridePath = path.join(project, ".nccgs", "framework-overrides.json");
+const state = readJson(statePath, "NCCGS install state", true);
+const overrideManifest = readJson(overridePath, "NCCGS framework override manifest", false);
+if (state && ![1, 2, 3].includes(state.schemaVersion)) errors.push(`Unsupported install-state schema: ${state.schemaVersion ?? "unknown"}.`);
+if (overrideManifest && overrideManifest.schemaVersion !== 1) errors.push(`Unsupported framework override schema: ${overrideManifest.schemaVersion ?? "unknown"}.`);
+
+const overrides = new Map();
+for (const item of overrideManifest?.overrides ?? []) {
+  if (!isManagedRelative(item.path) || !new Set(["preserve", "absent"]).has(item.disposition)
+      || !new Set(["approved", "pending_review"]).has(item.status)) {
+    errors.push(`Invalid framework override record: ${item.path ?? "path missing"}`);
+    continue;
+  }
+  if (overrides.has(item.path)) errors.push(`Duplicate framework override: ${item.path}`);
+  overrides.set(item.path, item);
 }
 
+let verifiedManaged = 0;
 if (state) {
   for (const item of state.files ?? []) {
+    if (!isManagedRelative(item.relative)) {
+      errors.push(`Unsafe managed path in install state: ${item.relative ?? "missing"}`);
+      continue;
+    }
     const file = path.join(project, ...item.relative.split("/"));
+    const override = overrides.get(item.relative);
+    if (override) {
+      const recordedUpstream = {
+        sha256: override.upstreamSha256,
+        canonicalSha256: override.upstreamCanonicalSha256
+      };
+      if (!sameFingerprint(item, recordedUpstream)) errors.push(`Framework override has stale upstream hashes: ${item.relative}`);
+      validateOverride(override, file);
+      verifiedManaged++;
+      continue;
+    }
     if (!fs.existsSync(file)) errors.push(`Managed file is missing: ${item.relative}`);
-    else if (hashFile(file) !== item.sha256) errors.push(`Managed file was modified: ${item.relative}`);
+    else if (!matchesFingerprint(file, item)) errors.push(`Managed file was modified: ${item.relative}`);
+    else verifiedManaged++;
   }
 }
+for (const item of overrides.values()) {
+  if ((state?.files ?? []).some((managed) => managed.relative === item.path)) continue;
+  validateOverride(item, path.join(project, ...item.path.split("/")));
+}
 
 const claudePath = path.join(project, "CLAUDE.md");
 if (!fs.existsSync(claudePath) || !fs.readFileSync(claudePath, "utf8").includes("@.claude/nccgs/constitution.md")) {
@@ -44,17 +77,38 @@ const policyPath = path.join(project, ".nccgs", "project.yaml");
 let policySchema = null;
 if (!fs.existsSync(policyPath)) errors.push(".nccgs/project.yaml is missing.");
 else {
-  const match = fs.readFileSync(policyPath, "utf8").match(/^schema_version:\s*(\d+)\s*$/m);
+  const policyText = fs.readFileSync(policyPath, "utf8");
+  const match = policyText.match(/^schema_version:\s*(\d+)\s*$/m);
   policySchema = match ? Number(match[1]) : null;
-  if (policySchema !== 2) {
-    const message = `Project policy schema must be 2; found ${policySchema ?? "unknown"}.`;
-    if (allowPolicyMigration) warnings.push(message);
-    else errors.push(message);
-  }
+  if (policySchema !== 2) migrationIssue(`Project policy schema must be 2; found ${policySchema ?? "unknown"}.`);
+  if (/^profile_contracts:/m.test(policyText)) migrationIssue("Legacy embedded profile_contracts require Astra migration to pipeline.json plus project gate mapping.");
 }
 
+const activationPath = path.join(project, ".nccgs/agent-activation.json");
+if (fs.existsSync(activationPath)) {
+  try {
+    const activation = json(activationPath);
+    for (const [relative, expected] of Object.entries(activation.generated)) {
+      const bytes = fs.readFileSync(contained(project, relative));
+      if (hash(bytes) !== expected && hash(bytes.toString("utf8").replace(/\r\n/g, "\n")) !== activation.generatedCanonical?.[relative]) errors.push(`Activated agent modified: ${relative}`);
+    }
+    for (const warning of activation.warnings ?? []) migrationIssue(warning);
+  } catch (error) { errors.push(`Invalid agent activation state: ${error.message}`); }
+}
+const tasksDir = path.join(project, ".nccgs/tasks");
+if (fs.existsSync(tasksDir)) for (const file of fs.readdirSync(tasksDir).filter(f => f.endsWith(".json"))) {
+  try {
+    const task = json(path.join(tasksDir, file));
+    if (task.closed) {
+      if (!stages.every(s => task.stages?.[s]) || task.closed.snapshot !== task.stages.acceptance.snapshot) throw new Error("Closure lacks its required stage records");
+      if (task.closed.snapshot === snapshot(project).sha256) checkTask(project, task, "done");
+      else warnings.push(`Historical closure ${task.id} is for a different snapshot; it cannot approve current work.`);
+    }
+  } catch (error) { errors.push(`Invalid closed task ${file}: ${error.message}`); }
+}
 if (errors.length) {
   for (const error of errors) console.error(`ERROR: ${error}`);
+  for (const warning of warnings) console.warn(`WARN: ${warning}`);
   console.error(`NCCGS doctor failed with ${errors.length} error(s).`);
   process.exit(1);
 }
@@ -63,9 +117,39 @@ for (const warning of warnings) console.warn(`WARN: ${warning}`);
 console.log("NCCGS doctor passed.");
 console.log(`Framework version: ${state.frameworkVersion}`);
 console.log(`Model profile: ${state.modelProfile}`);
-console.log(`Managed files verified: ${state.files.length}`);
+console.log(`Managed files verified: ${verifiedManaged}`);
+console.log(`Framework overrides: ${overrides.size} (${[...overrides.values()].filter((item) => item.status !== "approved").length} pending review)`);
 console.log(`Project policy schema: ${policySchema ?? "migration required"}`);
 
-function hashFile(file) {
-  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+function validateOverride(item, file) {
+  if (item.status !== "approved") migrationIssue(`Framework override awaits /migrate-project review: ${item.path}`);
+  if (item.disposition === "absent") {
+    if (fs.existsSync(file)) errors.push(`Override expects a missing file, but it exists: ${item.path}`);
+    return;
+  }
+  if (!fs.existsSync(file)) errors.push(`Preserved framework override is missing: ${item.path}`);
+  else if (!matchesFingerprint(file, item)) errors.push(`Preserved framework override changed after it was recorded: ${item.path}`);
+}
+
+function migrationIssue(message) {
+  if (allowMigrationRequired) warnings.push(message);
+  else errors.push(message);
+}
+
+function readJson(file, label, required) {
+  if (!fs.existsSync(file)) {
+    if (required) errors.push(`${label} is missing.`);
+    return null;
+  }
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (error) {
+    errors.push(`${label} is invalid JSON: ${error.message}`);
+    return null;
+  }
+}
+
+function isManagedRelative(value) {
+  if (typeof value !== "string" || !value.startsWith(".claude/")) return false;
+  const parts = value.split("/");
+  return !parts.includes("") && !parts.includes(".") && !parts.includes("..");
 }