@ngockhoale/ukit 2.6.5 → 2.6.7

package/manifests/instructionRules.yaml

@@ -0,0 +1,376 @@
+version: 1
+generated: false
+description: >-
+  Canonical rule-ID catalog for the root instruction contracts. Marker comments
+  <!-- RULE: ID --> tag normative behavior; semantic tests prove delivery.
+# marker_in values are drawn from the fixed set of the four marker-bearing
+# contract files {templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md}.
+# templates/.omp/RULES.md and .omp/RULES.md are marker-free by SPEC §7.1 policy
+# and must never appear here.
+# DEVIATION from SPEC §7.2 table: OWN-01 is marker_in: AGENTS set only (not
+# SHARED) — its anchor `PROJECT_IMPORTANT.md` does not exist in the CLAUDE
+# files, and markers are comment-only (no prose edits allowed). AGENTS-set
+# coverage matches the HOST-OC-01/HOST-OWN-01 rows that tag the same overlay.
+rules:
+  - id: CORE-01
+    title: One remembered command — ukit install
+    kind: critical
+    statement: >-
+      Human-facing UKit workflow collapses to one remembered command:
+      `ukit install`; after install, work in natural language inside the
+      supported harnesses.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'ukit install'
+  - id: CORE-02
+    title: Quality first, then speed, then token discipline
+    kind: supporting
+    statement: >-
+      Ordering of priorities for all work: quality first, then speed, then
+      token discipline.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: CLS-01
+    title: Trivial lane acts directly
+    kind: critical
+    statement: >-
+      Trivial tasks (typo, label, small rename, spacing, toggle flag, obvious
+      config change) act directly — no doc reads, planning, index, or agents.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'Act directly'
+  - id: CLS-02
+    title: Simple lane pulls smallest useful context
+    kind: critical
+    statement: >-
+      Simple tasks (1-2 files, clear scope, existing pattern) are handled
+      directly, pulling only the smallest useful context.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'smallest useful context'
+  - id: CLS-03
+    title: Non-trivial lane verifies harder
+    kind: supporting
+    statement: >-
+      Non-trivial/risky tasks read deeper, verify harder, and use the
+      index-first loop then skill activation then targeted verification.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: EXEC-01
+    title: Continue until write evidence or blocker
+    kind: critical
+    statement: >-
+      For explicit implement/apply/fix requests, continue until the actual edit
+      is made or a real blocker is found; never stop after read-only steps.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'actual edit is made'
+  - id: EXEC-02
+    title: No done-claims without Edit/Write evidence
+    kind: critical
+    statement: >-
+      Completion wording requires concrete Edit/Write evidence in the current
+      turn, plus verification when the scope is risky.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'concrete Edit/Write evidence'
+  - id: EXEC-03
+    title: Routed continuation is not a stopping point
+    kind: supporting
+    statement: >-
+      Routed states like pull-indexed-context or continuation-required are
+      internal continuation steps; finish the named milestone before widening.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: EXEC-04
+    title: Every stop names its reason
+    kind: critical
+    statement: >-
+      When a turn ends on a user-only action, open the reply with a
+      `WAITING ON YOU:` line and schedule a one-shot wakeup when available.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'WAITING ON YOU'
+  - id: LONG-01
+    title: LAND one thing, DEFER the rest, DELEGATE broad work
+    kind: supporting
+    statement: >-
+      Near token-cap, land one in-flight item end-to-end, defer the rest into
+      docs/STATUS.md or bounded handoff tasks, delegate broad work to subagents.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: LONG-02
+    title: Post-compact continuity from disk state
+    kind: supporting
+    statement: >-
+      After any compact or handoff, continue from persisted disk state without
+      rereading pre-compact context; delegate and keep replies short.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: IDX-01
+    title: Check index freshness before code context
+    kind: critical
+    statement: >-
+      For tasks needing code context, check the index is fresh and refresh it
+      when stale or missing.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'index is fresh'
+  - id: IDX-02
+    title: Open top 1-3 suspect files first
+    kind: critical
+    statement: >-
+      Open only the top 1-3 suspect files first, then widen if needed; use the
+      outline block to jump straight to the relevant region.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'top 1-3 suspect files'
+  - id: IDX-03
+    title: Outlines locate code; code to be changed must still be read
+    kind: critical
+    statement: >-
+      The outline locates code but does not describe behaviour; any code about
+      to be changed must still be read.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'must still be read'
+  - id: SKILL-01
+    title: Auto-activate the matching skill
+    kind: critical
+    statement: >-
+      On every non-trivial task, inspect installed project-local skills and
+      auto-activate the matching skill immediately; end users should not need
+      to know skill names.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'auto-activate the matching skill'
+  - id: SKILL-02
+    title: Smallest effective skill set
+    kind: supporting
+    statement: >-
+      Use the smallest effective set of skills, usually 1-2.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: SKILL-03
+    title: Upgrade skill choice on sharper evidence
+    kind: supporting
+    statement: >-
+      If evidence becomes more specific than the original prompt, upgrade the
+      active skill choice immediately.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HELP-01
+    title: Prefer internal helper commands for routing/context/verify
+    kind: supporting
+    statement: >-
+      Prefer the index helper scripts (route-task, resolve-context,
+      verify-context) for routing, related-file context, and verification.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HELP-02
+    title: Never ask contributors to run internal helpers
+    kind: critical
+    statement: >-
+      Do not ask normal contributors to run internal helper commands or
+      memorize maintainer commands; run them yourself or tell them to rerun
+      `ukit install`.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'Do not ask normal contributors'
+  - id: OWN-01
+    title: PROJECT_IMPORTANT.md is the canonical owner-instruction source
+    kind: critical
+    statement: >-
+      Read and follow the root PROJECT_IMPORTANT.md before project work; it is
+      the canonical project-owner instruction source.
+    marker_in: [templates/AGENTS.md, AGENTS.md]
+    anchor: 'PROJECT_IMPORTANT.md'
+  - id: SAFE-01
+    title: Preserve byte-level file details on edit
+    kind: critical
+    statement: >-
+      Preserve UTF-8 BOM/no-BOM and LF/CRLF for existing multilingual or
+      user-authored files.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'BOM/no-BOM'
+  - id: SAFE-02
+    title: Prefer unique current-file anchors for risky edits
+    kind: critical
+    statement: >-
+      For risky/shared/large edits, prefer unique current-file anchors over
+      line numbers or stale pasted blocks.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'unique current-file anchors'
+  - id: SAFE-03
+    title: Ask on missing or ambiguous stale specs
+    kind: supporting
+    statement: >-
+      Do not silently merge stale specs: if old_string is missing or ambiguous,
+      re-read current source and ask whether to apply, adapt, or skip.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: CTX-01
+    title: Deterministic segment bytes
+    kind: critical
+    statement: >-
+      Keep prompt-segment bytes deterministic so provider prompt prefixes can
+      be reused.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-01'
+  - id: CTX-02
+    title: Keep roles and order
+    kind: critical
+    statement: >-
+      Keep message roles and order stable across calls.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-02'
+  - id: CTX-03
+    title: Keep tool IDs and continuation state
+    kind: critical
+    statement: >-
+      Keep tool IDs and continuation state stable for prefix reuse.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-03'
+  - id: CTX-04
+    title: No clock/random IDs in static blocks
+    kind: critical
+    statement: >-
+      Static prompt blocks must not contain clock values or random IDs.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-04'
+  - id: CTX-05
+    title: Compaction starts a new epoch
+    kind: critical
+    statement: >-
+      Compaction starts a new cache epoch; do not expect prefix reuse across it.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-05'
+  - id: CTX-06
+    title: Never change data to match a cache
+    kind: critical
+    statement: >-
+      Never mutate data to make it match a cache entry.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-06'
+  - id: CTX-07
+    title: No unconfirmed cache fields
+    kind: critical
+    statement: >-
+      Do not rely on cache fields that have not been confirmed for the route in
+      use.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-07'
+  - id: CTX-08
+    title: Tool-result reuse needs valid freshness
+    kind: critical
+    statement: >-
+      Reuse of tool results requires valid freshness.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-08'
+  - id: CTX-09
+    title: Missing usage is unknown, not zero
+    kind: critical
+    statement: >-
+      Missing cache-usage reporting means unknown, not zero savings.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-09'
+  - id: CTX-10
+    title: Never cut a required check to reduce calls
+    kind: critical
+    statement: >-
+      Never skip a required verification or check just to reduce call count.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'CTX-10'
+  - id: HAND-01
+    title: Handoff Quality Gate is opt-in via docs/AI_HANDOFF
+    kind: supporting
+    statement: >-
+      The handoff quality gate activates only when a task goes through
+      docs/AI_HANDOFF; daily prompts keep the old flow.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HAND-02
+    title: RUN.md is the authoritative handoff run cursor
+    kind: critical
+    statement: >-
+      docs/AI_HANDOFF/RUN.md is the authoritative run cursor; only the
+      HANDOFF FULLSTACK COMPLETE/BLOCKED markers after Phase done/blocked end
+      a run.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'RUN.md'
+  - id: BUDGET-01
+    title: Context budget per task class
+    kind: critical
+    statement: >-
+      Context + verification budget rows: Trivial reads no docs, Simple reads
+      MEMORY only, Non-trivial adds PROJECT and CODE_MAP.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: '**Trivial**: no docs'
+  - id: BUDGET-02
+    title: STATUS.md only for open-ended or continuation prompts
+    kind: supporting
+    statement: >-
+      docs/STATUS.md is used for open-ended status/continue prompts or
+      meaningful continuation context; stale status is orientation only.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: BUDGET-03
+    title: WORKLOG recent entries only
+    kind: supporting
+    statement: >-
+      docs/WORKLOG.md is read for recent relevant entries only; archive oldest
+      entries when over limits.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: STATUS-01
+    title: STATUS.md is not source truth
+    kind: supporting
+    statement: >-
+      docs/STATUS.md captures compact current state; it is not source truth and
+      must not replace source/index-first investigation.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: SUBAG-01
+    title: Delegate only on meaningful context or parallel gains
+    kind: supporting
+    statement: >-
+      Keep direct execution as default for trivial/simple work; delegate only
+      when it shrinks context or enables useful parallel progress.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: SUBAG-02
+    title: Small-task maintainer is a sidecar lane
+    kind: supporting
+    statement: >-
+      The ukit-small-task-maintainer subagent handles safe/reversible UKit
+      chores as a sidecar lane and hands risky work back to the main model.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: AUTO-01
+    title: autonomy.level controls how much UKit acts without asking
+    kind: supporting
+    statement: >-
+      autonomy.level in .ukit/storage/config.json controls how much UKit acts
+      without asking first; end users should not need to change it.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: TIER-01
+    title: Tiers bind through agent definitions
+    kind: critical
+    statement: >-
+      A model tier takes effect only when work is handed to an agent whose own
+      definition binds that model; the main session model never changes
+      mid-turn.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'model:'
+  - id: TIER-02
+    title: Escalate one tier after repeated failure
+    kind: supporting
+    statement: >-
+      When the same file or symbol fails debugLoopThreshold times in one
+      session, route the next attempt one tier higher, capped at smart.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: HOST-OC-01
+    title: OpenCode must explicitly read the triggered SKILL.md
+    kind: critical
+    statement: >-
+      OpenCode reads AGENTS.md at session start only and does not auto-load
+      skills; the model must explicitly read the triggered SKILL.md.
+    marker_in: [templates/AGENTS.md, AGENTS.md]
+    anchor: 'read the triggered SKILL.md'
+  - id: HOST-OWN-01
+    title: Codex/OpenCode read the root owner instructions
+    kind: critical
+    statement: >-
+      When running in Codex or OpenCode, read and follow the root
+      PROJECT_IMPORTANT.md before doing project work.
+    marker_in: [templates/AGENTS.md, AGENTS.md]
+    anchor: 'read and follow the root'
+  - id: DURA-01
+    title: DuraOne skill activates only when installed
+    kind: supporting
+    statement: >-
+      The DuraOne skill is active only when the duraone pack is installed or
+      .claude/skills/duraone/SKILL.md exists; otherwise use generic standards.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+  - id: FALLBACK-01
+    title: Missing/corrupt runtime → rerun ukit install
+    kind: critical
+    statement: >-
+      If the workspace needs a refresh or runtime files are missing or corrupt,
+      tell maintainers to rerun `ukit install`.
+    marker_in: [templates/CLAUDE.md, templates/AGENTS.md, CLAUDE.md, AGENTS.md]
+    anchor: 'rerun `ukit install`'

