@ngockhoale/ukit 3.4.1 → 3.4.3

package/template_project/.claude/skills/pptx/scripts/thumbnail.py

@@ -53,6 +53,7 @@ from pptx import Presentation
 # Constants
 THUMBNAIL_WIDTH = 300  # Fixed thumbnail width in pixels
 CONVERSION_DPI = 100  # DPI for PDF to image conversion
+MIN_COLS = 3  # Minimum number of columns
 MAX_COLS = 6  # Maximum number of columns
 DEFAULT_COLS = 5  # Default number of columns
 JPEG_QUALITY = 95  # JPEG compression quality
@@ -89,7 +90,11 @@ def main():
 
     args = parser.parse_args()
 
-    # Validate columns
+    # Validate columns — C90-13: reject below-range values as a clean option
+    # error at argv time so the range(…, cols*(cols+1)) ValueError path in
+    # create_grids() is unreachable.
+    if args.cols < MIN_COLS:
+        parser.error(f"--cols must be between {MIN_COLS} and {MAX_COLS} (got {args.cols})")
     cols = min(args.cols, MAX_COLS)
     if args.cols > MAX_COLS:
         print(f"Warning: Columns limited to {MAX_COLS} (requested {args.cols})")

package/template_project/.claude/ukit/index/lib/index-core.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { withFileLock } from '../../runtime/token-utils.mjs';
+import { withAsyncLock } from '../../runtime/async-lock.mjs';
 
 // One wall-clock ceiling for the WHOLE discovery phase: both `git ls-files`
 // enumerations AND the non-git fallback walk share this single budget. Every
@@ -28,6 +29,23 @@ export class IndexDiscoveryTimeoutError extends Error {
   }
 }
 
+/**
+ * Fail-closed lock timeout (C92-B-01): a contended index-build lock that stays
+ * held past INDEX_BUILD_LOCK_WAIT_MS means another builder is still publishing
+ * (or a dead holder's lock could not be reclaimed). Building unlocked would
+ * interleave tmp+rename writes into a torn artifact set, so the caller gets a
+ * typed failure instead of a race.
+ */
+export class IndexBuildLockTimeoutError extends Error {
+  constructor({ waitedMs, lockPath }) {
+    super(`Index build lock ${lockPath} was still held after ${waitedMs}ms; refusing to publish unlocked.`);
+    this.name = 'IndexBuildLockTimeoutError';
+    this.code = 'INDEX_BUILD_LOCK_TIMEOUT';
+    this.waitedMs = waitedMs;
+    this.lockPath = lockPath;
+  }
+}
+
 // Upper bound on in-flight filesystem stat calls during discovery: git
 // candidate stats and the non-git fallback walk share this fixed pool.
 // The previous `Promise.all(candidates.map(stat))` produced one unbounded
