@ngockhoale/ukit 2.6.6 → 2.6.7

package/src/render/instructionRenderer.js

@@ -0,0 +1,226 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+
+import { renderTemplateString } from './renderTemplate.js';
+
+/**
+ * Deterministic core/overlay renderer for the five instruction-contract
+ * outputs (SPEC §8.1, FR-004..FR-007). Pure functions; disk access only in
+ * renderInstructionsFromDisk / checkRenderedInstructions.
+ *
+ * Emission rules (byte-exact):
+ *   h1 + '\n' + banner + '\n\n' + blocks.join('') [+ trailer] [+ '\n']
+ * where each `## ` block is `## <heading>` + the raw body slice — the body
+ * keeps its leading AND trailing whitespace, so concatenation reproduces
+ * the source bytes exactly; the reserved
+ * `__preamble__` block is the source's leading non-## text verbatim.
+ */
+
+export const PREAMBLE_KEY = '__preamble__';
+
+const SECTION_HEADING_RE = /^## (.+)$/gm;
+const LEFTOVER_TOKEN_RE = /\{\{\s*([a-zA-Z0-9_.-]+)\s*\}\}/;
+
+/**
+ * Split markdown into a Map<heading, body> at `## ` boundaries.
+ * `### ` and deeper stay inside the enclosing body. Leading non-## text lands
+ * under the reserved `__preamble__` key (absent when the file starts with `## `).
+ * Throws on a duplicate `## ` heading, naming it.
+ */
+export function parseSections(markdown) {
+  const sections = new Map();
+  const matches = [...markdown.matchAll(SECTION_HEADING_RE)];
+  const first = matches[0];
+
+  const preamble = first ? markdown.slice(0, first.index) : markdown;
+  if (preamble.trim().length > 0) {
+    // Raw slice kept verbatim: its trailing newline(s) are the separator
+    // before the first ## section (e.g. the RULES.md preamble block).
+    sections.set(PREAMBLE_KEY, preamble);
+  }
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const heading = m[1].trimEnd();
+    if (sections.has(heading)) {
+      throw new Error(`duplicate ## heading in source: ${heading}`);
+    }
+    const bodyStart = m.index + m[0].length;
+    const bodyEnd = i + 1 < matches.length ? matches[i + 1].index : markdown.length;
+    // Raw slice up to (not including) the next `## ` heading — leading AND
+    // trailing whitespace are byte-meaningful (marker line vs blank line
+    // under the heading; multi-blank separators between sections).
+    sections.set(heading, markdown.slice(bodyStart, bodyEnd));
+  }
+
+  return sections;
+}
+
+/**
+ * Render one layout output. `outputSpec` = layout.outputs[i];
+ * `sources` = { <sourceName>: Map<heading, body> }; `vars` = flat/nested
+ * variables applied when `outputSpec.resolve_vars` is true.
+ * Reserved specifiers: heading '__preamble__' emits the source's leading
+ * non-## block verbatim (no `## ` prefix); heading '*' expands to every
+ * `## ` section of that source in file order.
+ */
+export function renderOutput(outputSpec, sources, vars = {}) {
+  if (!Array.isArray(outputSpec.sections) || outputSpec.sections.length === 0) {
+    throw new Error(`output ${outputSpec.target}: sections must be a non-empty list`);
+  }
+
+  const blocks = [];
+  for (const ref of outputSpec.sections) {
+    const source = sources.get(ref.from);
+    if (!source) {
+      throw new Error(`output ${outputSpec.target}: unknown source '${ref.from}'`);
+    }
+    if (ref.heading === '*') {
+      for (const [heading, body] of source) {
+        if (heading === PREAMBLE_KEY) continue;
+        blocks.push(`## ${heading}${body}`);
+      }
+      continue;
+    }
+    if (ref.heading === PREAMBLE_KEY) {
+      if (!source.has(PREAMBLE_KEY)) {
+        throw new Error(
+          `output ${outputSpec.target}: source '${ref.from}' has no __preamble__ block`,
+        );
+      }
+      blocks.push(source.get(PREAMBLE_KEY));
+      continue;
+    }
+    if (!source.has(ref.heading)) {
+      throw new Error(
+        `output ${outputSpec.target}: heading '${ref.heading}' missing from source '${ref.from}'`,
+      );
+    }
+    blocks.push(`## ${ref.heading}${source.get(ref.heading)}`);
+  }
+
+  let out = `${outputSpec.h1}\n${outputSpec.banner}\n\n${blocks.join('')}`;
+  if (outputSpec.trailer !== undefined && outputSpec.trailer !== null && outputSpec.trailer !== '') {
+    if (!out.endsWith('\n')) out += '\n';
+    out += `${outputSpec.trailer}`;
+  }
+  if (!out.endsWith('\n')) out += '\n';
+
+  if (outputSpec.resolve_vars) {
+    out = renderTemplateString(out, vars);
+    const leftover = out.match(LEFTOVER_TOKEN_RE);
+    if (leftover) {
+      throw new Error(
+        `output ${outputSpec.target}: unresolved template variable '{{${leftover[1]}}}'`,
+      );
+    }
+  }
+  return out;
+}
+
+/**
+ * Render every output in `layout` from `sourceTexts` ({name: markdown}).
+ * Source names are looked up as `sources.get(ref.from)`; overlay sources are
+ * named `overlay:<file-stem>` by convention in renderInstructionsFromDisk.
+ * `varsByResolve` supplies variables to outputs with resolve_vars: true.
+ * FR-006 strictness: a `## ` section in any source referenced by zero outputs
+ * throws, naming the heading.
+ */
+export function renderAll(layout, sourceTexts, varsByResolve = {}) {
+  if (!layout || !Array.isArray(layout.outputs) || layout.outputs.length === 0) {
+    throw new Error('layout.outputs must be a non-empty list');
+  }
+
+  const sources = new Map(
+    Object.entries(sourceTexts).map(([name, text]) => [name, parseSections(text)]),
+  );
+
+  // Referenced-heading accounting for the unreferenced-section check.
+  const referenced = new Map(); // sourceName -> Set<heading>
+  const mark = (from, heading) => {
+    if (!referenced.has(from)) referenced.set(from, new Set());
+    referenced.get(from).add(heading);
+  };
+  for (const spec of layout.outputs) {
+    for (const ref of spec.sections || []) {
+      if (ref.heading === '*') {
+        const source = sources.get(ref.from);
+        if (!source) throw new Error(`unknown source '${ref.from}' referenced by '*'`);
+        for (const heading of source.keys()) {
+          if (heading !== PREAMBLE_KEY) mark(ref.from, heading);
+        }
+      } else if (ref.heading !== PREAMBLE_KEY) {
+        mark(ref.from, ref.heading);
+      }
+    }
+  }
+  for (const [name, source] of sources) {
+    for (const heading of source.keys()) {
+      if (heading === PREAMBLE_KEY) continue;
+      if (!referenced.get(name) || !referenced.get(name).has(heading)) {
+        throw new Error(`source '${name}': ## section '${heading}' referenced by zero outputs`);
+      }
+    }
+  }
+
+  const rendered = new Map();
+  for (const spec of layout.outputs) {
+    const vars = spec.resolve_vars ? varsByResolve : {};
+    rendered.set(spec.target, renderOutput(spec, sources, vars));
+  }
+  return rendered;
+}
+
+const SOURCE_FILES = {
+  core: 'templates/instructions/core.md',
+  'overlay:claude': 'templates/instructions/overlays/claude.md',
+  'overlay:agents': 'templates/instructions/overlays/agents.md',
+  'overlay:omp-rules': 'templates/instructions/overlays/omp-rules.md',
+  'overlay:repo': 'templates/instructions/overlays/repo.md',
+};
+
+/**
+ * Read layout + sources + repo-vars + package.json version from disk, render
+ * all outputs, and (write=true) write each target. Returns Map<target, content>.
+ */
+export async function renderInstructionsFromDisk({ repoRoot, write = true } = {}) {
+  const abs = (p) => path.join(repoRoot, p);
+  const layout = YAML.parse(
+    fs.readFileSync(abs('templates/instructions/layout.yaml'), 'utf8'),
+  );
+  const repoVars =
+    YAML.parse(fs.readFileSync(abs('templates/instructions/repo-vars.yaml'), 'utf8')) || {};
+  const pkg = JSON.parse(fs.readFileSync(abs('package.json'), 'utf8'));
+
+  const sourceTexts = {};
+  for (const [name, rel] of Object.entries(SOURCE_FILES)) {
+    sourceTexts[name] = fs.readFileSync(abs(rel), 'utf8');
+  }
+
+  const vars = { ...repoVars, ukit: { ...(repoVars.ukit || {}), version: pkg.version } };
+  const rendered = renderAll(layout, sourceTexts, vars);
+
+  if (write) {
+    for (const [target, content] of rendered) {
+      fs.writeFileSync(abs(target), content);
+    }
+  }
+  return rendered;
+}
+
+/**
+ * → string[] of drifted target paths (empty = clean). Drift means rendered
+ * bytes differ from disk bytes, or the target is missing.
+ */
+export async function checkRenderedInstructions({ repoRoot } = {}) {
+  const rendered = await renderInstructionsFromDisk({ repoRoot, write: false });
+  const drift = [];
+  for (const [target, content] of rendered) {
+    const file = path.join(repoRoot, target);
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) {
+      drift.push(target);
+    }
+  }
+  return drift;
+}

