nccgs 2.0.0 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/.claude/agents/nccgs-adversarial-reviewer.md +1 -1
  2. package/.claude/agents/nccgs-engine-programmer.md +1 -1
  3. package/.claude/agents/nccgs-fast-implementer.md +1 -1
  4. package/.claude/agents/nccgs-game-designer.md +1 -1
  5. package/.claude/agents/nccgs-gameplay-programmer.md +1 -1
  6. package/.claude/agents/nccgs-qa-engineer.md +1 -1
  7. package/.claude/agents/nccgs-task-scout.md +1 -1
  8. package/.claude/agents/nccgs-ui-programmer.md +1 -1
  9. package/.claude/agents/nccgs-unity-build-specialist.md +1 -1
  10. package/.claude/agents/nccgs-unity-implementer.md +1 -1
  11. package/.claude/agents/nccgs-unity-systems-specialist.md +1 -1
  12. package/.claude/agents/nccgs-unity-ui-specialist.md +1 -1
  13. package/.claude/agents/nccgs-verification-engineer.md +1 -1
  14. package/.claude/nccgs/MEMORY.md +9 -3
  15. package/.claude/nccgs/VERSION +1 -1
  16. package/.claude/nccgs/constitution.md +187 -176
  17. package/.claude/nccgs/hooks/closure-guard.mjs +2 -0
  18. package/.claude/nccgs/hooks/unity-transport-guard.mjs +11 -0
  19. package/.claude/nccgs/pipeline.json +260 -260
  20. package/.claude/nccgs/protocols/context-packets.md +5 -0
  21. package/.claude/nccgs/protocols/model-routing.md +46 -46
  22. package/.claude/nccgs/protocols/review-handoff.md +21 -1
  23. package/.claude/nccgs/protocols/shared-workflow-context.md +33 -0
  24. package/.claude/nccgs/protocols/unity-boundary.md +20 -0
  25. package/.claude/nccgs/routing.generated.md +4 -4
  26. package/.claude/nccgs/settings.fragment.json +84 -24
  27. package/.claude/nccgs/studio.json +53 -53
  28. package/.claude/nccgs/tools/autonomy.mjs +13 -0
  29. package/.claude/nccgs/tools/command-tokens.mjs +22 -0
  30. package/.claude/nccgs/tools/compile-policy.mjs +4 -0
  31. package/.claude/nccgs/tools/configure-models.mjs +4 -0
  32. package/.claude/nccgs/tools/hook-transport.mjs +34 -0
  33. package/.claude/nccgs/tools/installation-guard.mjs +55 -0
  34. package/.claude/nccgs/tools/native-completion.mjs +10 -1
  35. package/.claude/nccgs/tools/returned-handoff.mjs +11 -2
  36. package/.claude/nccgs/tools/shared-context-guard.mjs +60 -0
  37. package/.claude/nccgs/tools/shared-context.mjs +25 -0
  38. package/.claude/nccgs/tools/tool-guard.mjs +120 -131
  39. package/.claude/nccgs/tools/unity-transport.mjs +170 -0
  40. package/.claude/nccgs/workflow-catalog.json +4 -4
  41. package/CHANGELOG.md +235 -165
  42. package/CLAUDE.md +10 -8
  43. package/MEMORY.md +109 -56
  44. package/README.md +206 -168
  45. package/UPGRADING.md +130 -112
  46. package/VERSION +1 -1
  47. package/docs/ARCHITECTURE.md +131 -131
  48. package/docs/ASSET-PRODUCTION-GRAPHIFY-PLAN.md +230 -0
  49. package/docs/HUONG-DAN-MIGRATE-VA-SU-DUNG.md +117 -87
  50. package/docs/NCCGS-1.5.md +237 -237
  51. package/docs/PROJECT-POLICY.md +94 -94
  52. package/docs/RELEASE-STATUS.md +32 -7
  53. package/docs/UNINSTALL.md +134 -0
  54. package/docs/WFK17-HOOK-REPAIR.md +71 -0
  55. package/docs/WORKFLOWS.md +85 -85
  56. package/package.json +1 -1
  57. package/scaffold/.nccgs/project.yaml +109 -108
  58. package/scripts/benchmark-v15.mjs +173 -173
  59. package/scripts/cli.mjs +11 -2
  60. package/scripts/doctor.mjs +261 -261
  61. package/scripts/install.mjs +530 -515
  62. package/scripts/recover-session.mjs +89 -0
  63. package/scripts/run.mjs +22 -9
  64. package/scripts/supervise.mjs +4 -0
  65. package/scripts/uninstall.mjs +292 -0
  66. package/scripts/validate.mjs +285 -278
  67. package/tests/autonomy.test.mjs +126 -113
  68. package/tests/design-readiness.test.mjs +199 -199
  69. package/tests/fixtures/compiler-shutdown.cs +67 -64
  70. package/tests/fixtures/native-provider.mjs +61 -0
  71. package/tests/framework.test.mjs +740 -740
  72. package/tests/hook-repair.test.mjs +106 -0
  73. package/tests/lifecycle-v15.test.mjs +346 -300
  74. package/tests/native-completion-notices.test.mjs +181 -0
  75. package/tests/phase1.test.mjs +427 -416
  76. package/tests/phase2.test.mjs +250 -250
  77. package/tests/policy-v15.test.mjs +234 -234
  78. package/tests/returned-handoff-notices.test.mjs +170 -0
  79. package/tests/runtime-v15.test.mjs +1197 -1191
  80. package/tests/task-slices.test.mjs +285 -285
  81. package/tests/uninstall.test.mjs +477 -0
  82. package/tests/unity-transport.test.mjs +348 -0