@@ -211,7 +229,56 @@ const VIETNAMESE_TOKEN_ALIASES = new Map([
 // snapshots from a different version instead of trusting unknown fields.
 export const DISCOVERY_SNAPSHOT_VERSION = 1;
 
+export const INDEX_BUILD_LOCK_NAME = 'index-build';
+
+/**
+ * How long a builder waits for a build already in flight before failing
+ * closed. Must comfortably cover a worst-case build of a large repo — the
+ * wait replaces what used to be a silent interleaved publish, so an overly
+ * short budget would trade torn artifacts for spurious timeouts.
+ */
+export const INDEX_BUILD_LOCK_WAIT_MS = 60_000;
+
+/**
+ * C92-B-01: every buildCodeIndex entry point publishes under the shared
+ * `index-build` lock (the same path ensureIndexFresh locks). Per-artifact
+ * tmp+rename was never the problem — two builders with ASYMMETRIC write sets
+ * interleaved their renames, so a reader could consume meta.json from build A
+ * and files.json from build B. The lock lives inside the builder because the
+ * callers (refresh-index.mjs, build-index.mjs, git hooks) were all unlocked;
+ * ensureIndexFresh drives buildCodeIndexInner directly while it already
+ * holds the lock, so its outer hold cannot self-deadlock.
+ * Fail-closed: a lock that cannot be acquired inside the wait budget throws
+ * IndexBuildLockTimeoutError instead of publishing unlocked.
+ */
 export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = null, discoverySnapshot = null, signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
+  // A signal aborted before we even look at the lock must classify exactly
+  // like a discovery cancellation: callers rely on the typed
+  // IndexDiscoveryTimeoutError(aborted) and on no artifact directory ever
+  // appearing for a build that never started.
+  if (signal?.aborted) {
+    throw new IndexDiscoveryTimeoutError({ deadlineMs, phase: 'build', elapsedMs: 0, aborted: true });
+  }
+  const absoluteRoot = path.resolve(rootDir);
+  const lockBase = path.join(getIndexDir(absoluteRoot), INDEX_BUILD_LOCK_NAME);
+  const outcome = await withAsyncLock(
+    lockBase,
+    { signal, deadlineMs: INDEX_BUILD_LOCK_WAIT_MS },
+    () => buildCodeIndexInner({ rootDir: absoluteRoot, changedFiles, discoverySnapshot, signal, deadlineMs }),
+  );
+  if (outcome?.ok === true) {
+    return outcome.value;
+  }
+  if (outcome?.reason === 'aborted') {
+    throw new IndexCancelledError({ phase: 'build-lock' });
+  }
+  throw new IndexBuildLockTimeoutError({
+    waitedMs: outcome?.waitedMs ?? INDEX_BUILD_LOCK_WAIT_MS,
+    lockPath: `${lockBase}.lock`,
+  });
+}
+
+async function buildCodeIndexInner({ rootDir = process.cwd(), changedFiles = null, discoverySnapshot = null, signal = null, deadlineMs = DEFAULT_DISCOVERY_DEADLINE_MS } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const indexDir = getIndexDir(absoluteRoot);
 
@@ -222,11 +289,22 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
   // wins over the optimization, and incremental output must stay equivalent to
   // a clean full rebuild.
   const changedHintPlan = normalizeChangedFileHints(changedFiles);
-  if (changedHintPlan) {
-    const incremental = changedHintPlan.ok
-      ? await tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths: changedHintPlan.paths, signal })
-      : null;
-    if (incremental) {
+  let incrementalFallbackReason = changedHintPlan && !changedHintPlan.ok
+    ? 'unsafe-changed-file-hints'
+    : null;
+  if (changedHintPlan?.ok) {
+    const incremental = await tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths: changedHintPlan.paths, signal });
+    if (incremental?.rejected) {
+      // C92-B-02: a rejected merge is no longer silent. The reason lands on the
+      // build summary, and corruption-class rejections are also warned so the
+      // CLI callers that ignore the summary still surface it.
+      incrementalFallbackReason = incremental.detail
+        ? `${incremental.rejected} (${incremental.detail})`
+        : incremental.rejected;
+      if (incremental.detail) {
+        console.warn(`[index] incremental refresh rejected: meta.artifactItemCounts ${incremental.rejected} (${incremental.detail}) — falling back to full rebuild`);
+      }
+    } else if (incremental) {
       return incremental;
     }
   }
@@ -538,6 +616,11 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
     reusedAnalogs: canReuseAnalogs,
     preservedRuntimeCaches,
     mode: 'full',
+    // C92-B-02: when changed-file hints were offered but the incremental merge
+    // refused them, this names the rejection (e.g.
+    // 'artifact-item-counts-mismatch (files.json: recorded 4, actual 5)') so
+    // the fallback is diagnosable instead of silently returning 'full' forever.
+    incrementalFallbackReason,
     parsedFiles: filesToParse.slice(),
     removedFiles: [],
   };
@@ -658,19 +741,10 @@ function isValidCoveredItems(items, fileRecords, keyFn) {
   });
 }
 