package/templates/.gitignore

@@ -54,8 +54,8 @@ Thumbs.db
 # templates/.claude/ukit/index/task-budget-validator.mjs). The root .gitignore
 # already carries the anchored /.claude/ /.codex/ /.omp/ /.ukit/ exclusions.
 opencode.json
-AGENTS.md
-CLAUDE.md
+/AGENTS.md
+/CLAUDE.md
 docs/STATUS.md
 docs/TASKS.md
 .codex/settings.local.json

package/templates/.omp/RULES.md

@@ -1,4 +1,5 @@
 # .omp/RULES.md — sticky always-apply rules
+<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->
 
 omp re-attaches this file near every turn from its native location (`.omp/RULES.md` only, never a
 copy elsewhere). It carries the always-apply subset of root `AGENTS.md` that must survive even when

package/templates/AGENTS.md

@@ -1,6 +1,8 @@
 # AGENTS.md — {{project.name}}
+<!-- generated: templates/instructions/ — edit sources, then yarn docs:render -->
 
 ## Core Rule
+<!-- RULES: CORE-01 CORE-02 -->
 
 - Human-facing UKit workflow should collapse to one remembered command: `ukit install`.
 - After install, default to natural-language work inside **Claude Code / Codex / OpenCode / omp**.
@@ -9,48 +11,49 @@
 
 ## Fast Classification
 
