@ngockhoale/ukit 2.6.6 → 2.6.7

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to UKit are documented here.
 
+## 2.6.7 - 2026-09-19
+
+Canonical-instructions release — second roadmap slice (cycle C25,
+DOC-101..107). Root instruction files are now generated from a single
+canonical source; shipped contracts shrink ~25%; no runtime behavior
+changes to install/update/uninstall flows.
+
+- **DOC-102 — deterministic core/overlay renderer**: new
+  `templates/instructions/` sources (`core.md` + host overlays +
+  `layout.yaml`) rendered by `src/render/instructionRenderer.js` into
+  `templates/CLAUDE.md`, `templates/AGENTS.md`, `templates/.omp/RULES.md`
+  (plus repo roots). `yarn docs:render` regenerates; `yarn docs:render:check`
+  fails CI on drift. Byte-stable, duplicate-heading and unreferenced-section
+  errors enforced.
+- **DOC-101 — rule IDs + markers**: `manifests/instructionRules.yaml`
+  declares 48 rule IDs (kind/anchor/marker_in); `<!-- RULE: ID -->` markers
+  embedded in the 4 marker-bearing artifacts; `instructionRules.test.js`
+  validates schema, marker coverage, and anchor presence.
+- **DOC-103 — parity → semantic tests**: `contextDocsParity.test.js`
+  rewritten to generated-artifact checks (drift, rule coverage, overlay
+  heading allowlists, Release Policy boundary) + mutation tests that fail
+  on dropped/duplicate critical rules; shared helpers in
+  `tests/consistency/helpers/semanticParity.js`.
+- **DOC-104 — root contract shrink ≥25%**: `templates/CLAUDE.md` 288→214
+  lines, `templates/AGENTS.md` 305→229 (all critical rule markers + anchors
+  preserved). Internal-orchestration detail moved to new shipped doc
+  `templates/docs/UKIT_INTERNALS.md` (manifest item `docs-ukit-internals`);
+  baselines recorded in `docs/_baseline/root-instruction-lines.txt`.
+- **DOC-105 — WORKLOG rotation + MEMORY cleanup**: live worklog ≤500 lines,
+  rotated entries preserved in `docs/WORKLOG_ARCHIVE.md` (regression-tested);
+  MEMORY.md trimmed to durable protocol/decisions/constraints (≤200).
+- **DOC-106 — PROJECT_IMPORTANT_SPEC archived**: shrunk to a decision
+  record; full body at `docs/archive/specs/PROJECT_IMPORTANT_SPEC.md`;
+  `docArchiveLinks.test.js` guards link integrity.
+- **DOC-107 — user-first README**: rewritten around `ukit install` +
+  natural-language flow (115 lines); maintainer detail moved to linked docs.
+
 ## 2.6.6 - 2026-09-19
 
 Documentation-hardening release — first slice of the

package/README.md

@@ -2,52 +2,33 @@
 
 UKit installs a project-local AI workspace (`.claude/`, adapters, docs, and index helpers) so your team can work with Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi) from the same repo setup.
 
-## Highest-Priority Team Rule
+## Install
 
-**For normal team usage, the only UKit command anyone should need to remember is `ukit install`.**
+1. Install the UKit CLI globally:
 
-After `ukit install` finishes:
-- open your AI tool
-- describe the task in natural language
-- let the workspace instructions route the flow
-
-How the CLI binary itself gets installed or refreshed is a maintainer/platform concern.
-Inside projects, the command teammates should remember remains **`ukit install`**.
-
-Do **not** onboard the whole team around `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...`. Those commands can still exist for maintainers/debugging, but they are intentionally **not** the default human workflow.
-
-## Team Workflow
-
-1. Install the UKit CLI globally.
    ```bash
    npm install -g @ngockhoale/ukit
    ```
-2. Open any project root in the terminal.
-3. Run:
 
-```bash
-ukit install
-```
+2. Open any project root in the terminal and run:
 
-4. Fill in the generated docs baseline:
-   - `docs/PROJECT.md`
-   - `docs/MEMORY.md`
-   - `docs/AI_HANDOFF/`
-   - `docs/WORKLOG.md`
-5. Open your AI tool and work in natural language.
+   ```bash
+   ukit install
+   ```
 