-// Item shapes alone cannot detect a schema-current artifact whose `items` array
-// lost entries: every surviving entry still looks valid, yet the merge would
-// reuse it verbatim and publish an artifact missing the unchanged files. Each
-// required artifact therefore records its item count in meta, and the count must
-// match the array actually loaded — a mismatch (or a pre-count meta) falls back
-// to full discovery.
-function artifactItemCountsMatch(metaArtifact, counts) {
-  const recorded = metaArtifact?.artifactItemCounts;
-  if (!recorded || typeof recorded !== 'object' || Array.isArray(recorded)) {
-    return false;
-  }
-  return Object.entries(counts).every(([name, count]) => Number(recorded[name]) === count);
-}
+// C92-B-02: every rejection from tryIncrementalIndexUpdate carries a reason
+// (and, for integrity failures, a detail string) instead of a bare null, so a
+// torn or corrupted artifact set lands on the build summary as
+// incrementalFallbackReason rather than silently forcing 'full' forever.
 
 // Stat every hinted path and classify it as an upsert, a removal, or — for
 // extensions discovery never indexes — a no-op. Returns null when a hint
@@ -802,7 +876,7 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     [INDEX_ARTIFACTS.calls]: callsArtifact?.items?.length ?? -1,
     [INDEX_ARTIFACTS.relations]: relationsArtifact?.items?.length ?? -1,
   };
-  const previousArtifactsUsable = [
+  const previousArtifactsSchemaAndShapeUsable = [
     metaArtifact,
     filesArtifact,
     symbolsArtifact,
@@ -817,16 +891,29 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     && isValidCoveredItems(importsArtifact.items, filesArtifact.items, (item) => item.from)
     && isValidCoveredItems(callsArtifact.items, filesArtifact.items, (item) => item.filePath)
     && isValidCoveredItems(relationsArtifact.items, filesArtifact.items, (item) => item.filePath)
-    && Array.isArray(relationsArtifact?.sourceSnapshot?.styleFiles)
-    && artifactItemCountsMatch(metaArtifact, artifactItemCounts);
-  if (!previousArtifactsUsable) {
-    return null;
+    && Array.isArray(relationsArtifact?.sourceSnapshot?.styleFiles);
+  if (!previousArtifactsSchemaAndShapeUsable) {
+    return { rejected: 'previous-artifacts-unusable' };
+  }
+  // C92-B-02: the count gate used to fold silently into the same null as every
+  // other unusability, so a torn publish permanently disabled incremental
+  // refresh with no diagnostic. Name the artifacts that disagree with meta.
+  const recordedCounts = metaArtifact?.artifactItemCounts;
+  const countsRecorded = recordedCounts && typeof recordedCounts === 'object' && !Array.isArray(recordedCounts);
+  const countMismatchDetail = !countsRecorded
+    ? 'artifactItemCounts missing from meta.json'
+    : Object.entries(artifactItemCounts)
+        .filter(([name, actual]) => Number(recordedCounts[name]) !== actual)
+        .map(([name, actual]) => `${name}: recorded ${recordedCounts[name] ?? 'missing'}, actual ${actual}`)
+        .join(', ');
+  if (!countsRecorded || countMismatchDetail) {
+    return { rejected: 'artifact-item-counts-mismatch', detail: countMismatchDetail };
   }
 
   const previousRecordsByPath = new Map(filesArtifact.items.map((item) => [item.filePath, item]));
   const hintUpdates = await resolveChangedHintUpdates(absoluteRoot, changedPaths, previousRecordsByPath);
   if (!hintUpdates) {
-    return null;
+    return { rejected: 'changed-hints-unresolvable' };
   }
 
   // Merge the hint outcome into one sorted record set — the same shape and
@@ -895,7 +982,7 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
     }
   }, signal, 'stat-style'));
   if (styleEntries.some((entry) => entry?.statError)) {
-    return null;
+    return { rejected: 'style-stat-unresolvable' };
   }
   const styleFilePaths = styleEntries.filter(Boolean).map((entry) => normalizeRelative(absoluteRoot, entry.absolutePath));
 