+<!-- RULE: CLS-01 -->
 - **Trivial** — typo, label, small rename, spacing, toggle flag, obvious config change.
   - Act directly. No doc reads. No planning. No index. No agents.
+<!-- RULE: CLS-02 -->
 - **Simple** — 1-2 files, clear scope, existing pattern.
   - Handle directly. Pull only the smallest useful context via resolver or targeted read.
+<!-- RULE: CLS-03 -->
 - **Non-trivial / Risky** — auth, security, migration, uninstall, shared runtime, race/flaky, data-loss.
   - Read deeper, verify harder, and avoid shortcuts.
   - Use index-first loop, then skill activation, then targeted verification.
 
 ## Execution Contract (mandatory)
 
+<!-- RULE: EXEC-01 -->
 - For explicit implement/apply/fix requests, **continue until the actual edit is made** or a real blocker is found.
 - Do NOT stop after a read-only inspection step (Read/Grep/Glob/search).
-- If routed state says `pull-indexed-context`, treat it as internal continuation — after the bounded read, **continue to edit/verify in the same turn** when safe.
+<!-- RULE: EXEC-03 -->
+- If routed state says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point — after the bounded read, **continue to edit/verify in the same turn** when safe.
 - If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or repeating analysis.
+<!-- RULE: EXEC-02 -->
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
+<!-- RULE: EXEC-04 -->
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
 ## Long-Run Continuity
+<!-- RULES: LONG-01 LONG-02 -->
 
-Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
-
-- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
-- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
-- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+- Near token-cap: **LAND one thing** end-to-end (edit + verify, ≤3 tool calls), **DEFER** the rest into `docs/STATUS.md` or bounded `docs/AI_HANDOFF/` tasks, **DELEGATE** broad work to subagents. Only then compact.
+- After any compact or handoff: continue from the persisted disk state — never reread pre-compact context; delegate broad work, keep replies short.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — every such stop names its reason (Execution Contract). Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Index-First Loop
 
 For any task that needs code context:
 
-1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh:
-   - `node .claude/ukit/index/refresh-index.mjs`
-   - fallback: `node .claude/ukit/index/build-index.mjs`
-2. Query likely files:
-   - `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`
-3. For bug signatures:
-   - `node .claude/ukit/index/triage.mjs "<error signature>"`
-4. Open only the **top 1-3 suspect files first**, then widen if needed.
-   `query-index` and `resolve-context` print an `outline:` block (`line: signature`) for the
-   top suspects. Use it to jump straight to the relevant region with
-   `Read(file, offset=<line>)` instead of reading the whole file.
-   The outline locates code; it does not describe behaviour. **Any code you are about to
-   change must still be read.**
+<!-- RULE: IDX-01 -->
+1. Check if index is fresh (`.cache/index/` artifacts). If stale or missing, refresh (`node .claude/ukit/index/refresh-index.mjs`).
+2. Query likely files: `node .claude/ukit/index/query-index.mjs "<error|symbol|path>"`.
+3. For bug signatures: `node .claude/ukit/index/triage.mjs "<error signature>"`.
+<!-- RULE: IDX-02 -->
+4. Open only the **top 1-3 suspect files first**, then widen if needed. `query-index`/`resolve-context` print an `outline:` block — jump straight to `Read(file, offset=<line>)`.
+<!-- RULE: IDX-03 -->
+   The outline locates code; it does not describe behaviour. **Any code you are about to change must still be read.**
 5. For analog/reuse patterns, check if `resolve-context` returns related existing patterns.
 
 For clearly non-code specialist lanes (docs-only, status, task queue), skip the source-code index.