-## Update Policy
+The same `ukit install` command handles both first-time setup and refreshes. If UKit changes, your templates change, or a teammate needs to re-apply the workspace, rerun `ukit install`.
 
-The same command handles both first-time setup and refreshes:
+## After install
 
-```bash
-ukit install
-```
+For normal team usage, `ukit install` is the only UKit command anyone should need to remember:
 
-If UKit changes, your templates change, or a teammate needs to re-apply the workspace, rerun `ukit install`.
-If maintainers roll out a newer CLI build, the in-project workflow still stays the same: rerun `ukit install`.
+- open your AI tool
+- describe the task in natural language
+- let the workspace instructions route the flow
 
-## What `ukit install` Creates
+Fill in the generated docs baseline (`docs/PROJECT.md`, `docs/MEMORY.md`, `docs/AI_HANDOFF/`, `docs/WORKLOG.md`), then work in natural language. Do **not** onboard the team around `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` — those remain maintainer/debug workflows, not the default human path.
+
+## What `ukit install` creates
 
 **Core workspace**
 - `.claude/skills/` — canonical skills
@@ -73,180 +54,62 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 
 ## `PROJECT_IMPORTANT.md` — project-owner instructions
 
-`ukit install` seeds a root `PROJECT_IMPORTANT.md` **once**. After that the file is
-yours: UKit never rewrites, merges, formats, chmods, tracks, or deletes it — edits
-survive every `ukit install` rerun byte-for-byte, and deleting it + reinstalling
-seeds a fresh copy. It is also excluded from `ukit uninstall` deletion; uninstall
-backs it up to a sibling `PROJECT_IMPORTANT.md.ukit-backup[.n]` file at project
-root (never overwritten — a new suffix is chosen, and dry-run creates nothing).
+`ukit install` seeds a root `PROJECT_IMPORTANT.md` **once**. After that the file is yours: UKit never rewrites, merges, formats, or deletes it — edits survive every `ukit install` rerun byte-for-byte, and uninstall backs it up to a sibling `PROJECT_IMPORTANT.md.ukit-backup[.n]` file instead of deleting it.
 
-Put your non-negotiable project rules there. On each session start your AI tool
-receives its contents as advisory project-owner context — Claude Code and omp via
-their session hooks (and once more after a compaction, which starts a new context
-epoch), Codex and OpenCode via a static pointer in `AGENTS.md` (read-the-file
-instructions, not a runtime hook). Keep the file at or below **6,000 Unicode code
-points** — anything past that is truncated with an explicit warning, and the fix is
-to shorten the file, not rerun `ukit install`. Do not put credentials or secrets in
-it: a fail-closed sensitive-value scan runs on the exact body before injection and
-blocks anything that looks like a key or token.
+Put your non-negotiable project rules there. On each session start your AI tool receives its contents as advisory project-owner context. Keep the file at or below **6,000 Unicode code points** — anything past that is truncated with an explicit warning. Do not put credentials or secrets in it: a fail-closed sensitive-value scan runs before injection and blocks anything that looks like a key or token.
 
-## UKit v1.3.1 Runtime
+## Shared runtime
 
-UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
+UKit installs a hidden shared local runtime at `.ukit/` for production-oriented state that survives across agent sessions:
 
 - `.ukit/storage/config.json` — runtime defaults for compact/router/memory/validation/subagent hints
-- `.ukit/storage/cache/` — reusable prompt-cache, compact history, compact-pressure state, and output summaries
+- `.ukit/storage/cache/` — reusable prompt-cache, compact history, and output summaries
 - `.ukit/storage/memory/` — cross-agent local memory
 - `.ukit/storage/backups/` — rollback bytes for risky Safe Patch Protocol edits
 
