@ngockhoale/ukit 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to UKit are documented here.
 
 
+## 3.0.2 - 2026-09-23
+
+- **v3 reshape leftovers + docs verify-and-close (cycles C49–C51)**:
+  - Decision table v2: `MODEL_TIER_BY_CONTRACT` + `resolveModelTier` in `src/core/executionContracts.js` — contract→tier resolution is now data-driven.
+  - `limits=` route-text segment behind `routing.rigor.stage` (`src/index/taskRouting.js` + `route-task.mjs` mirror; stage-off output byte-identical, 10-case suite).
+  - Mechanical validators: `handoffDocValidator.js` + `reviewPanelAggregate.js` (+ `.mjs` CLIs) — handoff doc checks and review-panel aggregation now scriptable.
+  - Exit-predicate loop in stop-coordinator; diversity-review contract; M05.1' program-gate verdict + pstack doc banners.
+  - Docs: DOC-201..206 verified shipped (165/165 acceptance tests); stale STATUS.md queue pointer + 11 roadmap rows corrected.
+
+## 3.0.1 - 2026-09-23
+
+- **Template root split (breaking-scale layout change, kept on 3.0.x per owner decision)**: `templates/` → `template_project/` (project-level install surface) and `templates/user/` → `template_user/` (user-level `~/.ukit/` seeds). `buildPathConfig` gains `userTemplatesRoot`; `platform.user.yaml` sourceTemplates resolve relative to `template_user/`. Dev mirrors re-synced (C47 drift fixed). Pre-existing test debt fixed: `packageVersion` major pin, runtime config version, `routeCatalog` principle-skill map, `packageArtifact` negation handling, `artifactReferenceIntegrity` allowlist.
+
 ## 3.0.0 - 2026-09-23
 
 - Same content as 2.8.0 — re-versioned as a major: the UserLayer/ProjectLayer split plus the new `templates/user/` template set is a breaking-scale change and belongs on 3.x. 2.8.0 is deprecated on npm.

package/manifests/documentation.yaml

@@ -15,7 +15,7 @@ entries:
     load_policy: always
     validation: [manual]
     archive_policy: never
-    notes: generated by yarn docs:render from templates/instructions/ + repo overlay
+    notes: generated by yarn docs:render from template_project/instructions/ + repo overlay
   - id: root-agents-md
     path: AGENTS.md
     class: canonical
@@ -26,7 +26,7 @@ entries:
     load_policy: always
     validation: [manual]
     archive_policy: never
-    notes: generated by yarn docs:render from templates/instructions/ + repo overlay
+    notes: generated by yarn docs:render from template_project/instructions/ + repo overlay
   - id: root-readme
     path: README.md
     class: canonical
@@ -146,6 +146,17 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+  - id: docs-engine-conformance
+    path: docs/ENGINE_CONFORMANCE.md
+    class: canonical
+    audience: [agent, maintainer]
+    owner: adapter
+    source_of_truth: manifests/engineConformance.yaml
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual, test:tests/consistency/engineConformance.test.js]
+    archive_policy: never
+    notes: 'hand-authored mirror of manifests/engineConformance.yaml (M05.2 rescope); edit both together'
   - id: docs-gateway
     path: docs/GATEWAY.md
     class: canonical
@@ -383,46 +394,46 @@ entries:
     validation: [none]
     archive_policy: immutable
 
-  # ── templates/ canonical authoring sources ───────────────────────────────
+  # ── template_project/ canonical authoring sources ───────────────────────────────
   - id: tpl-claude-md
-    path: templates/CLAUDE.md
+    path: template_project/CLAUDE.md
     class: generated
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/instructions/
+    source_of_truth: template_project/instructions/
     merge_strategy: overwrite_with_backup
     load_policy: always
     validation: [manual, test:tests/consistency/instructionRender.test.js]
     archive_policy: never
-    notes: generated by yarn docs:render from templates/instructions/ (DOC-102); renders to installed roots
+    notes: generated by yarn docs:render from template_project/instructions/ (DOC-102); renders to installed roots
   - id: tpl-agents-md
-    path: templates/AGENTS.md
+    path: template_project/AGENTS.md
     class: generated
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/instructions/
+    source_of_truth: template_project/instructions/
     merge_strategy: overwrite_with_backup
     load_policy: always
     validation: [manual, test:tests/consistency/instructionRender.test.js]
     archive_policy: never