package/manifests/platform.full.yaml

@@ -246,6 +246,21 @@ items:
     packs:
       - core
 
+  # Shipped internal-orchestration detail (tier tables, subagent policy, sidecar review,
+  # small-task maintainer, helper/runtime/budget/status detail, DuraOne). Extracted from
+  # templates/instructions/core.md in DOC-104; `overwrite_with_backup` so `ukit update`
+  # refreshes it alongside the root contracts that point at it.
+  - id: docs-ukit-internals
+    type: config
+    sourceTemplate: docs/UKIT_INTERNALS.md
+    targetPath: docs/UKIT_INTERNALS.md
+    requires: []
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: core-skill-delivery
     type: skill
     sourceTemplate: .claude/skills/delivery/SKILL.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.6.5",
+  "version": "2.6.7",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -55,7 +55,9 @@
     "index:query": "node ./scripts/index/query-index.mjs",
     "bug:triage": "node ./scripts/bug/triage.mjs",
     "skill:audit": "node ./scripts/skill/audit-skill.mjs",
-    "test:artifact": "vitest run tests/integration/packageArtifact.test.js",
+    "docs:render": "node scripts/docs/render-instructions.mjs --write",
+    "docs:render:check": "node scripts/docs/render-instructions.mjs --check",
+    "test:artifact": "vitest run tests/integration/packageArtifact.test.js tests/integration/artifactReferenceIntegrity.test.js",
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",
     "test": "vitest run",