-If an older repo still has a visible legacy `ukit/` runtime folder, rerunning `ukit install` now migrates the shared runtime into hidden `.ukit/` when the target paths are free.
-
-When long sessions approach the compact threshold, UKit now uses a conservative pressure lane:
-
-- soft threshold = configured compact token threshold
-- hard threshold = roughly 20% above soft
-- compact only safe-zone history/noise
-- preserve active task, rules, decisions, and current code focus
-
-UKit v1.3.1 keeps the same shared runtime contract while adding Safe Patch Protocol guardrails and the local AI task queue alongside living project status routing:
-
-- install globally with `npm install -g @ngockhoale/ukit`
-- keep using the exact same human workflow inside projects: `ukit install`
-- preserve the same `ukit` binary, hooks, and install-first orchestration while standardizing the runtime root as hidden `.ukit/`
-- install `docs/AI_HANDOFF/` as the cross-AI handoff folder with per-task isolation: ACTIVE.md (snapshot), INDEX.md (task index), tasks/ (one file per task) so each AI reads only the task it needs, with token budget rules in RULES.md
-- auto-route open-ended “what next?” / “continue” prompts to the `next-step` skill with a visible freshness cue when status may be stale
-- auto-route explicit handoff/wrap-up requests to the `update-status` skill while skipping trivial/no-state-change tasks
-- keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
-- quietly guard risky AI edits with Safe Patch Protocol: stale/ambiguous specs are blocked, shared-risk whole-file writes are discouraged, and internal helpers preserve UTF-8 BOM/no-BOM plus LF/CRLF for multilingual text
-
-UKit v1.3.1 also keeps the fast path improvements from the recent runtime releases:
-
-- Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
-- localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action
-- routed verification lanes reuse declared `packageManager` metadata so helpers/hooks stop probing every lockfile candidate unnecessarily
-
-For maintainers, the runtime is inspectable with:
-
-- `ukit status`
-- `ukit memory list`
-- `ukit memory recall "<current task>"`
-- `ukit memory export`
-
-Normal teammates should still only need **`ukit install`**.
-
-## Retuning The Context Budget (maintainers)
-
-Switching to a model with a different context window is a **three-number edit in one file**:
-`templates/ukit/storage/config.json` → `compact`.
-
-| Key | Default | What it means |
-| --- | --- | --- |
-| `tokenThreshold` | `150000` | Soft advisory. Past this UKit starts recommending compaction. |
-| `hardCapTokens` | `500000` | Absolute ceiling — 50% of a 1M window. `context-hardcap-gate` blocks Edit/Write/Bash here. |
-| `autoCompactWindowRatio` | `0.7` | Auto-compact fires at this fraction of the cap (→ `350000`). Must be `< 1`. |
-
-Everything else is derived — do **not** hand-edit these:
-
-- `.claude/settings.json` → `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW`
-- `.omp/config.yml` → `compaction.thresholdTokens`
-- the code-side defaults in `src/core/runtimeConfig.js` and `src/core/compact/threshold.js`
+When long sessions approach the compact threshold, UKit compacts only safe-zone history/noise while preserving the active task, rules, decisions, and current code focus. If an older repo still has a visible legacy `ukit/` runtime folder, rerunning `ukit install` migrates the shared runtime into hidden `.ukit/` when the target paths are free.
 
-They are all rendered/read from the three keys above via `src/core/compact/contextBudget.js`.
-Edit the three numbers, rerun **`ukit install`**, and Claude Code and omp both follow.
+## Supported tools
 