-    notes: generated by yarn docs:render from templates/instructions/ (DOC-102); renders to installed roots
+    notes: generated by yarn docs:render from template_project/instructions/ (DOC-102); renders to installed roots
   - id: tpl-instructions
-    path: templates/instructions/
+    path: template_project/instructions/
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/instructions/
+    source_of_truth: template_project/instructions/
     merge_strategy: none
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
     notes: dir entry — core/overlay render sources (DOC-102)
   - id: tpl-instructions-core
-    path: templates/instructions/core.md
+    path: template_project/instructions/core.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/instructions/core.md
+    source_of_truth: template_project/instructions/core.md
     merge_strategy: none
     load_policy: task-routed
     validation: [manual]
@@ -430,124 +441,124 @@ entries:
     budget: { max_lines: 172, enforcement: warning }
     notes: 'canonical shared core; TASK-217 shrink 210→157 lines, TASK-004 Stall & Wait Reporting block →165 lines — budget raised 160→172 keeping ~4% headroom (warning-only)'
   - id: tpl-omp-rules
-    path: templates/.omp/RULES.md
+    path: template_project/.omp/RULES.md
     class: generated
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/instructions/overlays/omp-rules.md
+    source_of_truth: template_project/instructions/overlays/omp-rules.md
     merge_strategy: overwrite_with_backup
     load_policy: always
     validation: [manual, test:tests/consistency/ompContextLayer.test.js]
     archive_policy: never
     notes: generated by yarn docs:render from overlay:omp-rules (DOC-102); file entry overrides tpl-omp-dir
   - id: tpl-project-important
-    path: templates/PROJECT_IMPORTANT.md
+    path: template_project/PROJECT_IMPORTANT.md
     class: canonical
     audience: [owner, agent, maintainer]
     owner: project-owner
-    source_of_truth: templates/PROJECT_IMPORTANT.md
+    source_of_truth: template_project/PROJECT_IMPORTANT.md
     merge_strategy: skip
     load_policy: always
     validation: [manual]
     archive_policy: never
     notes: seeds owner file
   - id: tpl-docs-dir
-    path: templates/docs/
+    path: template_project/docs/
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/
+    source_of_truth: template_project/docs/
     merge_strategy: overwrite_with_backup
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
     notes: default for docs templates; skip items have per-file entries below
   - id: tpl-docs-project
-    path: templates/docs/PROJECT.md
+    path: template_project/docs/PROJECT.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/PROJECT.md
+    source_of_truth: template_project/docs/PROJECT.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-memory
-    path: templates/docs/MEMORY.md
+    path: template_project/docs/MEMORY.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/MEMORY.md
+    source_of_truth: template_project/docs/MEMORY.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-worklog
-    path: templates/docs/WORKLOG.md
+    path: template_project/docs/WORKLOG.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/WORKLOG.md
+    source_of_truth: template_project/docs/WORKLOG.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-code-map
-    path: templates/docs/CODE_MAP.md
+    path: template_project/docs/CODE_MAP.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/CODE_MAP.md
+    source_of_truth: template_project/docs/CODE_MAP.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-bugfix
-    path: templates/docs/BUGFIX.md
+    path: template_project/docs/BUGFIX.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/BUGFIX.md
+    source_of_truth: template_project/docs/BUGFIX.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-bug-template
-    path: templates/docs/BUG_TEMPLATE.md
+    path: template_project/docs/BUG_TEMPLATE.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/BUG_TEMPLATE.md
+    source_of_truth: template_project/docs/BUG_TEMPLATE.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-bug-index
-    path: templates/docs/BUG_INDEX.md
+    path: template_project/docs/BUG_INDEX.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/BUG_INDEX.md
+    source_of_truth: template_project/docs/BUG_INDEX.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-bug-metrics
-    path: templates/docs/BUG_METRICS.md
+    path: template_project/docs/BUG_METRICS.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/BUG_METRICS.md
+    source_of_truth: template_project/docs/BUG_METRICS.md
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
   - id: tpl-docs-ai-handoff