package/scripts/docs/render-instructions.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// DOC-102 renderer CLI (SPEC §8.2).
+//   node scripts/docs/render-instructions.mjs --write   (default) regenerate all outputs
+//   node scripts/docs/render-instructions.mjs --check   print DRIFT <path> per mismatch, exit 1
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  renderInstructionsFromDisk,
+  checkRenderedInstructions,
+} from '../../src/render/instructionRenderer.js';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+const USAGE = 'usage: render-instructions.mjs [--write|--check]';
+
+const args = process.argv.slice(2);
+const unknown = args.filter((a) => a !== '--write' && a !== '--check');
+if (unknown.length > 0) {
+  console.error(`${USAGE}\nunknown flag: ${unknown[0]}`);
+  process.exit(2);
+}
+
+const mode = args.includes('--check') ? 'check' : 'write';
+
+try {
+  if (mode === 'check') {
+    const drift = await checkRenderedInstructions({ repoRoot });
+    for (const target of drift) {
+      console.log(`DRIFT ${target}`);
+    }
+    process.exit(drift.length > 0 ? 1 : 0);
+  }
+
+  const rendered = await renderInstructionsFromDisk({ repoRoot, write: true });
+  for (const [target, content] of rendered) {
+    console.log(`WROTE ${target} (${content.split('\n').length - 1} lines)`);
+  }
+} catch (err) {
+  console.error(err && err.message ? err.message : err);
+  process.exit(1);
+}