-`hardCapTokens` must stay **below the model's real context window**, otherwise the API rejects
-the request before the gate can ever fire. Sizing at 50% of the window keeps room for the
-response plus the estimator's own undercount:
-
-| Model window | `hardCapTokens` | derived auto-compact |
-| --- | --- | --- |
-| 1M | `500000` | `350000` |
-| 256k | `128000` | `89600` |
-| 200k | `100000` | `70000` |
-
-## Installer Behavior
-
-- idempotent install (safe to rerun)
-- timestamped backups before overwrite
-- template rendering with project-aware variables
-- dependency-ordered manifest execution
-- path safety checks for template and target traversal
-- shared-skill adapter linking across supported tools
-- post-install docs baseline reminders
-- automatic code-index build + refresh hook install
-
-## Working Style After Install
-
-UKit is built so the team can stop memorizing UKit subcommands and focus on product work:
-- ask for fixes, reviews, implementations, tests, or docs in natural language
-- let the installed instructions choose the right workflow
-- let the AI use the indexed source code first so it can find the right files/tests fast
-- let Claude Code / Codex / OpenCode auto-detect and use the right project-local skill from the prompt and the files/tools involved
-- let the AI prefer targeted verification first, then widen only when shared/risky scope justifies it
-- let the AI selectively auto-delegate internal subagents only when that actually reduces context/noise or unlocks parallel progress; small localized work should stay direct
-- keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal `compact.codexContext.compactTarget` soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
-- let UKit internally use the `ukit-small-task-maintainer` subagent with `subagents.smallTaskModel=unic-lite` for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
-- rerun `ukit install` when you need to refresh the workspace
-
-End users should **not** need to know or memorize skill names.
-
-## Upstream Skill Alignment
-
-To keep UKit strong over time, maintainer work should track the current upstream skill ecosystem:
-- official Anthropic skills: [anthropics/skills](https://github.com/anthropics/skills)
-- official OpenAI skills: [openai/skills](https://github.com/openai/skills)
-- Agent Skills open standard: [agentskills.io](https://agentskills.io/)
-- curated discovery lists such as [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) and [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
-
-But this is a **maintainer concern**, not a team-onboarding burden.
+| Tool | Instructions | Skills | Config |
+|------|-------------|--------|--------|
+| Claude Code | `CLAUDE.md` | `.claude/skills/` (canonical) | `.claude/settings.json` |
+| OpenAI Codex | `AGENTS.md` | `.claude/skills/` (referenced) | `.codex/settings.json`, `.codex/settings.local.json`, `.codex/README.md` |
+| OpenCode | `AGENTS.md` | `.claude/skills/` (native Claude-compatible support) | `opencode.json` |
+| omp (Oh My Pi) | `.omp/AGENTS.md` (imports `AGENTS.md`) | `.claude/skills/` (read via omp's claude provider — no symlink) | `.omp/config.yml`, `.omp/RULES.md`, `.omp/README.md` |
 
-The rule remains:
+All supported tools share the same SKILL.md ecosystem so the workspace is authored once and reused everywhere.
 
-> ship curated improvements through UKit, then ask teammates to rerun **`ukit install`**
+## Maintainer docs
 
-Do **not** require normal contributors to learn marketplace/plugin commands just to use the workspace.
+Maintainer internals live in dedicated docs — linked here, not duplicated:
 
-## Maintainer / Debug Commands
+- [`docs/CONTEXT_BUDGET.md`](docs/CONTEXT_BUDGET.md) — retuning the context budget (three-number edit)
+- [`docs/UKIT_CODEV_PRINCIPLES.md`](docs/UKIT_CODEV_PRINCIPLES.md) — CoDev working principles
+- [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) — release steps
 
-These commands are still available, but they are **advanced workflows**, not default team onboarding:
+Maintainer/debug commands (advanced workflows, not team onboarding):
 
 - `ukit diff` — preview file changes before install
 - `ukit doctor` — validate UKit state and docs baseline
 - `ukit uninstall` — remove UKit-managed assets
 - `ukit status` — inspect shared UKit runtime state
 - `ukit memory ...` — inspect/export/forget shared memory items
-- `ukit update` — upgrade the global UKit CLI to the latest published version (same as `npm install -g @ngockhoale/ukit`)
+- `ukit update` — upgrade the global UKit CLI to the latest published version
 - `ukit index ...` — run repo indexing/query/triage tools directly
 - `ukit build index` — alias for `ukit index build`
 
-Use them when maintaining UKit, debugging workspace setup, or developing the CLI itself — not as the day-to-day path every teammate must learn.
-
-## Repo Development
-
-For maintainers evolving **UKit itself**, the key repo references live in:
-
-- `docs/UKIT_CODEV_PRINCIPLES.md`
-- `docs/RELEASE_1_1_3_SIGNOFF.md`
+## Development
 
-Run the test suite from the UKit repo root:
+For maintainers evolving **UKit itself**, run the test suite from the repo root:
 
 ```bash
 yarn test
 ```
 
-For deeper index development, repo-level scripts are available:
+Repo-level index scripts:
+
 - `yarn index:build`
 - `yarn index:refresh`
 - `yarn index:query -- "<error|symbol|path>"`
 - `yarn bug:triage -- "<error signature>"`
-
-## Tool Support
-
-| Tool | Instructions | Skills | Config |
-|------|-------------|--------|--------|
-| Claude Code | `CLAUDE.md` | `.claude/skills/` (canonical) | `.claude/settings.json` |
-| OpenAI Codex | `AGENTS.md` | `.claude/skills/` (referenced) | `.codex/settings.json`, `.codex/settings.local.json`, `.codex/README.md` |
-| OpenCode | `AGENTS.md` | `.claude/skills/` (native Claude-compatible support) | `opencode.json` |
-| omp (Oh My Pi) | `.omp/AGENTS.md` (imports `AGENTS.md`) | `.claude/skills/` (read via omp's claude provider — no symlink) | `.omp/config.yml`, `.omp/RULES.md`, `.omp/README.md` |
-
-All supported tools share the same SKILL.md ecosystem so the workspace is authored once and reused everywhere.

package/manifests/documentation.yaml

@@ -15,7 +15,7 @@ entries:
     load_policy: always
     validation: [manual]
     archive_policy: never
-    notes: repo-owned copy; never overwritten by ukit install/update
+    notes: generated by yarn docs:render from templates/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: repo-owned copy; never overwritten by ukit install/update
+    notes: generated by yarn docs:render from templates/instructions/ + repo overlay
   - id: root-readme
     path: README.md
     class: canonical
@@ -35,9 +35,9 @@ entries:
     source_of_truth: README.md
     merge_strategy: none
     load_policy: on-demand
-    validation: [manual]
+    validation: [manual, test:tests/consistency/rootReadme.test.js]
     archive_policy: never
-    notes: v1.3.1 prose — DOC-107 queued
+    notes: user-first refactor shipped DOC-107 (2026-09-19)
   - id: root-quick-start
     path: QUICK_START.md
     class: canonical
@@ -195,7 +195,19 @@ entries:
     merge_strategy: none
     load_policy: on-demand
     validation: [manual]
+    archive_policy: replace-with-snapshot
+    notes: archived DOC-106 → docs/archive/specs/; live file is compact decision record
+  - id: docs-context-budget
+    path: docs/CONTEXT_BUDGET.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/CONTEXT_BUDGET.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
     archive_policy: never
+    notes: moved from README.md DOC-107
   - id: docs-prompt-caching
     path: docs/PROMPT_CACHING.md
     class: canonical
@@ -328,26 +340,60 @@ entries:
   # ── templates/ canonical authoring sources ───────────────────────────────
   - id: tpl-claude-md
     path: templates/CLAUDE.md
-    class: canonical
+    class: generated
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/CLAUDE.md
+    source_of_truth: templates/instructions/
     merge_strategy: overwrite_with_backup
     load_policy: always
-    validation: [manual]
+    validation: [manual, test:tests/consistency/instructionRender.test.js]
     archive_policy: never
-    notes: renders to installed roots
+    notes: generated by yarn docs:render from templates/instructions/ (DOC-102); renders to installed roots
   - id: tpl-agents-md
     path: templates/AGENTS.md
-    class: canonical
+    class: generated
     audience: [agent, maintainer]
     owner: product
-    source_of_truth: templates/AGENTS.md
+    source_of_truth: templates/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
+  - id: tpl-instructions
+    path: templates/instructions/
+    class: canonical
+    audience: [agent, maintainer]
+    owner: product
+    source_of_truth: templates/instructions/
+    merge_strategy: none
+    load_policy: task-routed
     validation: [manual]
     archive_policy: never
-    notes: renders to installed roots
+    notes: dir entry — core/overlay render sources (DOC-102)
+  - id: tpl-instructions-core
+    path: templates/instructions/core.md
+    class: canonical
+    audience: [agent, maintainer]
+    owner: product
+    source_of_truth: templates/instructions/core.md
+    merge_strategy: none
+    load_policy: task-routed
+    validation: [manual]
+    archive_policy: never
+    budget: { max_lines: 160, enforcement: warning }
+    notes: canonical shared core; pre-shrink >160 is warning-only (DOC-104 shrinks)
+  - id: tpl-omp-rules
+    path: templates/.omp/RULES.md
+    class: generated
+    audience: [agent, maintainer]
+    owner: adapter
+    source_of_truth: templates/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
     class: canonical
@@ -461,6 +507,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: dir sourceTemplate docs/AI_HANDOFF → dir path ending '/'
+  - id: tpl-docs-ukit-internals
+    path: templates/docs/UKIT_INTERNALS.md
+    class: canonical
+    audience: [agent, maintainer]
+    owner: product
+    source_of_truth: templates/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
     class: canonical