-    path: templates/docs/AI_HANDOFF/
+    path: template_project/docs/AI_HANDOFF/
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/AI_HANDOFF/
+    source_of_truth: template_project/docs/AI_HANDOFF/
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
@@ -563,136 +574,136 @@ entries:
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
-    notes: installed copy of templates/docs/UKIT_INTERNALS.md (merge_strategy overwrite_with_backup on install); internal-orchestration detail extracted from core.md (DOC-104)
+    notes: installed copy of template_project/docs/UKIT_INTERNALS.md (merge_strategy overwrite_with_backup on install); internal-orchestration detail extracted from core.md (DOC-104)
   - id: tpl-docs-ukit-internals
-    path: templates/docs/UKIT_INTERNALS.md
+    path: template_project/docs/UKIT_INTERNALS.md
     class: canonical
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/docs/UKIT_INTERNALS.md
+    source_of_truth: template_project/docs/UKIT_INTERNALS.md
     merge_strategy: overwrite_with_backup
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
     notes: internal-orchestration detail extracted from core.md (DOC-104); shipped via docs-ukit-internals manifest item
   - id: tpl-codex-readme
-    path: templates/.codex/README.md
+    path: template_project/.codex/README.md
     class: canonical
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/.codex/README.md
+    source_of_truth: template_project/.codex/README.md
     merge_strategy: overwrite_with_backup
     load_policy: always
     validation: [manual]
     archive_policy: never
     notes: codex host adapter surface — FR-007 scan
   - id: tpl-omp-dir
-    path: templates/.omp/
+    path: template_project/.omp/
     class: canonical
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/.omp/
+    source_of_truth: template_project/.omp/
     merge_strategy: overwrite_with_backup
     load_policy: always
     validation: [manual]
     archive_policy: never
     notes: omp host adapter surface (AGENTS/README/RULES + agents)
   - id: tpl-ukit-readme
-    path: templates/ukit/README.md
+    path: template_project/ukit/README.md
     class: canonical
     audience: [maintainer]
     owner: runtime
-    source_of_truth: templates/ukit/README.md
+    source_of_truth: template_project/ukit/README.md
     merge_strategy: overwrite_with_backup
     load_policy: never
     validation: [manual]
     archive_policy: never
     notes: reference only — FR-007 scan
   - id: tpl-ukit-storage-memory
-    path: templates/ukit/storage/memory/
+    path: template_project/ukit/storage/memory/
     class: canonical
     audience: [agent, maintainer]
     owner: runtime
-    source_of_truth: templates/ukit/storage/memory/
+    source_of_truth: template_project/ukit/storage/memory/
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
     notes: dir sourceTemplate ukit/storage/memory → dir path ending '/'
   - id: tpl-claude-dir
-    path: templates/.claude/
+    path: template_project/.claude/
     class: canonical
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/.claude/
+    source_of_truth: template_project/.claude/
     merge_strategy: overwrite_with_backup
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
     notes: skills/agents/hooks dir entry
   - id: tpl-adapter-presets
-    path: templates/adapter-presets/
+    path: template_project/adapter-presets/
     class: canonical
     audience: [maintainer]
     owner: adapter
-    source_of_truth: templates/adapter-presets/
+    source_of_truth: template_project/adapter-presets/
     merge_strategy: none
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
     notes: mixed strategies per manifest; skip items have per-file entries
   - id: tpl-preset-claude-settings-local
-    path: templates/adapter-presets/claude/settings.local.json
+    path: template_project/adapter-presets/claude/settings.local.json
     class: canonical
     audience: [maintainer]
     owner: adapter
-    source_of_truth: templates/adapter-presets/claude/settings.local.json
+    source_of_truth: template_project/adapter-presets/claude/settings.local.json
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
     notes: non-.md entry — exists for FR-002 manifest consistency
   - id: tpl-preset-codex-settings-local
-    path: templates/adapter-presets/codex/settings.local.json
+    path: template_project/adapter-presets/codex/settings.local.json
     class: canonical
     audience: [maintainer]
     owner: adapter
-    source_of_truth: templates/adapter-presets/codex/settings.local.json
+    source_of_truth: template_project/adapter-presets/codex/settings.local.json
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
     notes: non-.md entry — exists for FR-002 manifest consistency
   - id: tpl-gitignore
-    path: templates/.gitignore
+    path: template_project/.gitignore
     class: canonical
     audience: [maintainer]
     owner: product
-    source_of_truth: templates/.gitignore
+    source_of_truth: template_project/.gitignore
     merge_strategy: skip
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
     notes: non-.md entry — exists for FR-002 manifest consistency
 