package/src/core/projectImportant.js

@@ -2,7 +2,7 @@
  * projectImportant.js (TASK-037)
  *
  * Source-side inspector + deterministic envelope renderer for
- * PROJECT_IMPORTANT.md per docs/PROJECT_IMPORTANT_SPEC.md §3, §4, §5.2, §6,
+ * PROJECT_IMPORTANT.md per docs/archive/specs/PROJECT_IMPORTANT_SPEC.md §3, §4, §5.2, §6,
  * §12.1.
  *
  * Guarantees:

package/src/core/uninstall.js

@@ -16,7 +16,7 @@ import { PROJECT_IMPORTANT_FILENAME } from './projectImportant.js';
 // tracked/followed. Before any destructive uninstall step a regular source gets a
 // raw-byte backup beside it at the project root (never under .claude/.ukit/.codex/
 // .omp — those may be deleted): `<name>.ukit-backup`, then `.ukit-backup.1`, `.2`, …
-// via bounded exclusive-create collision walk. See docs/PROJECT_IMPORTANT_SPEC.md §15.
+// via bounded exclusive-create collision walk. See docs/archive/specs/PROJECT_IMPORTANT_SPEC.md §15.
 const IMPORTANT_BACKUP_SUFFIX = '.ukit-backup';
 const IMPORTANT_BACKUP_COLLISION_LIMIT = 100;