@@ -1209,7 +1296,7 @@ export async function queryCodeIndex({ rootDir = process.cwd(), query, limit = 5
     const directScores = new Map();
     for (const file of safeItems(files)) {
       const filePath = file.filePath;
-      if (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles) continue;
+      if (typeof filePath !== 'string' || !filePath || (isLikelyTestFilePath(filePath) && !includeLikelyTestFiles)) continue;
       const searchDescriptor = searchDescriptorsByFile.get(filePath) ?? createFileSearchDescriptor({ filePath, symbols: [] });
       const { score, reasons } = scoreDirectFileMatch({
         queryDescriptor,
@@ -1378,8 +1465,24 @@ function ensureArtifact(artifact) {
   };
 }
 
+// C92-B-03 consumer symmetry: an artifact written under a different
+// INDEX_SCHEMA_VERSION (older OR newer — a package downgrade leaves newer
+// artifacts on disk) is treated as absent, exactly like getFileOutline's
+// schema gate on symbols.json. Without it, queryCodeIndex scores the
+// mismatched set and looks healthy while outline: silently disappears.
+function safeSchemaArtifact(artifact) {
+  const normalized = ensureArtifact(artifact);
+  return normalized.schemaVersion === INDEX_SCHEMA_VERSION ? normalized : { items: [] };
+}
+
+// The cache keys matched against this escaped value are produced by
+// JSON.stringify, which escapes control characters (\n, \b, \u00XX, lone
+// surrogates) on top of backslash/quote. Hand-escaping only \\ and \" means a
+// rootDir containing control characters never matches its own cache keys, so
+// clearIndexArtifactCache leaves stale results behind. Reuse JSON.stringify
+// itself and strip the surrounding quotes to stay in lockstep.
 function escapeJsonString(value) {
-  return String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+  return JSON.stringify(String(value)).slice(1, -1);
 }
 
 // ── Context Resolver ──
@@ -2939,8 +3042,10 @@ async function loadQuerySearchBundle(rootDir) {
         readArtifact(absoluteRoot, INDEX_ARTIFACTS.symbols),
       ])
         .then(([files, symbols]) => {
-          const safeFiles = ensureArtifact(files);
-          const safeSymbols = ensureArtifact(symbols);
+          // C92-B-03: same schema contract getFileOutline applies — a mismatched
+          // artifact reads as empty instead of feeding ranking.
+          const safeFiles = safeSchemaArtifact(files);
+          const safeSymbols = safeSchemaArtifact(symbols);
           const symbolMap = groupBy(safeItems(safeSymbols), (item) => item.filePath);
           return {
             files: safeFiles,
@@ -2972,11 +3077,11 @@ async function loadQuerySupportBundle(rootDir) {
           readArtifact(absoluteRoot, INDEX_ARTIFACTS.archetypes),
         ]))
         .then(async ([files, imports, testsMap, hotspots, archetypes]) => {
-          const safeFiles = ensureArtifact(files);
-          const safeImports = ensureArtifact(imports);
-          const safeTestsMap = ensureArtifact(testsMap);
-          const safeHotspots = ensureArtifact(hotspots);
-          const safeArchetypes = ensureArtifact(archetypes);
+          const safeFiles = safeSchemaArtifact(files);
+          const safeImports = safeSchemaArtifact(imports);
+          const safeTestsMap = safeSchemaArtifact(testsMap);
+          const safeHotspots = safeSchemaArtifact(hotspots);
+          const safeArchetypes = safeSchemaArtifact(archetypes);
           const indexedFileSet = new Set(safeItems(safeFiles).map((item) => item.filePath));
           const importAliasContext = importsNeedAliasContext(safeItems(safeImports))
             ? await loadImportAliasContext({ rootDir: absoluteRoot })
@@ -3399,7 +3504,7 @@ function buildResolvedImportGraphs(rootDir, imports, indexedFileSet, importAlias
   const importersByTarget = new Map();
 
   for (const edge of imports) {
-    if (!edge?.from || !edge?.to) continue;
+    if (typeof edge?.from !== 'string' || typeof edge?.to !== 'string' || !edge.from || !edge.to) continue;
 
     const target = resolveImportSpecifier({
       rootDir,
@@ -3525,9 +3630,13 @@ function resolveImportSpecifier({
   indexedFileSet,
   aliasContext,
 }) {
-  if (!specifier?.trim()) return null;
+  if (typeof specifier !== 'string' || !specifier.trim()) return null;
 
   if (specifier.startsWith('.')) {
+    // A relative specifier cannot be resolved without the importing file, so a
+    // malformed (non-string) edge.from must skip the edge instead of throwing
+    // inside path.posix.dirname.
+    if (typeof fromFilePath !== 'string') return null;
     const fromDir = path.posix.dirname(fromFilePath);
     const base = path.posix.normalize(path.posix.join(fromDir, specifier));
     return resolveCandidateBase(base, indexedFileSet);
@@ -4495,7 +4604,12 @@ async function evaluateIndexStaleness({ rootDir, maxAgeMs, now, generatedAtMs, e
     || Number.isNaN(maxAgeMs)
     || maxAgeMs < 0
     || (now - effectiveGeneratedAtMs) >= maxAgeMs
-    || !metaArtifact?.sourceFingerprint;
+    || !metaArtifact?.sourceFingerprint
+    // C92-B-03: an artifact set written under a different INDEX_SCHEMA_VERSION
+    // — older OR newer — is not fresh. `!==` covers the package-downgrade
+    // direction too; serving the old schema made `outline:` silently vanish
+    // while ranking kept answering.
+    || metaArtifact?.schemaVersion !== INDEX_SCHEMA_VERSION;
 
   // Legacy boolean callers (query-index, triage, verify-context) stop here and
   // let buildCodeIndex do its own discovery when a rebuild is needed.
@@ -4578,7 +4692,10 @@ export async function ensureIndexFresh({
     return lastRefreshMs;
   }
 
-  const lockPath = `${getIndexDir(absoluteRoot)}/index-build.lock`;
+  // Shares the builder's lock: buildCodeIndex acquires `<base>.lock` for
+  // base `index-build`, so this must name the same base — and drives the
+  // unwrapped inner builder since this critical section already holds it.
+  const lockPath = `${getIndexDir(absoluteRoot)}/${INDEX_BUILD_LOCK_NAME}`;
   const result = await withFileLock(lockPath, async () => {
     const lockedRefreshMs = await getIndexArtifactGeneratedAt({ rootDir: absoluteRoot });
     const lockedStale = lockedRefreshMs === null
@@ -4592,7 +4709,7 @@ export async function ensureIndexFresh({
     if (!lockedStale) {
       return { refreshed: false, generatedAtMs: lockedRefreshMs };
     }
-    const summary = await buildCodeIndex({ rootDir: absoluteRoot, ...discoveryOptions, discoverySnapshot });
+    const summary = await buildCodeIndexInner({ rootDir: absoluteRoot, ...discoveryOptions, discoverySnapshot });
     return { refreshed: true, summary, generatedAtMs: summary?.generatedAtMs ?? Date.now() };
   });
 

package/template_project/.claude/ukit/index/playbook-registry.mjs

@@ -17,7 +17,6 @@
 // Parity is locked by tests/consistency/registryParity.test.js.
 
 import fs from 'node:fs/promises';
-import fsSync from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -77,12 +76,14 @@ const AUTONOMOUS_TRIGGER_RE = /\b(finish (?:this|the) backlog|bounded (?:long )?
 const RELEASE_TRIGGER_RE = /\b(publish|ship it|release|bump (?:the )?version|deploy|cut a release|tag (?:the )?release)\b/i;
 const HANDOFF_CYCLE_TRIGGER_RE = /\b(handoff|multi[- ]?task cycle|task pipeline|execute the plan|worktree)\b/i;
 
-// session-pickup discriminator needs the resumable-record check.
-function hasResumableRecord(projectRoot) {
+// session-pickup discriminator needs the resumable-record check. ASYNC scan
+// (W3-PB2): the resolve path runs inside hook processes where a sync
+// readdirSync parks the event loop and can starve the hook self-deadline.
+async function hasResumableRecord(projectRoot) {
   if (!projectRoot) return false;
   try {
     const runsDir = path.join(projectRoot, '.ukit', 'storage', 'runs');
-    const entries = fsSync.readdirSync(runsDir, { withFileTypes: true });
+    const entries = await fs.readdir(runsDir, { withFileTypes: true });
     return entries.some((entry) => entry.isFile() && entry.name.endsWith('.json'));
   } catch {
     return false;
@@ -288,7 +289,7 @@ function matchFirst(text, regexes) {
   return -1;
 }
 
-function buildRouteSignals({
+async function buildRouteSignals({
   signalText,
   executionMode,
   escalationTriggers,
@@ -357,7 +358,7 @@ function buildRouteSignals({
     testHarness: TEST_HARNESS_RE.test(signalText),
     measurable: /\d/.test(signalText) || MEASURABLE_RE.test(signalText),
     dataMove: DATA_MOVE_RE.test(signalText),
-    hasResumableRecord: hasResumableRecord(projectRoot),
+    hasResumableRecord: await hasResumableRecord(projectRoot),
     // BL-026 review fix: ask to convert/author a skill — beats defect verbs in
     // the same sentence ("make this repeated fix flow a skill").
     skillAsk: SKILL_ASK_RE.test(signalText),
@@ -375,14 +376,17 @@ const MEASURABLE_RE = /\b(latency|baseline|benchmark|profile|cpu|memory|heap|tak
 // REQUIRED — a registry file without them is malformed (FR-007), where the
 // workflow-policy loader tolerates filename-stem ids.
 function parsePlaybookMeta(raw, filePath) {
-  if (!raw.startsWith('---\n')) {
+  // W3-PB1: normalize CRLF before fence matching — a Windows-authored
+  // frontmatter block is still frontmatter, not malformed.
+  const text = String(raw).replace(/\r\n/g, '\n');
+  if (!text.startsWith('---\n')) {
     return null;
   }
-  const fenceIndex = raw.indexOf('\n---', 3);
+  const fenceIndex = text.indexOf('\n---', 3);
   if (fenceIndex === -1) {
     return null; // unterminated frontmatter
   }
-  const metaText = raw.slice(4, fenceIndex);
+  const metaText = text.slice(4, fenceIndex);
   const meta = {};
   for (const line of metaText.split('\n')) {
     const match = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
@@ -407,7 +411,7 @@ function parsePlaybookMeta(raw, filePath) {
   if (lanes.length === 0) {
     return null;
   }
-  const body = raw.slice(fenceIndex + 4).replace(/^\n/, '');
+  const body = text.slice(fenceIndex + 4).replace(/^\n/, '');
   if (body.trim() === '') {
     return null; // empty body → not a playbook
   }
@@ -552,7 +556,7 @@ export async function resolvePlaybookId({
       ...(Array.isArray(escalationTriggers) ? escalationTriggers : []),
       ...deriveEscalationTriggers(floor),
     ])];
-    const signals = buildRouteSignals({
+    const signals = await buildRouteSignals({
       signalText,
       executionMode,
       escalationTriggers: mergedTriggers,

package/template_project/.claude/ukit/index/post-edit-verify.mjs

@@ -74,15 +74,27 @@ async function readJsonl(filePath) {
     .filter(Boolean);
 }
 
+// C92-D-03: a pre-edit manifest row is never rewritten once a post-edit pass
+// consumes it, so "the last row with a rollbackPath and no afterHash" keeps
+// matching every later edit of the same path — the delta gate then diffs
+// against a two-generations-old blob and its BLOCKED remediation points at a
+// restore target that discards landed work. Manifest ORDER is the consumption
+// marker instead: scan newest → oldest and decide from the FIRST row seen for
+// this path. If that row is a post-edit audit row (or carries no usable
+// rollbackPath), the backup for it was already consumed — there is no baseline
+// for this edit, and no older row may be resurrected.
 async function findLatestBackup(projectRoot, relativePath) {
   const backupsRoot = path.join(projectRoot, '.ukit', 'storage', 'backups');
   for (const manifestPath of await listManifestPaths(backupsRoot)) {
     const entries = await readJsonl(manifestPath);
     for (let index = entries.length - 1; index >= 0; index -= 1) {
       const entry = entries[index];
-      if (entry.file === relativePath && entry.rollbackPath && !entry.afterHash) {
-        return { entry, manifestPath };
+      if (entry.file !== relativePath) continue;
+      const isPostEditRow = entry.event === 'post-edit' || Boolean(entry.afterHash);
+      if (isPostEditRow || !entry.rollbackPath) {
+        return { consumed: true, manifestPath };
       }
+      return { entry, manifestPath };
     }
   }
   return null;
@@ -171,11 +183,20 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
   if (!(await pathExists(resolved.absolute))) return { status: 'skipped', reason: 'missing-after', file: resolved.relative };
 
   const latest = await findLatestBackup(projectRoot, resolved.relative);
-  if (!latest) return { status: 'skipped', reason: 'no-backup', file: resolved.relative };
+  // Consumed (or absent) baseline → there is nothing truthful to diff against.
+  // Skipping is deliberate: a fabricated delta is strictly worse than no gate.
+  if (!latest || latest.consumed) return { status: 'skipped', reason: 'no-backup', file: resolved.relative };
 
   const rollbackPath = path.resolve(projectRoot, latest.entry.rollbackPath);
-  const beforeBuffer = await fs.readFile(rollbackPath);
+  const beforeBuffer = await fs.readFile(rollbackPath).catch(() => null);
+  if (!beforeBuffer) return { status: 'skipped', reason: 'no-backup', file: resolved.relative };
   const beforeProfile = analyzeTextBuffer(beforeBuffer);
+  // Self-validating baseline: when the producer recorded beforeHash, the blob
+  // must hash to exactly that value. A mismatch means the blob is stale or
+  // corrupt — treat it as missing rather than diff against wrong content.
+  if (latest.entry.beforeHash && beforeProfile.sha256 !== latest.entry.beforeHash) {
+    return { status: 'skipped', reason: 'no-backup', file: resolved.relative };
+  }
   const afterProfile = await analyzeTextFile(resolved.absolute);
   const risk = classifySafePatchRisk(resolved.relative, afterProfile, config);
   const delta = beforeProfile.utf8Valid && afterProfile.utf8Valid

package/template_project/.claude/ukit/index/pre-edit-backup.mjs

@@ -64,6 +64,10 @@ async function backupIfNeeded({ projectRoot, payload }) {
   await fs.copyFile(resolved.absolute, rollbackPath);
   const manifestPath = path.join(backupRoot, 'manifest.jsonl');
   const entry = {
+    // C92-D-03: explicit row typing — post-edit-verify consumes a baseline by
+    // manifest order, so readers must be able to tell a pre-edit backup row
+    // from a post-edit audit row without inferring it from field presence.
+    event: 'pre-edit',
     file: resolved.relative,
     beforeHash: profile.sha256,
     profile: publicTextProfile(profile),

package/template_project/.claude/ukit/index/provision-worktree.mjs

@@ -123,12 +123,16 @@ function excludeNodeModulesFromGit(root) {
   }
 }
 
-// The `.claude` copy must never clobber a git-TRACKED file (today exactly
-// `.claude/commands/ukit/handoff-fullstack.md` — owned by TASK-005). A fresh
-// worktree already has that file checked out by `git worktree add`; if the
-// gitignored dev mirror in mainRoot has locally drifted from the committed
-// copy, an unconditional recursive copy would silently overwrite the
-// worktree's tracked file with main's unreviewed local state.
+// The `.claude` copy must never clobber a file that is git-TRACKED **in the
+// worktree being populated** (today exactly `.claude/commands/ukit/
+// handoff-fullstack.md` — owned by TASK-005). A fresh worktree already has
+// that file checked out by `git worktree add`; if the gitignored dev mirror
+// in mainRoot has locally drifted from the committed copy, an unconditional
+// recursive copy would silently overwrite the worktree's tracked file with
+// main's unreviewed local state. W3-02: the probe must run against the
+// DESTINATION worktree's index (`git -C <wtPath> ls-files`), not the main
+// tree's — a file tracked only on the worktree's branch is invisible to the
+// main index and would be clobbered.
 function trackedClaudeFiles(root) {
   try {
     const res = gitProbe(['ls-files', '--', '.claude'], root);
@@ -183,10 +187,11 @@ if (!fs.existsSync(srcClaude)) {
 } else {
   // Always (re)copy: a fresh worktree may already carry a partial, git-tracked
   // .claude/ (e.g. commands), which must not make us skip the hooks/scripts.
-  // Never overwrite a git-tracked file under .claude/ (e.g.
-  // handoff-fullstack.md) — leave whatever `git worktree add` already
-  // checked out for it alone.
-  const trackedInClaude = trackedClaudeFiles(mainRoot);
+  // Never overwrite a file tracked in the WORKTREE's index (e.g.
+  // handoff-fullstack.md, or a file committed only on the worktree's branch)
+  // — leave whatever `git worktree add` already checked out for it alone.
+  // W3-02: probe wtPath, not mainRoot — each linked worktree has its own index.
+  const trackedInClaude = trackedClaudeFiles(wtPath);
   fs.cpSync(srcClaude, dstClaude, {
     recursive: true,
     filter: (src) => {

package/template_project/.claude/ukit/index/query-index.mjs

@@ -24,7 +24,7 @@ const rootDir = getRootDir(args);
 const limitArg = readFlagValue(args, '--limit');
 const limit = Number.parseInt(limitArg ?? '5', 10);
 const showOutline = !args.includes('--no-outline');
-const query = collectPositionalArgs(args, ['--root', '--limit']);
+const query = collectPositionalArgs(args, ['--no-outline']);
 
 if (!query) {
   console.error('Usage: node .claude/ukit/index/query-index.mjs "<error|symbol|path>"');
@@ -167,23 +167,30 @@ function getRootDir(argv) {
 
 function readFlagValue(argv, flag) {
   const exact = argv.indexOf(flag);
-  if (exact >= 0 && argv[exact + 1]) return argv[exact + 1];
+  if (exact >= 0 && argv[exact + 1] && !argv[exact + 1].startsWith('--')) {
+    return argv[exact + 1];
+  }
   const withEquals = argv.find((item) => item.startsWith(`${flag}=`));
   return withEquals ? withEquals.slice(flag.length + 1) : null;
 }
 
-function collectPositionalArgs(argv, flagsWithValues = []) {
+function collectPositionalArgs(argv, booleanFlags = []) {
   return argv
-    .filter((arg, index) => !isFlagOrValue(argv, index, flagsWithValues))
+    .filter((arg, index) => !isFlagOrValue(argv, index, booleanFlags))
     .join(' ')
     .trim();
 }
 
-function isFlagOrValue(argv, index, flagsWithValues = []) {
+function isFlagOrValue(argv, index, booleanFlags = []) {
   const arg = argv[index];
   if (!arg.startsWith('--')) {
     const prev = argv[index - 1];
-    return Boolean(prev && flagsWithValues.includes(prev));
+    // A bare token following a `--flag` is that flag's value — the previous
+    // parser let unknown flags (e.g. `--foo bar`) leak `bar` into the query.
+    // Boolean flags (`--no-outline`) and `--flag=value` forms consume nothing.
+    if (!prev || !prev.startsWith('--')) return false;
+    if (booleanFlags.includes(prev) || prev.includes('=')) return false;
+    return true;
   }
   return true;
 }