-  # ── repo mirrors (derived from templates/) ───────────────────────────────
+  # ── repo mirrors (derived from template_project/) ───────────────────────────────
   - id: mirror-claude-dir
     path: .claude/
     class: derived
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/.claude/
+    source_of_truth: template_project/.claude/
     merge_strategy: none
     load_policy: task-routed
     validation: [manual]
     archive_policy: never
-    notes: repo mirror of templates/.claude/
+    notes: repo mirror of template_project/.claude/
   - id: mirror-codex-readme
     path: .codex/README.md
     class: derived
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/.codex/README.md
+    source_of_truth: template_project/.codex/README.md
     merge_strategy: none
     load_policy: on-demand
     validation: [manual]
@@ -702,7 +713,7 @@ entries:
     class: derived
     audience: [agent, maintainer]
     owner: adapter
-    source_of_truth: templates/.omp/
+    source_of_truth: template_project/.omp/
     merge_strategy: none
     load_policy: on-demand
     validation: [manual]
@@ -712,7 +723,7 @@ entries:
     class: derived
     audience: [agent, maintainer]
     owner: runtime
-    source_of_truth: templates/ukit/README.md
+    source_of_truth: template_project/ukit/README.md
     merge_strategy: none
     load_policy: on-demand
     validation: [manual]

package/manifests/engineConformance.yaml

@@ -0,0 +1,32 @@
+# Engine conformance contract (M05.2 rescope — V3_RESHAPE §5).
+# Same logical route on all 3 engines; same completion semantics where the host
+# supports blocking; documented degradation elsewhere.
+# Every class x host cell carries a support value:
+#   enforced  — the host can hard-block / a gate reads persisted state (evidence required)
+#   degraded  — the mechanism exists only as advisory text on this host (note required)
+#   advisory  — stdout/prompt text the model is asked to respect; no enforcement expected
+# Human mirror: docs/ENGINE_CONFORMANCE.md
+# Consistency enforced by: tests/consistency/engineConformance.test.js
+version: 1
+routeParity:
+  mechanism: shared-mirror   # all engines route through the same route-task.mjs
+  evidence: tests/consistency/engineConformance.test.js
+classes:
+  host-enforced:
+    description: hook can hard-block (PreToolUse deny, Stop gate, hook deadlines)
+    hosts:
+      claude-code: { support: enforced, evidence: tests/hooks/blockDangerous.test.js }
+      codex:       { support: degraded, note: 'no PreToolUse hook surface; deny rules are advisory text in AGENTS.md/settings' }
+      omp:         { support: enforced, evidence: tests/hooks/ompHookBridge.test.js }
+  state-checked:
+    description: persisted state a gate reads (completionEvidence, ledger counters, riskEscalation)
+    hosts:
+      claude-code: { support: enforced, evidence: tests/hooks/executionLedgerRiskGate.test.js }
+      codex:       { support: degraded, note: 'no Stop hook; completionEvidence is advisory in .codex/README.md' }
+      omp:         { support: enforced, evidence: tests/hooks/ompHookBridge.test.js }
+  advisory:
+    description: stdout/prompt text the model is asked to respect (routes, suppress, budgets)
+    hosts:
+      claude-code: { support: advisory }
+      codex:       { support: advisory }
+      omp:         { support: advisory }

package/manifests/hostCapabilities.yaml

@@ -32,8 +32,8 @@ hosts:
     subagents:               { state: tested,    evidence: tests/consistency/ompAgentParity.test.js }
     hooks:                   { state: tested,    evidence: tests/hooks/ompHookBridge.test.js }
     session-start-injection: { state: tested,    evidence: tests/hooks/ompHookBridge.test.js }
-    stop-gate:               { state: unknown }
+    stop-gate:               { state: tested,    evidence: tests/hooks/ompHookBridge.test.js }
     slash-commands:          { state: observed,  note: 'delegation parentheticals checked by tests/consistency/ompCommandParity.test.js' }
     owner-file-injection:    { state: unknown }
-    settings-env:            { state: observed,  note: 'templates/.omp/config.yml modelRoles reviewed by ompAgentParity' }
+    settings-env:            { state: observed,  note: 'template_project/.omp/config.yml modelRoles reviewed by ompAgentParity' }
     context-files:           { state: observed,  note: 'omp consumes AGENTS.md/CLAUDE.md context layer; no dedicated test' }