@@ -58,14 +61,12 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 ## Automatic Skill Activation (mandatory)
 
 - End users should not need to know skill names.
+<!-- RULE: SKILL-01 -->
 - On every non-trivial task — and again after the first relevant tool calls — inspect installed project-local skills and **auto-activate the matching skill immediately**.
 - Match from both prompt wording and tool/file evidence.
-- Use the smallest effective set, usually 1-2 skills.
-- If evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
-- If docs work is detected, read `.claude/skills/docs-quality/SKILL.md` when present.
-- Prefer routed context and routed verification over ad-hoc broad reading.
-- Reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
-- If shared route state already includes `previous-context` or `recent-output`, reuse those first.
+<!-- RULES: SKILL-02 SKILL-03 -->
+- Use the smallest effective set, usually 1-2 skills; if evidence becomes more specific than the original prompt, upgrade the active skill choice immediately.
+- Prefer routed context and routed verification over ad-hoc broad reading; reuse `.claude/ukit/skill-router-state.json` when it already carries compact route memory.
 
 ### Common skill triggers
 
@@ -80,12 +81,11 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 
 ## Internal Helper Policy
 
-- Prefer `node .claude/ukit/index/route-task.mjs "<prompt>" [--tool-command <cmd>] [--target <file>]` when routing is complex or ambiguous.
-- Prefer `node .claude/ukit/index/resolve-context.mjs ...` for indexed related-file context.
-- Prefer `node .claude/ukit/index/verify-context.mjs ...` for concrete verification lanes.
-- **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
-- Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
-- If the workspace needs a refresh, prefer telling them to rerun `ukit install`.
+<!-- RULES: HELP-01 HELP-02 -->
+- Prefer the internal index helpers (`node .claude/ukit/index/route-task.mjs`, `resolve-context.mjs`, `verify-context.mjs`) for routing, related-file context, and verification lanes.
+- **Do not ask normal contributors to run internal helper commands** or memorize maintainer commands (`ukit doctor`, `ukit diff`, `ukit uninstall`) — run them yourself.
+<!-- RULE: FALLBACK-01 -->
+- If the workspace needs a refresh or runtime files are missing/corrupt, tell maintainers to rerun `ukit install`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Skill Quality (maintainer-only)
 
@@ -93,150 +93,90 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 
 ## UKit v{{ukit.version}} Shared Runtime
 
-- Shared runtime state lives in `.ukit/storage/`.
-- Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, validation, and Safe Patch behavior.
-- Reuse `.ukit/storage/memory/` before asking users to restate decisions.
-- For non-trivial work, prefer `ukit memory recall "<current task>"` before widening doc reads.
-- Reusable cache/compact/output state lives in `.ukit/storage/cache/prompt-cache.json`, `.ukit/storage/cache/compact-history.json`, `.ukit/storage/cache/compact-pressure.json`, `.ukit/storage/cache/output-history.json`, and preserved raw tool outputs under `.ukit/storage/cache/tee/`.
-- Shared route memory lives in `.claude/ukit/skill-router-state.json`.
-- If shared route state already includes compact `previous-context` or `recent-output`, reuse those first.
-- If an older repo still has a visible `ukit/` runtime root, rerun `ukit install`; UKit should migrate the shared runtime into hidden `.ukit/` when safe.
-- Maintainers can inspect runtime state with `ukit status` and `ukit memory export`, but normal teammates should still only need `ukit install`.
-- If runtime files are missing or corrupt, tell maintainers to rerun `ukit install`.
-- Threshold-based compact pressure is internal orchestration; do not expose it to users.
-- For Codex Desktop long sessions, UKit can use soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 tokens.
+- Shared runtime state lives in `.ukit/storage/`; `.ukit/storage/config.json` is the source of runtime toggles (compact, token pipeline, router, memory, validation, Safe Patch).
+- Reuse `.ukit/storage/memory/` and `ukit memory recall "<current task>"` before asking users to restate decisions or widening doc reads; maintainers can inspect state with `ukit status` / `ukit memory export`.
+- Shared route memory lives in `.claude/ukit/skill-router-state.json`; reuse compact `previous-context`/`recent-output` first.
+- If runtime files are missing/corrupt or an old visible `ukit/` root remains, rerun `ukit install`. Cache state (`.ukit/storage/cache/output-history.json`, tee/) + Codex handoff detail: `docs/UKIT_INTERNALS.md`.
 
 ## Prompt Caching