package/UPGRADING.md CHANGED
@@ -1,112 +1,130 @@
1
- # Upgrading NCCGS 2.0.0
2
-
3
- Current prepared stable package: **2.0.0**, unpublished. Preparation does not change
4
- npm `next` or `latest`. Use the local archive for reproducible evaluation.
5
- Read [release status](docs/RELEASE-STATUS.md) for what has and has not been verified.
6
-
7
- ## Choose the operation
8
-
9
- | Situation | Operation | Effect |
10
- |---|---|---|
11
- | No NCCGS installation | `install` | Adds framework and initial project policy |
12
- | Existing NCCGS installation | `update` | Updates managed files; preserves project-owned policy and customizations |
13
- | Intentionally adopt standalone execution | `migrate-execution --to standalone` | Explicitly changes execution configuration; separate from updating files |
14
- | Resume work | `run` | Launches Claude Code with the project's configured obligations |
15
-
16
- **Historical published-1.3.0 → RC3 upgrade qualification covers its tested fixture matrix.**
17
- See [upgrade qualification](docs/UPGRADE-QUALIFICATION.md) for scope and the RC2
18
- issue corrected in RC3. RC4 archive checks are recorded separately in its release
19
- receipts; historical results do not certify a different archive. Try a complete
20
- copy before applying this package to active work.
21
-
22
- ## New installation
23
-
24
- Requirements: Node.js 18+, Claude Code with access to the selected models, and a
25
- Unity project with Assets, Packages and ProjectSettings. Live Unity operations
26
- also require the appropriate Unity Editor/CLI integration.
27
-
28
- ```powershell
29
- $NccgsArchive = "D:\path\to\nccgs-2.0.0.tgz"
30
- npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject" --dry-run
31
- npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject"
32
- npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\UnityProject"
33
- ```
34
-
35
- New installations select standalone execution and the claude-standalone model
36
- profile. External review is off by default; manual/project acceptance obligations
37
- still apply when required. New task autonomy defaults to full, activated by `run`;
38
- OS restrictions, explicit deny rules and evidence/destructive-action guards remain.
39
-
40
- ## Update an existing installation
41
-
42
- Back up the complete project first, including .claude, .nccgs, source, settings,
43
- open task records and evidence. Stop active NCCGS sessions before applying an
44
- update. Do not update a frozen evaluation in place.
45
-
46
- ```powershell
47
- npx --yes --package "$NccgsArchive" nccgs update --project "D:\path\to\ProjectCopy" --dry-run
48
- npx --yes --package "$NccgsArchive" nccgs update --project "D:\path\to\ProjectCopy"
49
- npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\ProjectCopy"
50
- ```
51
-
52
- Inspect the dry-run changes before the second command. Ordinary updates preserve
53
- model profile, execution policy and project customizations. A project with no
54
- execution.json retains compatibility obligations; selecting a model profile alone
55
- does not migrate its execution policy. Existing autonomy settings are preserved.
56
-
57
- Changed or intentionally missing managed files are recorded in
58
- `.nccgs/framework-overrides.json`. Resolve pending overrides through the project's
59
- reviewed migration workflow; do not use `--force` just to make doctor green. Keep
60
- the project's canonical requirements and applicable gates. Reopen Claude Code
61
- after changing hooks, settings or managed agents.
62
-
63
- If update reports that NCCGS is not installed, use the exact local-archive `install` command
64
- above after checking the target. Some legacy CLI messages mention `@latest`;
65
- that selects the published stable channel, not this unpublished local archive.
66
-
67
- ## Optional execution-policy migration
68
-
69
- After installing/updating, migrate only when the owner intends to adopt standalone.
70
- Review any active task's pinned obligations before changing policy.
71
-
72
- ```powershell
73
- npx --yes --package "$NccgsArchive" nccgs migrate-execution --project "D:\path\to\ProjectCopy" --to standalone --model-profile claude-standalone --dry-run
74
- ```
75
-
76
- Inspect the result, then repeat without `--dry-run` to apply. Omit
77
- `--model-profile` to preserve model routes. An update alone does not perform this
78
- migration. Schema-1 tasks retain their original gates/history; do not relabel them
79
- as schema-2, reuse stale approvals or reset consumed attempts. A changed pipeline can block resuming an old task. Finish it before upgrading,
80
- or explicitly scope subsequent work with retained lineage/evidence; updating or
81
- rolling back execution settings does not re-approve an old task.
82
-
83
- The command archives configuration under `.nccgs/backups/execution/<ID>`. To
84
- preview restoration of that execution migration:
85
-
86
- ```powershell
87
- npx --yes --package "$NccgsArchive" nccgs migrate-execution --project "D:\path\to\ProjectCopy" --rollback "MIGRATION_UUID" --dry-run
88
- ```
89
-
90
- Use the actual printed UUID; remove `--dry-run` only after reviewing the preview.
91
- Rollback refuses changed current configuration or altered backup hashes and
92
- requires a compatible framework version. It restores execution configuration,
93
- **not a complete package downgrade**. A full recovery uses the complete project
94
- backup. Do not install 1.3.0 over a 2.0 project and assume task-schema downgrade
95
- is safe. Caught migration failures restore captured configuration; an OS kill is
96
- not an atomic transaction and may require manual recovery.
97
-
98
- ## Start and review work
99
-
100
- ```powershell
101
- npx --yes --package "$NccgsArchive" nccgs run --project "D:\path\to\UnityProject"
102
- ```
103
-
104
- Use `/status` in Claude Code to inspect obligations. Use `/migrate-project` when
105
- the installer/doctor reports project migration or override review is required.
106
- Installation and doctor checks prove package/setup integrity, not Claude execution,
107
- game quality, completion of a task or human acceptance.
108
-
109
- Existing projects that intentionally use Astra/Fable keep their configured chain.
110
- See [compatibility gates](.claude/nccgs/protocols/task-gates.md). Historical 1.4/1.5
111
- guides describe their original versions; this document governs the current 2.0.0 package's
112
- installation commands and release status.
1
+ # Upgrading NCCGS 2.1.1
2
+
3
+ Current source: **2.1.1**, unpublished. Version 2.0.0 was published on 2026-10-28.
4
+ The registry already contains a different `nccgs@2.1.0` tarball. This prepared
5
+ 2.1.1 package derives from the accepted local R11 r05 qualification; it does not
6
+ replace or retroactively qualify the registry artifact. No npm tags are changed.
7
+
8
+ Preparation does not change npm tags. Use the local 2.1.1 archive for evaluation.
9
+ Read [release status](docs/RELEASE-STATUS.md) for what has and has not been verified.
10
+
11
+ ## Choose the operation
12
+
13
+ | Situation | Operation | Effect |
14
+ |---|---|---|
15
+ | No NCCGS installation | `install` | Adds framework and initial project policy |
16
+ | Existing NCCGS installation | `update` | Updates managed files; preserves project-owned policy and customizations |
17
+ | Intentionally adopt standalone execution | `migrate-execution --to standalone` | Explicitly changes execution configuration; separate from updating files |
18
+ | Resume work | `run` | Launches Claude Code with the project's configured obligations |
19
+ | Stop using NCCGS in this project | `uninstall` | Removes unchanged framework files/hooks; retains source, customizations and history |
20
+ | Undo removal | `uninstall --rollback ID` | Restores verified backup bytes, refusing later edits |
21
+
22
+ **Historical published-1.3.0 → RC3 upgrade qualification covers its tested fixture matrix.**
23
+ See [upgrade qualification](docs/UPGRADE-QUALIFICATION.md) for scope and the RC2
24
+ issue corrected in RC3. RC4 archive checks are recorded separately in its release
25
+ receipts; historical results do not certify a different archive. Try a complete
26
+ copy before applying this package to active work.
27
+
28
+ ## New installation
29
+
30
+ Requirements: Node.js 18+, Claude Code with access to the selected models, and a
31
+ Unity project with Assets, Packages and ProjectSettings. Live Unity operations
32
+ also require the appropriate Unity Editor/CLI integration.
33
+
34
+ ```powershell
35
+ $NccgsArchive = "D:\path\to\nccgs-2.1.1.tgz"
36
+ npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject" --dry-run
37
+ npx --yes --package "$NccgsArchive" nccgs install --project "D:\path\to\UnityProject"
38
+ npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\UnityProject"
39
+ ```
40
+
41
+ New installations select standalone execution and the claude-standalone model
42
+ profile. External review is off by default; manual/project acceptance obligations
43
+ still apply when required. New task autonomy defaults to full, activated by `run`;
44
+ OS restrictions, explicit deny rules and evidence/destructive-action guards remain.
45
+
46
+ ## Update an existing installation
47
+
48
+ Back up the complete project first, including .claude, .nccgs, source, settings,
49
+ open task records and evidence. Stop active NCCGS sessions before applying an
50
+ update. Do not update a frozen evaluation in place.
51
+
52
+ ```powershell
53
+ npx --yes --package "$NccgsArchive" nccgs update --project "D:\path\to\ProjectCopy" --dry-run
54
+ npx --yes --package "$NccgsArchive" nccgs update --project "D:\path\to\ProjectCopy"
55
+ npx --yes --package "$NccgsArchive" nccgs doctor --project "D:\path\to\ProjectCopy"
56
+ ```
57
+
58
+ Inspect the dry-run changes before the second command. Ordinary updates preserve
59
+ model profile, execution policy and project customizations. A project with no
60
+ execution.json retains compatibility obligations; selecting a model profile alone
61
+ does not migrate its execution policy. Existing autonomy settings are preserved.
62
+
63
+ Changed or intentionally missing managed files are recorded in
64
+ `.nccgs/framework-overrides.json`. Resolve pending overrides through the project's
65
+ reviewed migration workflow; do not use `--force` just to make doctor green. Keep
66
+ the project's canonical requirements and applicable gates. Reopen Claude Code
67
+ after changing hooks, settings or managed agents.
68
+
69
+ If update reports that NCCGS is not installed, use the exact local-archive `install` command
70
+ above after checking the target. Some legacy CLI messages mention `@latest`;
71
+ that selects the published stable channel, not this unpublished local archive.
72
+
73
+ ## Optional execution-policy migration
74
+
75
+ For removal instead of migration, use [uninstall and recovery](docs/UNINSTALL.md).
76
+ The 2.1.1 CLI can remove an existing 2.0.0 installation directly. Removing or
77
+ reinstalling never resets prior task, review, acceptance or budget obligations.
78
+
79
+ After installing/updating, migrate only when the owner intends to adopt standalone.
80
+ Review any active task's pinned obligations before changing policy.
81
+
82
+ ```powershell
83
+ npx --yes --package "$NccgsArchive" nccgs migrate-execution --project "D:\path\to\ProjectCopy" --to standalone --model-profile claude-standalone --dry-run
84
+ ```
85
+
86
+ Inspect the result, then repeat without `--dry-run` to apply. Omit
87
+ `--model-profile` to preserve model routes. An update alone does not perform this
88
+ migration. Schema-1 tasks retain their original gates/history; do not relabel them
89
+ as schema-2, reuse stale approvals or reset consumed attempts. A changed pipeline can block resuming an old task. Finish it before upgrading,
90
+ or explicitly scope subsequent work with retained lineage/evidence; updating or
91
+ rolling back execution settings does not re-approve an old task.
92
+
93
+ The command archives configuration under `.nccgs/backups/execution/<ID>`. To
94
+ preview restoration of that execution migration:
95
+
96
+ ```powershell
97
+ npx --yes --package "$NccgsArchive" nccgs migrate-execution --project "D:\path\to\ProjectCopy" --rollback "MIGRATION_UUID" --dry-run
98
+ ```
99
+
100
+ Use the actual printed UUID; remove `--dry-run` only after reviewing the preview.
101
+ Rollback refuses changed current configuration or altered backup hashes and
102
+ requires a compatible framework version. It restores execution configuration,
103
+ **not a complete package downgrade**. A full recovery uses the complete project
104
+ backup. Do not install 1.3.0 over a 2.0 project and assume task-schema downgrade
105
+ is safe. Caught migration failures restore captured configuration; an OS kill is
106
+ not an atomic transaction and may require manual recovery.
107
+
108
+ ## Start and review work
109
+
110
+ ```powershell
111
+ npx --yes --package "$NccgsArchive" nccgs run --project "D:\path\to\UnityProject"
112
+ ```
113
+
114
+ Use `/status` in Claude Code to inspect obligations. Use `/migrate-project` when
115
+ the installer/doctor reports project migration or override review is required.
116
+ Installation and doctor checks prove package/setup integrity, not Claude execution,
117
+ game quality, completion of a task or human acceptance.
118
+
119
+ Existing projects that intentionally use Astra/Fable keep their configured chain.
120
+ See [compatibility gates](.claude/nccgs/protocols/task-gates.md). Historical 1.4/1.5
121
+ guides describe their original versions; this document governs the current 2.1.1 package's
122
+ installation commands and release status.
123
+
124
+ ## R07 CLI-only working candidate (unpublished)
125
+
126
+ The Unity CLI-only transport boundary now applies at launch, normal and repair tool admission, and project hooks. A strict empty MCP configuration is the default; separately approved non-Unity configurations remain explicit. Retained supervised runs without strict MCP isolation are refused before launch and without rewriting original run/cost/dispatch records. Start a properly authorized fresh continuation using the existing task/history/budget; never reset quotas to pass. No global configuration or game project is migrated automatically.
127
+
128
+ This working candidate retains the R06 completion/returned-handoff repairs and shared Graphify consumer. Frozen R03/R04/R06 records remain unchanged. Native scoped qualification and human acceptance are separate; no npm tag is changed.
129
+
130
+ R07 review repair: Claude Code declares its MCP-config option variadic. The one validated config is therefore placed at argv end or immediately before the explicit option terminator, preserving positional prompts and preventing an unchecked second config. Recovery requires that canonical boundary without rewriting retained state. Ordinary Claude/Codex Unity MCP registration is denied; non-Unity community server/method names remain available. Provider instruction-pattern warnings remain fail-closed; qualification handoffs describe settings in prose instead of reproducing configuration JSON.
package/VERSION CHANGED
@@ -1 +1 @@
1
- 2.0.0
1
+ 2.1.1
@@ -1,131 +1,131 @@
1
- # NCCGS architecture
2
-
3
- ## Design objective
4
-
5
- NCCGS optimizes correctness, specialization, context efficiency, recoverability, and
6
- evidence. File or agent count is not an objective. A component exists when it owns a
7
- distinct decision surface, failure mode, artifact, or verification lens.
8
-
9
- ## Layers
10
-
11
- 1. **Kernel** — constitution, authority, project policy, ownership, state, closure.
12
- 2. **Router** — domain/risk classification, model profile, context packet, execution
13
- graph and write ownership.
14
- 3. **Studio roles** — a focused active set plus optional specialists. Counts, model
15
- routes and native turn ceilings come from the [generated routing reference](../.claude/nccgs/routing.generated.md).
16
- Activation choices survive updates; customized files are preserved.
17
- 4. **Workflow modules** — 36 composable skills with eight user-facing entrypoints.
18
- 5. **Unity operations** — unmodified official Unity Skills and Unity CLI/Pipeline.
19
- 6. **Automation** — Node hooks for recovery, audit and safety.
20
- 7. **Evaluation** — structural validation and executable behavioral tests.
21
-
22
- ## Bounded orchestration
23
-
24
- The primary Claude Code session is the sole Claude subagent orchestrator. New
25
- installations use standalone execution: Claude Code owns intake, planning,
26
- documents, dispatch and reporting. It constructs an implementation DAG,
27
- selects the smallest complete role set, passes a context packet, assigns one writer
28
- per path, and merges handoffs. Studio agents do not recursively delegate.
29
-
30
- This preserves domain decomposition while preventing context-amplifying chains such
31
- as director → lead → engine lead → specialist. The 2.0.0 operating protocol launches
32
- one foreground Agent call at a time and waits for its final result. The configured
33
- worker ceiling is not a promise of parallel dispatch. Review/analysis reserves a
34
- stable snapshot and cannot overlap source writers in the same project.
35
-
36
- Execution obligations are selected before models. Missing execution.json means
37
- compatibility; existing Astra/Fable/Product Owner gates survive updates. Explicit
38
- execution migration and model-profile selection are separate operations.
39
-
40
- ## Context architecture
41
-
42
- Large standalone implementation tasks can use a pinned [slice plan](TASK-SLICING.md)
43
- within the same task. Exact file ownership, original criterion IDs and dependency
44
- dispatches bound each assignment. One final integration receives the full contract;
45
- intermediate handoffs cannot satisfy implementation or acceptance. Independent
46
- review excludes every implementation contributor in the task subtree. Plans and
47
- revisions retain attempts and reserve capacity inside existing ancestor limits;
48
- they create no child task, review round or session budget.
49
-
50
- The feature contract stores approved scope. The context packet stores the current
51
- working-set map: source anchors and revisions, decision summaries, ownership,
52
- dependencies, verification, and reasons for any full-source read. Agents receive the
53
- packet path and exact responsibility rather than copies of every canonical document.
54
-
55
- State, packets, and handoffs are file-backed so compaction and session restarts do not
56
- require reconstructing truth from chat history.
57
-
58
- ## Model architecture
59
-
60
- Each catalog role has a capability class: lightweight, standard, deep, leadership,
61
- or review. `pipeline.json` is the routing source; the compiler generates catalog
62
- routes and agent frontmatter, and validation rejects drift. The default
63
- claude-standalone profile requests Sonnet/medium for FAST, Opus/medium for STANDARD,
64
- Opus/high for CONTROLLED and Opus/high for independent review. Requested routes
65
- do not establish actual provider execution. The generated reference includes
66
- compatibility routes; quality, balanced and inherit profiles remain available
67
- without duplicating agent prompts.
68
-
69
- Legacy profiles support policy-directed fallback. The astra-claude profile instead
70
- blocks a required stage when its model/effort cannot be confirmed; it never labels
71
- an inherited model's output as Fable review or the selected implementation route.
72
-
73
- ## Unity boundary
74
-
75
- NCCGS does not copy Unity API/CLI procedures into agent prompts. Studio roles own
76
- product and technical intent; official Unity Skills own operation mechanics. The
77
- SHA-256 manifest makes upstream modifications visible.
78
-
79
- ## Evidence and closure
80
-
81
- Standalone work follows scoped intake and reviewed design where required ->
82
- risk-selected implementation -> measured verification -> independent review ->
83
- report -> configured external/manual/acceptance gates. The accountable implementer
84
- fixes findings and an independent reviewer re-reviews changed work. Compatibility
85
- with astra-claude retains Fable review, Astra checking and explicit Product Owner
86
- acceptance. `task.mjs` enforces the selected sequence using snapshot hashes, immutable
87
- artifact references, runtime observations and explicit external decisions. A changed
88
- snapshot invalidates previous review/acceptance. Re-recording an earlier stage clears
89
- downstream stages while retaining history. Hooks supplement the task gate; they are
90
- not a security sandbox. There is no automatic cross-app transport.
91
-
92
- Task risk selects a frozen implementation route and a review budget from
93
- `contract.taskTiers`: FAST/lightweight/2 rounds, STANDARD/standard/3, or
94
- CONTROLLED/deep/3. Valid review records consume rounds even for negative verdicts.
95
- Re-recording implementation preserves the counter. A PASS at the limit can proceed;
96
- otherwise exhaustion stops the task until an explicit external, reasoned extension.
97
- Planning estimates are advisory. Standalone dispatch and configured worker
98
- time/cost limits govern admission using observed telemetry; they do not measure
99
- account-wide usage or interrupt a provider request already running.
100
-
101
- Requested model settings and observed runtime values are separate fields. Native
102
- events can report the resolved model and fallback history; absent observed effort
103
- stays unknown until supporting runtime evidence is imported.
104
-
105
- Every workflow dispatcher selects execution policy first. Standalone loads the
106
- shared standalone protocol; design entrypoints also load the design lifecycle.
107
- Compatibility loads exactly one Astra or legacy reference. Risk selects scope and
108
- model routing; all standalone tiers retain independent review.
109
-
110
- Handoff helpers generate bounded prompts and PARTIAL drafts, validate structure
111
- before completion, and import a completed reviewer's pinned result through the
112
- existing record gate. They never supply provider evidence, change a verdict,
113
- close the task, or reset budgets. See [handoff operations](HANDOFF-AUTOMATION.md).
114
-
115
- One implementer remains accountable for the task. The scout closes a named factual
116
- gap; specialist reviewers add distinct risk coverage. Neither is a compulsory
117
- ritual. Approved scope and evidence determine the stopping point: once criteria
118
- and relevant checks pass without actionable blockers, hand off. New checks require
119
- changed inputs, failures, or new evidence; subjective questions require a playable
120
- Product Owner test instead of indefinite model debate.
121
-
122
- One canonical closure record links existing project artifacts. `lean`, `linked`, and
123
- `strict` policies determine what blocks DONE. Waivers are item-specific and retain
124
- Product Owner authority.
125
-
126
- ## Extension rules
127
-
128
- Add a role only for a distinct domain contract. Add a workflow when a repeated
129
- sequence, gate, or artifact benefits from independent discovery and testing. Put
130
- conditional detail in references. Do not modify official Unity Skills for local
131
- policy, and do not hard-code one project's paths in framework files.
1
+ # NCCGS architecture
2
+
3
+ ## Design objective
4
+
5
+ NCCGS optimizes correctness, specialization, context efficiency, recoverability, and
6
+ evidence. File or agent count is not an objective. A component exists when it owns a
7
+ distinct decision surface, failure mode, artifact, or verification lens.
8
+
9
+ ## Layers
10
+
11
+ 1. **Kernel** — constitution, authority, project policy, ownership, state, closure.
12
+ 2. **Router** — domain/risk classification, model profile, context packet, execution
13
+ graph and write ownership.
14
+ 3. **Studio roles** — a focused active set plus optional specialists. Counts, model
15
+ routes and native turn ceilings come from the [generated routing reference](../.claude/nccgs/routing.generated.md).
16
+ Activation choices survive updates; customized files are preserved.
17
+ 4. **Workflow modules** — 36 composable skills with eight user-facing entrypoints.
18
+ 5. **Unity operations** — unmodified official Unity Skills and Unity CLI/Pipeline.
19
+ 6. **Automation** — Node hooks for recovery, audit and safety.
20
+ 7. **Evaluation** — structural validation and executable behavioral tests.
21
+
22
+ ## Bounded orchestration
23
+
24
+ The primary Claude Code session is the sole Claude subagent orchestrator. New
25
+ installations use standalone execution: Claude Code owns intake, planning,
26
+ documents, dispatch and reporting. It constructs an implementation DAG,
27
+ selects the smallest complete role set, passes a context packet, assigns one writer
28
+ per path, and merges handoffs. Studio agents do not recursively delegate.
29
+
30
+ This preserves domain decomposition while preventing context-amplifying chains such
31
+ as director → lead → engine lead → specialist. The 2.0.0 operating protocol launches
32
+ one foreground Agent call at a time and waits for its final result. The configured
33
+ worker ceiling is not a promise of parallel dispatch. Review/analysis reserves a
34
+ stable snapshot and cannot overlap source writers in the same project.
35
+
36
+ Execution obligations are selected before models. Missing execution.json means
37
+ compatibility; existing Astra/Fable/Product Owner gates survive updates. Explicit
38
+ execution migration and model-profile selection are separate operations.
39
+
40
+ ## Context architecture
41
+
42
+ Large standalone implementation tasks can use a pinned [slice plan](TASK-SLICING.md)
43
+ within the same task. Exact file ownership, original criterion IDs and dependency
44
+ dispatches bound each assignment. One final integration receives the full contract;
45
+ intermediate handoffs cannot satisfy implementation or acceptance. Independent
46
+ review excludes every implementation contributor in the task subtree. Plans and
47
+ revisions retain attempts and reserve capacity inside existing ancestor limits;
48
+ they create no child task, review round or session budget.
49
+
50
+ The feature contract stores approved scope. The context packet stores the current
51
+ working-set map: source anchors and revisions, decision summaries, ownership,
52
+ dependencies, verification, and reasons for any full-source read. Agents receive the
53
+ packet path and exact responsibility rather than copies of every canonical document.
54
+
55
+ State, packets, and handoffs are file-backed so compaction and session restarts do not
56
+ require reconstructing truth from chat history.
57
+
58
+ ## Model architecture
59
+
60
+ Each catalog role has a capability class: lightweight, standard, deep, leadership,
61
+ or review. `pipeline.json` is the routing source; the compiler generates catalog
62
+ routes and agent frontmatter, and validation rejects drift. The default
63
+ claude-standalone profile requests Sonnet/high for FAST, Opus/high for STANDARD,
64
+ Opus/xhigh for CONTROLLED/leadership and Fable/high for independent review. Requested routes
65
+ do not establish actual provider execution. The generated reference includes
66
+ compatibility routes; quality, balanced and inherit profiles remain available
67
+ without duplicating agent prompts.
68
+
69
+ Legacy profiles support policy-directed fallback. The astra-claude profile instead
70
+ blocks a required stage when its model/effort cannot be confirmed; it never labels
71
+ an inherited model's output as Fable review or the selected implementation route.
72
+
73
+ ## Unity boundary
74
+
75
+ NCCGS does not copy Unity API/CLI procedures into agent prompts. Studio roles own
76
+ product and technical intent; official Unity Skills own operation mechanics. The
77
+ SHA-256 manifest makes upstream modifications visible.
78
+
79
+ ## Evidence and closure
80
+
81
+ Standalone work follows scoped intake and reviewed design where required ->
82
+ risk-selected implementation -> measured verification -> independent review ->
83
+ report -> configured external/manual/acceptance gates. The accountable implementer
84
+ fixes findings and an independent reviewer re-reviews changed work. Compatibility
85
+ with astra-claude retains Fable review, Astra checking and explicit Product Owner
86
+ acceptance. `task.mjs` enforces the selected sequence using snapshot hashes, immutable
87
+ artifact references, runtime observations and explicit external decisions. A changed
88
+ snapshot invalidates previous review/acceptance. Re-recording an earlier stage clears
89
+ downstream stages while retaining history. Hooks supplement the task gate; they are
90
+ not a security sandbox. There is no automatic cross-app transport.
91
+
92
+ Task risk selects a frozen implementation route and a review budget from
93
+ `contract.taskTiers`: FAST/lightweight/2 rounds, STANDARD/standard/3, or
94
+ CONTROLLED/deep/3. Valid review records consume rounds even for negative verdicts.
95
+ Re-recording implementation preserves the counter. A PASS at the limit can proceed;
96
+ otherwise exhaustion stops the task until an explicit external, reasoned extension.
97
+ Planning estimates are advisory. Standalone dispatch and configured worker
98
+ time/cost limits govern admission using observed telemetry; they do not measure
99
+ account-wide usage or interrupt a provider request already running.
100
+
101
+ Requested model settings and observed runtime values are separate fields. Native
102
+ events can report the resolved model and fallback history; absent observed effort
103
+ stays unknown until supporting runtime evidence is imported.
104
+
105
+ Every workflow dispatcher selects execution policy first. Standalone loads the
106
+ shared standalone protocol; design entrypoints also load the design lifecycle.
107
+ Compatibility loads exactly one Astra or legacy reference. Risk selects scope and
108
+ model routing; all standalone tiers retain independent review.
109
+
110
+ Handoff helpers generate bounded prompts and PARTIAL drafts, validate structure
111
+ before completion, and import a completed reviewer's pinned result through the
112
+ existing record gate. They never supply provider evidence, change a verdict,
113
+ close the task, or reset budgets. See [handoff operations](HANDOFF-AUTOMATION.md).
114
+
115
+ One implementer remains accountable for the task. The scout closes a named factual
116
+ gap; specialist reviewers add distinct risk coverage. Neither is a compulsory
117
+ ritual. Approved scope and evidence determine the stopping point: once criteria
118
+ and relevant checks pass without actionable blockers, hand off. New checks require
119
+ changed inputs, failures, or new evidence; subjective questions require a playable
120
+ Product Owner test instead of indefinite model debate.
121
+
122
+ One canonical closure record links existing project artifacts. `lean`, `linked`, and
123
+ `strict` policies determine what blocks DONE. Waivers are item-specific and retain
124
+ Product Owner authority.
125
+
126
+ ## Extension rules
127
+
128
+ Add a role only for a distinct domain contract. Add a workflow when a repeated
129
+ sequence, gate, or artifact benefits from independent discovery and testing. Put
130
+ conditional detail in references. Do not modify official Unity Skills for local
131
+ policy, and do not hard-code one project's paths in framework files.