+<!-- RULES: CTX-01 CTX-02 CTX-03 CTX-04 CTX-05 CTX-06 CTX-07 CTX-08 CTX-09 CTX-10 -->
 
-- Deterministic, stable context lets a provider reuse a prompt prefix — and it is worth doing even when no caching is guaranteed.
 - Full ruleset: `docs/PROMPT_CACHING.md` (read on demand; it is not loaded into every session).
 - CTX-01 deterministic segment bytes · CTX-02 keep roles and order · CTX-03 keep tool IDs and continuation state · CTX-04 no clock/random IDs in static blocks · CTX-05 compaction starts a new epoch · CTX-06 never change data to match a cache · CTX-07 no unconfirmed cache fields · CTX-08 tool-result reuse needs valid freshness · CTX-09 missing usage is unknown, not zero · CTX-10 never cut a required check to reduce calls.
-- Never sort messages, trim meaningful whitespace, rewrite reasoning fields, or move a user request into system context.
-- Upstream vendor docs are reference only — never a guarantee about the route you actually use.
 
 ## Safe Patch Protocol
+<!-- RULES: SAFE-02 SAFE-03 SAFE-01 -->
 
-- Safe Patch is internal orchestration: normal users still only need `ukit install` and natural language.
-- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks.
-- Do not silently merge stale specs: if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
+- For risky/shared/large edits, prefer unique current-file anchors over line numbers or stale pasted blocks; if `old_string` is missing or ambiguous, re-read current source and ask whether to apply as-is, adapt, or skip.
 - Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual/user-authored files.
-- Use `node .claude/ukit/index/safe-patch.mjs` internally when normal Edit/Write may normalize bytes or when anchor-based matching is needed.
+- Internal helper + detail: `docs/UKIT_INTERNALS.md` (`node .claude/ukit/index/safe-patch.mjs`).
 
 ## Handoff Quality Gate — OPT-IN
+<!-- RULE: HAND-01 -->
 
 CHỈ kích hoạt khi task đi qua `docs/AI_HANDOFF/` (user nói "execute task TASK-xxx" hoặc target là `docs/AI_HANDOFF/tasks/*.md`). Daily prompt → KHÔNG đụng, flow cũ giữ nguyên.
 
 Khi Handoff mode: đọc `docs/AI_HANDOFF/RULES.md` để biết 4 phase (Idea+Plan → Create Tasks → Implement+Test → Review+Test) + state machine + comment thread + self-report model. Config: `.ukit/storage/config.json` → `handoff.*`.
 
 ## Context + Verification Budget
+<!-- RULE: BUDGET-01 -->
 
 - **Trivial**: no docs, and no index query unless the file target is unclear.
 - **Simple**: `docs/MEMORY.md` only, plus resolver-selected files/tests.
 - **Non-trivial**: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`.
-- `docs/STATUS.md`: use for open-ended status/continue prompts or meaningful continuation context; stale status is orientation only.
-- `docs/TASKS.md`: use only for queued-task prompts or when status points at queued work; safely clean exact duplicates/completed overflow by default without deleting unfinished human-authored tasks.
-- `docs/WORKLOG.md`: only recent relevant entries. Follow the Budget Rules at the top of the file; archive oldest entries to `docs/WORKLOG_ARCHIVE.md` when over limits.
+<!-- RULES: BUDGET-02 BUDGET-03 -->
+- `docs/STATUS.md` for open-ended/continue prompts; `docs/TASKS.md` only for queued-task prompts; `docs/WORKLOG.md` recent entries only (archive overflow).
 - Follow routed verification policy: targeted first, widen only when risk/shared scope justifies it, ask before blanket broad runs.
 
 ## Living Status Workflow
+<!-- RULE: STATUS-01 -->
 
-- `docs/STATUS.md` captures compact current state, active work, debug threads, blockers, verification, and next candidates.
-- It is not source truth and must not replace source/index-first investigation.
-- For "what next?" / "continue" prompts without a concrete target, use `next-step` and show a freshness cue before relying on the status file.
-- For concrete debug/implementation/review prompts, keep the concrete workflow primary even if the user asks for an approach or next step.
-- After meaningful work, use `update-status`; skip trivial/no-state-change tasks and avoid transcript-style noise.
-- `docs/TASKS.md` is a local AI task queue: prefer `Ready for AI` when asked to pick queued work, and clean duplicates/prune `Done Recently` safely when reading/updating it.
+- `docs/STATUS.md` captures compact current state; it is not source truth and must not replace source/index-first investigation.
+- For "what next?" / "continue" prompts, use `next-step` with a freshness cue; after meaningful work use `update-status`. `docs/TASKS.md` is the local AI task queue — prefer `Ready for AI`. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Small-Task Maintainer (internal)
+<!-- RULE: SUBAG-02 -->
 
-- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
-- Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
-- Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task.
-- If the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model.
-- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow.
-- Always preserve the CoDev priority: quality > safety > speed > token discipline.
+- The `ukit-small-task-maintainer` subagent (`subagents.smallTaskModel`, default `unic-lite`) handles safe/reversible UKit chores as a sidecar lane — never block or slow the user task; risky work hands back to the main model. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Post-Edit Sidecar Review (internal)
 
-- If routed state's `routeSummary.line` includes a `review=code-reviewer(diff)` segment, a `local-build` or `shared-edit` task qualifies for a non-blocking second opinion — this exists because the daily-flow executor model can miss edge cases.
-- Only launch it once write evidence AND verification evidence already exist for the task (never before; never as a substitute for either).
-- Launch the `code-reviewer` agent (see the harness table under 3-Tier Model Routing) with `REVIEW_TARGET_TYPE=diff`, in the background, on the `smart` tier per `subagents.diffReviewModel`. Do not wait for it — continue and report the task as done using the normal completion rules.
-- Its findings are advisory only: never re-open, block, or delay the already-reported completion on their account. Surface them to the user as a follow-up note if/when they arrive.
-- This is internal orchestration — end users never invoke it directly; `ukit install` plus natural language remains the whole surface. No new commands.
+- When routed state's `routeSummary.line` carries `review=code-reviewer(diff)`, launch the `code-reviewer` agent in the background (`smart` tier) **only after** write + verification evidence exists; findings are advisory — never block the already-reported completion. Detail: `docs/UKIT_INTERNALS.md`.
 
 ## Selective Subagent Policy (internal only)
+<!-- RULE: SUBAG-01 -->
 
-- Keep direct execution as the default for trivial/simple work.
-- Delegate only when it meaningfully shrinks context or enables useful parallel progress.
-- Good delegation triggers:
-  - noisy side lanes (broad logs/search/test output)
-  - 3+ independent failures/files/checks
-  - explicit batch/plan execution
-  - broad implementation/debug lanes that can return a concise summary
-- If route memory includes `delegate=<lane>`, treat it as an internal hint after any required indexed-context step.
+- Keep direct execution as the default for trivial/simple work; delegate only when it meaningfully shrinks context or enables useful parallel progress (noisy side lanes, 3+ independent failures, batch plans, broad debug lanes).
 - Do not ask end users to name agents or remember agent commands.
 
 ## Adaptive Autonomy
+<!-- RULE: AUTO-01 -->
 
 - `autonomy.level` in `.ukit/storage/config.json` controls how much UKit acts without asking first: `conservative` (ask more), `balanced` (default), `free-run` (auto-run more), `vibecode` (run one prompt to a finished result; the completion gate stops only on completion evidence, a genuine blocker, or a dangerous-command decision).
 - End users should not need to change this; maintainers may tune it per-project.
 
 ## 3-Tier Model Routing
+<!-- RULES: TIER-01 TIER-02 -->
 
 **Internal orchestration only — end users still just use natural language. No new commands.**
 
-UKit routes tasks to one of three model tiers based on task complexity:
-
 | Tier | Generic alias | Claude model | Typical tasks |
 |------|--------------|--------------|---------------|
 | lite | `unic-lite` | claude-haiku | Reads, git queries, bash summaries, small doc edits |
 | code | `unic-code` | claude-sonnet | Normal coding, local fixes, shared edits, builds, debugging, impact mapping |
 | smart | `unic-smart` | claude-opus | Release review/audit, and escalated deep reasoning after repeated failure |
 
-### Contract-to-tier mapping
-
-| Contract | Tier |
-|----------|------|
-| `tiny-fix` | lite |
-| `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` | code |
-| `review-release` | smart |
-
-### How a tier is actually bound
-
-The main session model never changes mid-turn. A tier only takes effect when work is handed to
-an agent whose own definition binds that model:
-
-| Harness | Agent definitions | How to launch one |
-|---------|-------------------|-------------------|
-| Claude Code | `.claude/agents/*.md` (`model:` frontmatter) | Agent tool, `subagent_type: "<name>"` |
-| omp | `.omp/agents/*.md` (`model: "@lite"` / `"@code"` / `"@smart"` / `"@vision"`, resolved through `modelRoles` in `.omp/config.yml`) | task-agent `<name>` |
-
-When a task's contract maps to a tier other than the current session model, hand it to the
-matching agent instead of doing it inline. Doing everything inline is exactly what makes UKit
-behave as if it only had one model — the tier table above has no effect on its own.
-
-### Escalation rule
-
-When the same file or symbol fails `debugLoopThreshold` (default: 2) times in one session, UKit routes the next attempt one tier higher (capped at `smart`). Config: `orchestration.escalation` in `.ukit/storage/config.json`.
-
-This is internal orchestration — end users do not need to know about tiers, thresholds, or escalation. The AI handles routing transparently.
-
-### Vision lane (capability, not a cost tier)
-
-`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. Whether a mapping can read images is a capability fact, not a provider fact: a mapping that has not **verified** native vision must never guess at image contents — choose native-first when verified, otherwise route to the specialist.
-
-- **Gateway detection**: UNIC routing for a Claude Code session is decided ONLY by what changes Claude Code's own outbound endpoint — `ANTHROPIC_BASE_URL` (env var, or the `env.ANTHROPIC_BASE_URL` key in project/home `.claude/settings.json`) containing `unicjsc.com`. Other tools' configs — Codex `config.toml`, Kilo `secrets.json`, or an `OPENAI_BASE_URL` env var — describe a different tool's endpoint entirely and never decide this session's routing.
-- **Advisory routing (no hard block)**: when an image reaches the prompt, the vision router reminds the session to have `ukit-vision-analyst` analyse it before relying on its contents. Edits are **never blocked** — correctness relies on the model routing images to the analyst instead of guessing.
-- This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
+- The main session model never changes mid-turn: a tier takes effect only when work is handed to an agent whose own definition binds that model (`model:` frontmatter in `.claude/agents/*.md`; `model:` `@lite`/`@code`/`@smart`/`@vision` in `.omp/agents/*.md` resolved via `modelRoles`).
+- Contract map: `tiny-fix` → lite · `local-fix`, `local-build`, `shared-edit`, `find-cause`, `map-impact` → code · `review-release` → smart.
+- Escalation: same file/symbol failing `debugLoopThreshold` (default 2) times in one session routes the next attempt one tier higher, capped at `smart`.
+- `unic-vision` is a capability lane, not a cost tier — unverified vision must never guess at image contents; route images to `ukit-vision-analyst`. Full harness table + gateway detection detail: `docs/UKIT_INTERNALS.md`.
 
 ## Session Start — OpenCode
 
+<!-- RULE: HOST-OC-01 -->
 At the start of every OpenCode session, before working on the first task:
-1. Check `.claude/ukit/skill-router-state.json` — if `line` has route hints matching the current task, reuse them instead of re-routing from scratch.
-2. Note which skills are installed by scanning `.claude/skills/` (directory listing only); read the full SKILL.md only when a task triggers it.
-3. For every non-trivial task: run `/ukit-route <task summary>` immediately to get skill + context hints **before** writing any code.
-4. If the route result points to a skill, read that SKILL.md before acting — do not skip this step.
-5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router output over ad-hoc guessing.
+1. Reuse matching route hints from `.claude/ukit/skill-router-state.json`; scan `.claude/skills/` (listing only) and read a SKILL.md only when a task triggers it.
+2. For every non-trivial task, run `/ukit-route <task summary>` for skill + context hints **before** writing code; if it names a skill, read that SKILL.md — do not skip. When `router.enabled: true` in `.ukit/storage/config.json`, prefer router output over guessing; treat it as internal continuation — continue to edit/verify, don't stop.
 
 ## Project Owner Instructions — Codex and OpenCode
 
@@ -245,13 +185,12 @@ When running in Codex or OpenCode, read and follow the root
 project-owner instruction source. Do not copy its contents into this file.
 If it is missing or unreadable, state that limitation and continue with the
 remaining project instructions.
-
+<!-- RULES: OWN-01 HOST-OWN-01 -->
 ## Skills
 
-- Canonical skills live in `.claude/skills/`.
-- Adapter mirrors may also exist, for example `.codex/skills/` → `.claude/skills/` (symlink). **omp** has no mirror: it reads `.claude/skills/` directly through its own `claude` discovery provider.
-- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load `.claude/skills/`. The model must explicitly read the triggered SKILL.md.
-- If `opencode.json` ships `ukit-*` commands, treat them as internal helper entrypoints only and **never ask end users to run them**; humans should still only need `ukit install`.
+- Canonical skills live in `.claude/skills/`; adapter mirrors may exist (`.codex/skills/` → symlink). **omp** reads `.claude/skills/` directly via its `claude` discovery provider.
+- **OpenCode**: reads `AGENTS.md` at session start only — it does NOT auto-load skills; the model must explicitly read the triggered SKILL.md.
+- `ukit-*` commands in `opencode.json` are internal helper entrypoints — never ask end users to run them.
 
 ## Project Snapshot
 
@@ -262,25 +201,13 @@ remaining project instructions.
 ## Working Rules
 
 - Keep scope tight, prefer the smallest correct change set, and reuse existing code.
-- For explicit implement/apply/fix requests, keep working until the actual edit is made or a real blocker is found; do not stop after a read-only inspection step.
-- If routed state still says `pull-indexed-context`, treat it as an internal continuation step, not a stopping point.
-- If routed state shows `continuation required` or a stuck-lane rescue mode, finish the named milestone before widening reads or rephrasing the same partial status.
-- Never claim "done", "applied", or "fixed" after Read/Grep/analysis alone. Completion language requires concrete Edit/Write evidence in the current turn, plus verification when the change is risky.
-- Update `docs/WORKLOG.md` after significant work.
-- If source contradicts docs, update docs immediately.
+- Update `docs/WORKLOG.md` after significant work; if source contradicts docs, update docs immediately.
 - Use `{{runtime.packageManager}}`.
 
 ## DuraOne Skill — Conditional Activation
+<!-- RULE: DURA-01 -->
 
-DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại.
-
-- Khi active: luôn đọc `.claude/skills/duraone/SKILL.md` trước khi code.
-- References:
-  - `.claude/skills/duraone/references/frontend.md`
-  - `.claude/skills/duraone/references/backend.md`
-  - `.claude/skills/duraone/references/sql.md`
-  - `.claude/skills/duraone/references/workflow.md`
-- Khi không active: dùng generic coding standards + project-specific patterns từ index.
+DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skills/duraone/SKILL.md` tồn tại — khi active, luôn đọc SKILL.md + references trước khi code; khi không, dùng generic standards + index patterns. Chi tiết: `docs/UKIT_INTERNALS.md`.
 
 ## Completion Checklist
 
@@ -289,15 +216,12 @@ DuraOne skill chỉ active khi pack `duraone` được cài hoặc `.claude/skil
 - Verification executed and reported
 - Docs updated when source truth changed
 
-
 ## Handoff Fullstack Rules
+<!-- RULE: HAND-02 -->
 
-- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` nghĩa là run còn sống — Stop gate sẽ từ chối stop và trả về `Next:` step.
-- Recap/checkpoint không bao giờ là completion — chỉ `HANDOFF FULLSTACK COMPLETE` (sau khi `Phase: done`) hoặc `HANDOFF FULLSTACK BLOCKED` (sau khi `Phase: blocked`) mới kết thúc run.
-- Resume tự động mọi task chưa xong: current, legacy, pending, interrupted, recovery (`-R<n>` thay `cancelled_superseded`), và task mới được giao.
-- Handoff-create phải viết `docs/AI_HANDOFF/SPEC.md` chi tiết trước khi tạo task; task nào cũng mang `Spec references`.
-- Kết thúc cycle: docs sync → archive `docs/AI_HANDOFF/archive/cycle-NN/` → `Phase: done` → Final Report có marker.
-- `handoff-clear` bắt buộc đóng RUN.md (`Phase: done` hoặc xóa) — cursor sống sẽ giữ Stop gate chặn session sau.
+- `docs/AI_HANDOFF/RUN.md` là run cursor có thẩm quyền; `Phase:` ≠ `done`/`blocked` nghĩa là run còn sống — Stop gate từ chối stop và trả về `Next:` step.
+- Recap/checkpoint không bao giờ là completion — chỉ `HANDOFF FULLSTACK COMPLETE` (sau `Phase: done`) hoặc `HANDOFF FULLSTACK BLOCKED` (sau `Phase: blocked`) mới kết thúc run. Resume tự động mọi task chưa xong (current, legacy, pending, interrupted, recovery `-R<n>`).
+- Kết thúc cycle: docs sync → archive `docs/AI_HANDOFF/archive/cycle-NN/` → `Phase: done`. `handoff-clear` bắt buộc đóng RUN.md. Full rules: `docs/AI_HANDOFF/RULES.md`.
 
 ## Compact Instructions