@dzhechkov/harness-core 0.5.4 → 0.6.1

package/src/index.ts

@@ -221,6 +221,7 @@ export {
   resumeMode,
   decideCheckpointResume,
   serializeCheckpoint,
+  decideCheckpointWrite,
   parseCheckpointRead,
   checkpointReadCmd,
   checkpointAppendCmd,
@@ -236,7 +237,33 @@ export {
   codeCheckpointPersistAllowed,
   codeStageResultShapeValid,
 } from './feature-adr-checkpoints.js';
-export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairTruncation } from './feature-adr-checkpoints.js';
+export type { CheckpointStage, CheckpointEntry, ResumeMode, ResumeDecision, ParsedCheckpointRead, TrainingPairFamily, TrainingPair, TrainingPairEvaluation, TrainingPairProvenance, TrainingPairTruncation,
+  CheckpointWriteVerdict,
+} from './feature-adr-checkpoints.js';
+
+// amendment-traceability (ADR-001/002/003): the deterministic half of the Step-8 amendment gate.
+export {
+  MIN_MATCHABLE_ID_LENGTH,
+  AMENDMENT_VACUITY_NOTE,
+  normalizeTestId,
+  amendmentSection,
+  planSaysNoAmendments,
+  parseAmendments,
+  resolveAmendments,
+  decideAmendmentOutcome,
+  amendmentVerdictLine,
+  amendmentsMissingFromPlan,
+  amendmentSubject,
+  extractTestTitles,
+} from './amendment-trace.js';
+export {
+  RECORD_MAX_LINE_CHARS,
+  decideRecordWrite,
+  decideReadBack,
+  recordVerdictLine,
+} from './run-records.js';
+export type { RecordKind, RecordVerdict, RecordDecision } from './run-records.js';
+export type { AmendmentRow, AmendmentVerdict, AmendmentResolution, AmendmentOutcome, AmendmentDecision, PlanCoverageGap } from './amendment-trace.js';
 export {
   DOMAIN_LIFT_EXACT,
   DOMAIN_LIFT_RELATED,
@@ -516,6 +543,12 @@ export {
   resolveCoderSpec,
   coderIsCodex,
   resolveQeSpec,
+  crossFamilyQe,
+  decideModeBScope,
+  partitionReviewFindings,
+  parseHashProbe,
+  changedFromHashes,
+  changeSetProbeCmd,
   routingRequested,
   mergeOpts,
   DEFAULT_MODELS,
@@ -558,15 +591,48 @@ export {
   PLAN_GATE_SCRIPT,
   planCompletenessGateCmd,
   parsePlanGateVerdict,
+  // p16-non-js-portability: the gate-script search chain's operator note (ADR-002/AM-7) and the
+  // dzBin absolutization (ADR-003). Named for the same reason as the three above.
+  refusalNoteFor,
+  normalizeDzBin,
   // qe-bridge-claude: the bridge's path/slug hygiene reuses these rather than minting a second
   // definition of "safe" (ADR-001 D5-A).
   isSafeSlug,
   hasUnsafePathChars,
   hasDotDotSegment,
+  // qe-scoped-review: the two scoped Codex QE dispatch modes + the LOCKED decline taxonomy. NAMED
+  // one by one on purpose — an omission here silently drops the export from the published package
+  // while the suite stays green (the ADR-002 Confirmation-1 lesson, re-learnt on 2026-08-21 when a
+  // fixed export shipped behind two stale workflow mirrors).
+  CODEX_REVIEW_TIMEOUT_SECONDS,
+  CODEX_REVIEW_DEFAULT_EFFORT,
+  CODEX_TIMEOUT,
+  CODEX_QE_SIGNAL_PREFIX,
+  CODEX_QE_DECLINE_KINDS,
+  SCOPED_QE_MAX_FILES,
+  SCOPED_QE_MAX_QUESTIONS,
+  SCOPED_QE_MAX_PATH_CHARS,
+  SCOPED_QE_MAX_QUESTION_CHARS,
+  SCOPED_QE_PROMPT_MAX_CHARS,
+  isSafeCodexRef,
+  codexReviewCommand,
+  codexQeSignalCommand,
+  scopedQePrompt,
+  parseCodexReviewSignal,
+  parseCodexReviewFindings,
+  gradeFromReviewFindings,
+  classifyCodexQeOutcome,
+  codexQeDeclineReason,
+  codexDeclineReason,
+  parseCodexReviewResult,
 } from './feature-adr-routing.js';
 export type {
   StageOpts,
   RoutingEnv,
+  CrossFamilyQeReport,
+  ModeBScopeVerdict,
+  PartitionedFindings,
+  FileHashSnapshot,
   UsageSignal,
   UsageAction,
   CodeLandingStatus,
@@ -583,6 +649,15 @@ export type {
   ParsedBaselineCapture,
   ParsedLandingSignal,
   PlanGateVerdict,
+  PlanGateCmdOpts,
+  CodexReviewCommandInput,
+  CodexReviewCommandResult,
+  ScopedQePromptInput,
+  ParsedCodexQeSignal,
+  CodexQeFinding,
+  ClassifyCodexQeInput,
+  CodexQeDeclineDetail,
+  CodexReviewResult,
 } from './feature-adr-routing.js';
 export {
   CLAUDE_USAGE_MODELS,

package/src/loop-blobs.generated.ts

@@ -43,11 +43,11 @@ export const BLOBS: Record<string, LoopBlob> = {
   "checkpoints": {
     name: "checkpoints",
     version: "1.1.0",
-    contentHash: "d4dc6c956be3dd279b225bc5061ec4255babc44ffb5ca58646c9b6ea04a0c8c2",
+    contentHash: "a44560c6036fd143b7a3f125fec00fa8b91c3c06ac5b9e1ecfb83d27a5211e9b",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-checkpoints.ts",
     requires: [],
-    exports: ["CHECKPOINT_STAGES","STAGE_ARTIFACTS","CHECKPOINT_MAX_RESULT_CHARS","CKPT_SCHEMA_VERSION","fnv1a","fnv1a64","checkpointInputHash","resumeMode","decideCheckpointResume","serializeCheckpoint","CHECKPOINT_LS_SENTINEL","parseCheckpointRead","shellQuote","checkpointReadCmd","checkpointAppendCmd","DESIGN_SUBSTAGES","designStageKey","decideDesignFanResume","parseArtifactProbe"],
-    code: "const CHECKPOINT_STAGES = ['router', 'design', 'plan', 'code', 'qe', 'fleet'];\nconst STAGE_ARTIFACTS = {\n    router: null,\n    design: '01_requirements.md',\n    plan: '06_implementation_plan.md',\n    code: '07_code_changes/change_manifest.md',\n    qe: '08_qe_report.md',\n    fleet: '09_fleet_qe_assessment.md',\n};\nconst CHECKPOINT_MAX_RESULT_CHARS = 12000;\nconst CKPT_SCHEMA_VERSION = 'fa-ckpt-3';\nfunction fnv1a(str) {\n    let h = 0x811c9dc5;\n    for (let i = 0; i < str.length; i++) {\n        h ^= str.charCodeAt(i);\n        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n    }\n    return h.toString(16).padStart(8, '0');\n}\nfunction fnv1a64(str) {\n    return fnv1a(str) + fnv1a('fa-ckpt-salt' + str);\n}\nfunction checkpointInputHash(stage, parts) {\n    return fnv1a64(JSON.stringify([CKPT_SCHEMA_VERSION, stage, ...parts.map((p) => (p === undefined ? null : p))]));\n}\nfunction resumeMode(raw) {\n    return raw === 'never' ? 'never' : raw === 'force' ? 'force' : 'auto';\n}\nconst DESIGN_SUBSTAGES = ['requirements', 'adr', 'qcsd', 'architecture'];\nfunction designStageKey(sub) {\n    return 'design:' + sub;\n}\nfunction decideDesignFanResume(opts) {\n    const missingSubstages = [];\n    opts.required.forEach((sub, i) => {\n        const r = opts.results[i];\n        if (r === null || r === undefined)\n            missingSubstages.push(sub);\n    });\n    const missingArtifacts = [];\n    let probeMissing = false;\n    if (opts.artifacts.length > 0) {\n        if (opts.postRunListing === null)\n            probeMissing = true;\n        else\n            for (const rel of opts.artifacts)\n                if (!opts.postRunListing.has(rel))\n                    missingArtifacts.push(rel);\n    }\n    const reason = missingSubstages.length > 0 ? 'substage-missing'\n        : probeMissing ? 'probe-not-established'\n            : missingArtifacts.length > 0 ? 'artifact-missing'\n                : 'ok';\n    return { complete: reason === 'ok', missingSubstages, missingArtifacts, reason };\n}\nfunction decideCheckpointResume(opts) {\n    if (opts.mode === 'never')\n        return { resume: false, reason: 'mode-never' };\n    if (!opts.entry || opts.entry.result === null || opts.entry.result === undefined) {\n        return { resume: false, reason: 'no-checkpoint' };\n    }\n    if (opts.entry.inputHash !== opts.inputHash)\n        return { resume: false, reason: 'stale-input' };\n    if (opts.mode === 'force')\n        return { resume: true, reason: 'resumed-force' };\n    const required = opts.artifactRel === null ? [] : (typeof opts.artifactRel === 'string' ? [opts.artifactRel] : opts.artifactRel);\n    for (const rel of required) {\n        if (!opts.listing.has(rel))\n            return { resume: false, reason: 'artifact-missing' };\n    }\n    return { resume: true, reason: 'resumed' };\n}\nfunction serializeCheckpoint(stage, inputHash, result) {\n    if (result === null || result === undefined)\n        return null;\n    let line;\n    try {\n        line = JSON.stringify({ stage, inputHash, result });\n    }\n    catch {\n        return null;\n    }\n    if (typeof line !== 'string' || line.length > CHECKPOINT_MAX_RESULT_CHARS)\n        return null;\n    return line;\n}\nconst CHECKPOINT_LS_SENTINEL = '---FA-CKPT-LS---';\nfunction parseCheckpointRead(text) {\n    const out = { entries: {}, listing: new Set(), malformedLines: 0 };\n    const raw = String(text ?? '');\n    const lines = raw.split('\\n');\n    const sentinelAt = lines.findIndex((l) => l.trim() === CHECKPOINT_LS_SENTINEL);\n    const body = sentinelAt === -1 ? lines : lines.slice(0, sentinelAt);\n    const ls = sentinelAt === -1 ? [] : lines.slice(sentinelAt + 1);\n    for (const line of body) {\n        const t = line.trim();\n        if (t === '')\n            continue;\n        try {\n            const e = JSON.parse(t);\n            if (e && typeof e === 'object' && typeof e.stage === 'string' && typeof e.inputHash === 'string' && 'result' in e && e.result !== null && e.result !== undefined) {\n                out.entries[e.stage] = e;\n            }\n            else {\n                if (e && typeof e === 'object' && typeof e.stage === 'string')\n                    delete out.entries[e.stage];\n                out.malformedLines++;\n            }\n        }\n        catch {\n            out.malformedLines++;\n        }\n    }\n    for (const line of ls) {\n        const t = line.trim();\n        if (t !== '')\n            out.listing.add(t);\n    }\n    return out;\n}\nfunction shellQuote(s) {\n    return \"'\" + String(s).replace(/'/g, \"'\\\\''\") + \"'\";\n}\nfunction checkpointReadCmd(fdirAbs) {\n    const q = shellQuote(fdirAbs);\n    return ('cat ' + q + '/.fa-state/checkpoints.jsonl 2>/dev/null || true; ' +\n        \"echo '\" + CHECKPOINT_LS_SENTINEL + \"'; \" +\n        'cd ' + q + ' 2>/dev/null && find . -maxdepth 2 -type f 2>/dev/null | sed \"s|^\\\\./||\" || true');\n}\nfunction checkpointAppendCmd(fdirAbs, line) {\n    const dir = shellQuote(fdirAbs + '/.fa-state');\n    const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');\n    return 'mkdir -p ' + dir + \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + file;\n}\nfunction parseArtifactProbe(opts) {\n    if (opts.stdout === null || opts.stdout === undefined)\n        return null;\n    const known = new Map();\n    for (const rel of opts.required)\n        known.set('HAVE:' + rel, rel);\n    const found = new Set();\n    let sentinels = 0;\n    for (const raw of String(opts.stdout).split('\\n')) {\n        const line = raw.trim();\n        if (line === '')\n            continue;\n        if (line === opts.sentinel) {\n            sentinels++;\n            continue;\n        }\n        if (sentinels > 0)\n            return null;\n        const rel = known.get(line);\n        if (rel === undefined)\n            return null;\n        found.add(rel);\n    }\n    if (sentinels !== 1)\n        return null;\n    return found;\n}",
+    exports: ["CHECKPOINT_STAGES","STAGE_ARTIFACTS","CHECKPOINT_MAX_RESULT_CHARS","CKPT_SCHEMA_VERSION","fnv1a","fnv1a64","checkpointInputHash","resumeMode","decideCheckpointResume","serializeCheckpoint","CHECKPOINT_LS_SENTINEL","parseCheckpointRead","shellQuote","checkpointReadCmd","checkpointAppendCmd","DESIGN_SUBSTAGES","designStageKey","decideDesignFanResume","parseArtifactProbe","ROUTER_CONTRACT_TOKEN"],
+    code: "const CHECKPOINT_STAGES = ['router', 'design', 'plan', 'code', 'qe', 'fleet'];\nconst STAGE_ARTIFACTS = {\n    router: '00_complexity_assessment.md',\n    design: '01_requirements.md',\n    plan: '06_implementation_plan.md',\n    code: '07_code_changes/change_manifest.md',\n    qe: '08_qe_report.md',\n    fleet: '09_fleet_qe_assessment.md',\n};\nconst CHECKPOINT_MAX_RESULT_CHARS = 12000;\nconst CKPT_SCHEMA_VERSION = 'fa-ckpt-3';\nconst ROUTER_CONTRACT_TOKEN = 'router-writes-00-v1';\nfunction fnv1a(str) {\n    let h = 0x811c9dc5;\n    for (let i = 0; i < str.length; i++) {\n        h ^= str.charCodeAt(i);\n        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;\n    }\n    return h.toString(16).padStart(8, '0');\n}\nfunction fnv1a64(str) {\n    return fnv1a(str) + fnv1a('fa-ckpt-salt' + str);\n}\nfunction checkpointInputHash(stage, parts) {\n    return fnv1a64(JSON.stringify([CKPT_SCHEMA_VERSION, stage, ...parts.map((p) => (p === undefined ? null : p))]));\n}\nfunction resumeMode(raw) {\n    return raw === 'never' ? 'never' : raw === 'force' ? 'force' : 'auto';\n}\nconst DESIGN_SUBSTAGES = ['requirements', 'adr', 'qcsd', 'architecture'];\nfunction designStageKey(sub) {\n    return 'design:' + sub;\n}\nfunction decideDesignFanResume(opts) {\n    const missingSubstages = [];\n    opts.required.forEach((sub, i) => {\n        const r = opts.results[i];\n        if (r === null || r === undefined)\n            missingSubstages.push(sub);\n    });\n    const missingArtifacts = [];\n    let probeMissing = false;\n    if (opts.artifacts.length > 0) {\n        if (opts.postRunListing === null)\n            probeMissing = true;\n        else\n            for (const rel of opts.artifacts)\n                if (!opts.postRunListing.has(rel))\n                    missingArtifacts.push(rel);\n    }\n    const reason = missingSubstages.length > 0 ? 'substage-missing'\n        : probeMissing ? 'probe-not-established'\n            : missingArtifacts.length > 0 ? 'artifact-missing'\n                : 'ok';\n    return { complete: reason === 'ok', missingSubstages, missingArtifacts, reason };\n}\nfunction decideCheckpointResume(opts) {\n    if (opts.mode === 'never')\n        return { resume: false, reason: 'mode-never' };\n    if (!opts.entry || opts.entry.result === null || opts.entry.result === undefined) {\n        return { resume: false, reason: 'no-checkpoint' };\n    }\n    if (opts.entry.inputHash !== opts.inputHash)\n        return { resume: false, reason: 'stale-input' };\n    if (opts.mode === 'force')\n        return { resume: true, reason: 'resumed-force' };\n    const required = opts.artifactRel === null ? [] : (typeof opts.artifactRel === 'string' ? [opts.artifactRel] : opts.artifactRel);\n    for (const rel of required) {\n        if (!opts.listing.has(rel))\n            return { resume: false, reason: 'artifact-missing' };\n    }\n    return { resume: true, reason: 'resumed' };\n}\nfunction serializeCheckpoint(stage, inputHash, result) {\n    if (result === null || result === undefined)\n        return null;\n    let line;\n    try {\n        line = JSON.stringify({ stage, inputHash, result });\n    }\n    catch {\n        return null;\n    }\n    if (typeof line !== 'string' || line.length > CHECKPOINT_MAX_RESULT_CHARS)\n        return null;\n    return line;\n}\nconst CHECKPOINT_LS_SENTINEL = '---FA-CKPT-LS---';\nfunction parseCheckpointRead(text) {\n    const out = { entries: {}, listing: new Set(), malformedLines: 0 };\n    const raw = String(text ?? '');\n    const lines = raw.split('\\n');\n    const sentinelAt = lines.findIndex((l) => l.trim() === CHECKPOINT_LS_SENTINEL);\n    const body = sentinelAt === -1 ? lines : lines.slice(0, sentinelAt);\n    const ls = sentinelAt === -1 ? [] : lines.slice(sentinelAt + 1);\n    for (const line of body) {\n        const t = line.trim();\n        if (t === '')\n            continue;\n        try {\n            const e = JSON.parse(t);\n            if (e && typeof e === 'object' && typeof e.stage === 'string' && typeof e.inputHash === 'string' && 'result' in e && e.result !== null && e.result !== undefined) {\n                out.entries[e.stage] = e;\n            }\n            else {\n                if (e && typeof e === 'object' && typeof e.stage === 'string')\n                    delete out.entries[e.stage];\n                out.malformedLines++;\n            }\n        }\n        catch {\n            out.malformedLines++;\n        }\n    }\n    for (const line of ls) {\n        const t = line.trim();\n        if (t !== '')\n            out.listing.add(t);\n    }\n    return out;\n}\nfunction shellQuote(s) {\n    return \"'\" + String(s).replace(/'/g, \"'\\\\''\") + \"'\";\n}\nfunction checkpointReadCmd(fdirAbs) {\n    const q = shellQuote(fdirAbs);\n    return ('cat ' + q + '/.fa-state/checkpoints.jsonl 2>/dev/null || true; ' +\n        \"echo '\" + CHECKPOINT_LS_SENTINEL + \"'; \" +\n        'cd ' + q + ' 2>/dev/null && find . -maxdepth 2 -type f 2>/dev/null | sed \"s|^\\\\./||\" || true');\n}\nfunction checkpointAppendCmd(fdirAbs, line) {\n    const dir = shellQuote(fdirAbs + '/.fa-state');\n    const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');\n    return 'mkdir -p ' + dir + \" && printf '%s\\\\n' \" + shellQuote(line) + ' >> ' + file;\n}\nfunction parseArtifactProbe(opts) {\n    if (opts.stdout === null || opts.stdout === undefined)\n        return null;\n    const known = new Map();\n    for (const rel of opts.required)\n        known.set('HAVE:' + rel, rel);\n    const found = new Set();\n    let sentinels = 0;\n    for (const raw of String(opts.stdout).split('\\n')) {\n        const line = raw.trim();\n        if (line === '')\n            continue;\n        if (line === opts.sentinel) {\n            sentinels++;\n            continue;\n        }\n        if (sentinels > 0)\n            return null;\n        const rel = known.get(line);\n        if (rel === undefined)\n            return null;\n        found.add(rel);\n    }\n    if (sentinels !== 1)\n        return null;\n    return found;\n}",
   },
   "training-pairs": {
     name: "training-pairs",
@@ -79,11 +79,11 @@ export const BLOBS: Record<string, LoopBlob> = {
   "codex-dispatch": {
     name: "codex-dispatch",
     version: "1.0.0",
-    contentHash: "140da3714d2507683b0a27fcb01fa449ea3cb1619f1a2e181aaf24291397642d",
+    contentHash: "f203268da376fa993ce61d38b8fc6a24db4ac1e3edb6b90662f86ae4351a30e7",
     sourcePath: "packages/@dzhechkov/harness-core/src/feature-adr-routing.ts",
     requires: [],
     exports: ["codexDispatchMode","codexExecPlan","needsCodeLandedBarrier","decideCodeLanding"],
-    code: "const CODE_LANDING_PIPELINE_PREFIXES = ['features/', '.dz/', '.agentic-qe/', 'roam/'];\nfunction codeLandingEmptySignal(seconds) {\n    return 'changed=0 after ' + seconds + 's — genuinely not landed';\n}\nfunction needsCodeLandedBarrier(coderUsed) {\n    return coderUsed === 'codex' || coderUsed === 'codex-fallback';\n}\nfunction stripCodeLandingPath(path) {\n    let p = String(path || '').trim().replace(/\\\\/g, '/');\n    while (p.indexOf('./') === 0)\n        p = p.slice(2);\n    return p.replace(/\\/+/g, '/');\n}\nfunction classifyCodeLandingPathReject(path) {\n    const p = stripCodeLandingPath(path);\n    if (!p)\n        return 'empty-after-strip';\n    if (p[0] === '/')\n        return 'absolute-path';\n    if (p === '..' || p.indexOf('../') === 0 || p.indexOf('/../') >= 0 || p.endsWith('/..'))\n        return 'traversal';\n    if (/[\\0\\r\\n\\t \"'\\x60$;&|<>*?()[\\]{}!]/.test(p))\n        return 'not-a-path';\n    if (p.endsWith('/'))\n        return 'not-a-path';\n    for (const prefix of CODE_LANDING_PIPELINE_PREFIXES) {\n        const bare = prefix.slice(0, -1);\n        if (p === bare || p.indexOf(prefix) === 0)\n            return 'pipeline-artifact-path';\n    }\n    return null;\n}\nfunction normalizeCodeLandingPath(path) {\n    return classifyCodeLandingPathReject(path) === null ? stripCodeLandingPath(path) : '';\n}\nfunction filterPollableCodePaths(paths) {\n    const out = [];\n    const seen = new Set();\n    for (const path of paths || []) {\n        const normalized = normalizeCodeLandingPath(path);\n        if (!normalized || seen.has(normalized))\n            continue;\n        seen.add(normalized);\n        out.push(normalized);\n    }\n    return out;\n}\nfunction isNewlyChanged(path, baseline, currentHashes) {\n    if (!baseline || !baseline.ok)\n        return false;\n    let recorded = null;\n    for (const entry of baseline.entries) {\n        if (entry.path === path) {\n            recorded = entry.hash;\n            break;\n        }\n    }\n    if (recorded === null)\n        return true;\n    const now = currentHashes ? currentHashes[path] : undefined;\n    if (now === undefined)\n        return false;\n    return now !== recorded;\n}\nfunction decideCodeLanding(snapshot) {\n    const maxWaitMs = Math.max(0, snapshot.maxWaitMs);\n    const elapsedMs = Math.max(0, snapshot.elapsedMs);\n    const elapsedSeconds = Math.floor(elapsedMs / 1000);\n    const expectedPaths = filterPollableCodePaths(snapshot.expectedPaths);\n    const changedPaths = filterPollableCodePaths(snapshot.changedEntries.map(function (entry) { return entry.path; }));\n    if (expectedPaths.length === 0) {\n        return {\n            status: 'inconclusive',\n            reason: 'empty-plan-block',\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'no-expected-targets',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=no-expected-targets reason=empty-plan-block',\n        };\n    }\n    const baseline = snapshot.baseline;\n    if (!baseline || !baseline.ok) {\n        const reason = baseline && baseline.reason ? baseline.reason : 'no-baseline';\n        return {\n            status: 'inconclusive',\n            reason: reason,\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'newly-changed',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=' + reason,\n        };\n    }\n    const changed = new Set(changedPaths);\n    const matchedExpectedPaths = expectedPaths.filter(function (path) {\n        return changed.has(path) && isNewlyChanged(path, baseline, snapshot.currentHashes);\n    });\n    if (matchedExpectedPaths.length > 0) {\n        return {\n            status: 'landed',\n            changed: matchedExpectedPaths.length,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: matchedExpectedPaths,\n            changedPaths: changedPaths,\n            predicate: 'newly-changed',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=landed changed=' +\n                matchedExpectedPaths.length +\n                ' after=' +\n                elapsedSeconds +\n                's predicate=newly-changed matched=' +\n                matchedExpectedPaths.join(','),\n        };\n    }\n    if (elapsedMs < maxWaitMs) {\n        return {\n            status: 'not-yet-flushed',\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'empty-before-timeout',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=not-yet-flushed changed=0 after ' + elapsedSeconds + 's — not yet flushed',\n        };\n    }\n    const terminalSeconds = Math.ceil(maxWaitMs / 1000);\n    return {\n        status: 'genuinely-not-landed',\n        changed: 0,\n        elapsedMs: elapsedMs,\n        elapsedSeconds: terminalSeconds,\n        expectedPaths: expectedPaths,\n        matchedExpectedPaths: [],\n        changedPaths: changedPaths,\n        predicate: 'empty-after-timeout',\n        qeSignalLine: 'CODEX-LANDING-SIGNAL status=genuinely-not-landed ' + codeLandingEmptySignal(terminalSeconds),\n    };\n}\nconst WRAPPER_STAGES = { code: 1, plan: 1 };\nfunction codexDispatchMode(stage) {\n    return WRAPPER_STAGES[stage] ? 'wrapper' : 'exec';\n}\nconst CODEX_EXEC_PROMPT_CEILING_CHARS = 24000;\nfunction codexExecPlan(input) {\n    if (codexDispatchMode(input.stage) === 'wrapper') {\n        return { mode: 'wrapper', reason: 'deliverable is a file written out-of-band' };\n    }\n    if (!input.probedId) {\n        return { mode: 'claude', reason: 'no codex model id answered the probe' };\n    }\n    if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {\n        return {\n            mode: 'claude',\n            reason: 'prompt is ' +\n                input.promptChars +\n                ' chars, over the ' +\n                CODEX_EXEC_PROMPT_CEILING_CHARS +\n                '-char codex exec ceiling (it would stall)',\n        };\n    }\n    return { mode: 'exec', reason: 'codex exec on ' + input.probedId };\n}",
+    code: "const CODE_LANDING_PIPELINE_PREFIXES = ['features/', '.dz/', '.agentic-qe/', 'roam/'];\nfunction codeLandingEmptySignal(seconds) {\n    return 'changed=0 after ' + seconds + 's — genuinely not landed';\n}\nfunction needsCodeLandedBarrier(coderUsed) {\n    return coderUsed === 'codex' || coderUsed === 'codex-fallback';\n}\nfunction stripCodeLandingPath(path) {\n    let p = String(path || '').trim().replace(/\\\\/g, '/');\n    while (p.indexOf('./') === 0)\n        p = p.slice(2);\n    return p.replace(/\\/+/g, '/');\n}\nfunction classifyCodeLandingPathReject(path) {\n    const p = stripCodeLandingPath(path);\n    if (!p)\n        return 'empty-after-strip';\n    if (p[0] === '/')\n        return 'absolute-path';\n    if (p === '..' || p.indexOf('../') === 0 || p.indexOf('/../') >= 0 || p.endsWith('/..'))\n        return 'traversal';\n    if (/[\\0\\r\\n\\t \"'\\x60$;&|<>*?()[\\]{}!]/.test(p))\n        return 'not-a-path';\n    if (p.endsWith('/'))\n        return 'not-a-path';\n    for (const prefix of CODE_LANDING_PIPELINE_PREFIXES) {\n        const bare = prefix.slice(0, -1);\n        if (p === bare || p.indexOf(prefix) === 0)\n            return 'pipeline-artifact-path';\n    }\n    return null;\n}\nfunction normalizeCodeLandingPath(path) {\n    return classifyCodeLandingPathReject(path) === null ? stripCodeLandingPath(path) : '';\n}\nfunction filterPollableCodePaths(paths) {\n    const out = [];\n    const seen = new Set();\n    for (const path of paths || []) {\n        const normalized = normalizeCodeLandingPath(path);\n        if (!normalized || seen.has(normalized))\n            continue;\n        seen.add(normalized);\n        out.push(normalized);\n    }\n    return out;\n}\nfunction isNewlyChanged(path, baseline, currentHashes) {\n    if (!baseline || !baseline.ok)\n        return false;\n    let recorded = null;\n    for (const entry of baseline.entries) {\n        if (entry.path === path) {\n            recorded = entry.hash;\n            break;\n        }\n    }\n    if (recorded === null)\n        return true;\n    const now = currentHashes ? currentHashes[path] : undefined;\n    if (now === undefined)\n        return false;\n    return now !== recorded;\n}\nfunction decideCodeLanding(snapshot) {\n    const maxWaitMs = Math.max(0, snapshot.maxWaitMs);\n    const elapsedMs = Math.max(0, snapshot.elapsedMs);\n    const elapsedSeconds = Math.floor(elapsedMs / 1000);\n    const expectedPaths = filterPollableCodePaths(snapshot.expectedPaths);\n    const changedPaths = filterPollableCodePaths(snapshot.changedEntries.map(function (entry) { return entry.path; }));\n    if (expectedPaths.length === 0) {\n        return {\n            status: 'inconclusive',\n            reason: 'empty-plan-block',\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'no-expected-targets',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=no-expected-targets reason=empty-plan-block',\n        };\n    }\n    const baseline = snapshot.baseline;\n    if (!baseline || !baseline.ok) {\n        const reason = baseline && baseline.reason ? baseline.reason : 'no-baseline';\n        return {\n            status: 'inconclusive',\n            reason: reason,\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'newly-changed',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=' + reason,\n        };\n    }\n    const changed = new Set(changedPaths);\n    const matchedExpectedPaths = expectedPaths.filter(function (path) {\n        return changed.has(path) && isNewlyChanged(path, baseline, snapshot.currentHashes);\n    });\n    if (matchedExpectedPaths.length > 0) {\n        return {\n            status: 'landed',\n            changed: matchedExpectedPaths.length,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: matchedExpectedPaths,\n            changedPaths: changedPaths,\n            predicate: 'newly-changed',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=landed changed=' +\n                matchedExpectedPaths.length +\n                ' after=' +\n                elapsedSeconds +\n                's predicate=newly-changed matched=' +\n                matchedExpectedPaths.join(','),\n        };\n    }\n    if (elapsedMs < maxWaitMs) {\n        return {\n            status: 'not-yet-flushed',\n            changed: 0,\n            elapsedMs: elapsedMs,\n            elapsedSeconds: elapsedSeconds,\n            expectedPaths: expectedPaths,\n            matchedExpectedPaths: [],\n            changedPaths: changedPaths,\n            predicate: 'empty-before-timeout',\n            qeSignalLine: 'CODEX-LANDING-SIGNAL status=not-yet-flushed changed=0 after ' + elapsedSeconds + 's — not yet flushed',\n        };\n    }\n    const terminalSeconds = Math.ceil(maxWaitMs / 1000);\n    return {\n        status: 'genuinely-not-landed',\n        changed: 0,\n        elapsedMs: elapsedMs,\n        elapsedSeconds: terminalSeconds,\n        expectedPaths: expectedPaths,\n        matchedExpectedPaths: [],\n        changedPaths: changedPaths,\n        predicate: 'empty-after-timeout',\n        qeSignalLine: 'CODEX-LANDING-SIGNAL status=genuinely-not-landed ' + codeLandingEmptySignal(terminalSeconds),\n    };\n}\nconst WRAPPER_STAGES = { code: 1, plan: 1 };\nfunction codexDispatchMode(stage) {\n    return WRAPPER_STAGES[stage] ? 'wrapper' : 'exec';\n}\nconst CODEX_EXEC_PROMPT_CEILING_CHARS = 24000;\nfunction codexExecPlan(input) {\n    if (codexDispatchMode(input.stage) === 'wrapper') {\n        return { mode: 'wrapper', reason: 'deliverable is a file written out-of-band' };\n    }\n    if (!input.probedId) {\n        return { mode: 'claude', reason: 'no codex model id answered the probe' };\n    }\n    if (input.stage === 'qe' && input.scoped !== true) {\n        return {\n            mode: 'claude',\n            reason: 'qe prompt is not SCOPED — an unscoped codex exec QE buys reconnaissance, not review ' +\n                '(MEASURED 2026-08-21: 19038 chars, 280s, exit 124, no verdict)',\n        };\n    }\n    if (input.promptChars > CODEX_EXEC_PROMPT_CEILING_CHARS) {\n        return {\n            mode: 'claude',\n            reason: 'prompt is ' +\n                input.promptChars +\n                ' chars, over the ' +\n                CODEX_EXEC_PROMPT_CEILING_CHARS +\n                '-char codex exec ceiling (it would stall)',\n        };\n    }\n    return { mode: 'exec', reason: 'codex exec on ' + input.probedId };\n}\nconst SCOPED_QE_MAX_FILES = 3;\nconst SCOPED_QE_MAX_QUESTIONS = 4;\nconst SCOPED_QE_MAX_PATH_CHARS = 200;\nconst SCOPED_QE_MAX_QUESTION_CHARS = 200;\nfunction scopedQePrompt(input) {\n    const o = input || {};\n    const rawFiles = Array.isArray(o.files) ? o.files : [];\n    const files = [];\n    for (const f of rawFiles) {\n        const s = String(f === undefined || f === null ? '' : f).trim();\n        if (s === '')\n            continue;\n        if (files.indexOf(s) !== -1)\n            continue;\n        files.push(s.slice(0, SCOPED_QE_MAX_PATH_CHARS));\n        if (files.length >= SCOPED_QE_MAX_FILES)\n            break;\n    }\n    if (files.length === 0)\n        return '';\n    const rawQuestions = Array.isArray(o.questions) ? o.questions : [];\n    const questions = [];\n    for (const q of rawQuestions) {\n        const s = String(q === undefined || q === null ? '' : q).trim().replace(/\\s+/g, ' ');\n        if (s === '')\n            continue;\n        questions.push(s.slice(0, SCOPED_QE_MAX_QUESTION_CHARS));\n        if (questions.length >= SCOPED_QE_MAX_QUESTIONS)\n            break;\n    }\n    if (questions.length === 0) {\n        questions.push('Is this change correct, and does the test named by its ADR actually DISCRIMINATE (would it fail if the protection were deleted)?');\n    }\n    const slug = String(o.slug === undefined || o.slug === null ? '' : o.slug).trim().slice(0, 60);\n    let out = 'Read ONLY these files: ' + files.join(', ') + '. Do NOT open any other file and do NOT explore the repository.';\n    if (slug !== '')\n        out += ' They are the changed files of feature ' + slug + '.';\n    out += '\\n\\nAnswer these ' + questions.length + ' questions about them:\\n';\n    for (let i = 0; i < questions.length; i++)\n        out += i + 1 + '. ' + questions[i] + '\\n';\n    out += '\\nFinish with a single final line: Grade: <A|B|C|D>';\n    return out;\n}",
   },
   "challenge-panel": {
     name: "challenge-panel",

package/src/patterns.ts

@@ -287,7 +287,10 @@ export function computePatternBoost(
       matched = true;
     } else {
       // medium: a meaningful word from the pattern appears in the skill haystack
-      for (const word of text.split(/[^a-z0-9]+/)) {
+      // `\p{L}\p{N}`, not `a-z0-9`: the ASCII-only class made every non-Latin word invisible to
+      // the boost, so a Cyrillic pattern could never match a skill haystack. The `>= 5` rule below
+      // is this site's OWN threshold and is deliberately unchanged — only the alphabet moved.
+      for (const word of text.split(/[^\p{L}\p{N}]+/u)) {
         if (word.length >= 5 && haystack.includes(word)) {
           matched = true;
           break;

package/src/run-records.ts

@@ -0,0 +1,220 @@
+/**
+ * Witnessed run records — the decision half of `dz feature-adr-record` (ADR-001 … ADR-003).
+ *
+ * Two durable writers in the /feature-adr workflow still handed a subagent a PRE-BAKED shell string
+ * carrying their payload: the run-cost ledger and the training-pair capture. That is the shape a
+ * security classifier blocked NINE times in one run — one entity instructing another to append state
+ * it never verified. The checkpoint writer was migrated for that reason; these two were left behind.
+ *
+ * The role change is the point: the subagent stops being a COURIER (handed a shell string, appends
+ * it) and becomes a CALLER (handed arguments; the command decides). A courier can neither refuse nor
+ * verify.
+ *
+ * Pure: payload in, verdict out. The CLI owns paths, the append, the read-back and the exit code.
+ */
+
+export type RecordKind = 'ledger' | 'training-pair';
+
+export type RecordVerdict =
+  /** the line was appended AND read back equal */
+  | 'written'
+  /** a mark shows another run got here first — nothing written, nothing wrong */
+  | 'duplicate'
+  /** the target already held this pair — nothing written, nothing wrong */
+  | 'skipped'
+  /** the payload was rejected before any write; the target is untouched */
+  | 'refused'
+  /** the append happened but the read-back disagreed — the caller MUST treat this as NOT written */
+  | 'not-verified';
+
+export interface RecordDecision {
+  readonly verdict: RecordVerdict;
+  /** One mapping, never two: 0 written|duplicate|skipped · 2 refused · 3 not-verified. */
+  readonly exit: 0 | 2 | 3;
+  readonly reason: string;
+  /**
+   * ALWAYS false. A cost row and a training pair are observability, and observability must not take
+   * the run down with it (ADR-003). The field exists so the property is assertable rather than
+   * merely intended — a thrown refusal would turn bookkeeping into an outage.
+   */
+  readonly blocking: false;
+  /** The exact line to append, or null when nothing may be written. */
+  readonly line: string | null;
+  /** Set when a mark was found without its target — the previous holder died before writing. */
+  readonly staleMark?: boolean;
+}
+
+/** A serialised record line above this is refused rather than truncated (acid case A2). */
+export const RECORD_MAX_LINE_CHARS = 24_000;
+
+/** Fields every ledger row must carry before it is worth writing down. */
+const LEDGER_REQUIRED = ['slug', 'stage'] as const;
+/** Fields every training pair must carry — the dataset is worthless without input/output. */
+const PAIR_REQUIRED = ['slug', 'stage', 'input', 'output'] as const;
+
+const refuse = (reason: string): RecordDecision => ({ verdict: 'refused', exit: 2, reason, blocking: false, line: null });
+
+/** `duplicate` and `skipped` both wrote nothing and both are fine — but they are DIFFERENT facts. */
+const noop = (verdict: 'duplicate' | 'skipped', reason: string): RecordDecision => ({
+  verdict,
+  exit: 0,
+  reason,
+  blocking: false,
+  line: null,
+});
+
+function shapeMismatch(kind: RecordKind, payload: Record<string, unknown>): string | null {
+  // AM-1 FIRST, before the required-field sweep. A ledger row offered as a training pair fails BOTH
+  // checks, and the wrong-kind reason is the one that tells the caller what actually happened —
+  // "missing field `output`" sends them looking for a field they never meant to send.
+  if (kind === 'ledger' && 'input' in payload && 'output' in payload) {
+    // BOTH fields together are the training-pair signature. Either one alone is not: a ledger row may
+    // legitimately carry `input: {cached_tokens: 80}` (cross-family review, 2026-08-21) and refusing
+    // it would make the command reject honest data on a name collision.
+    return 'this payload carries BOTH `input` and `output` — it is a training pair, not a ledger row';
+  }
+  if (kind === 'training-pair' && 'tokens' in payload && !('input' in payload)) {
+    return 'this payload looks like a ledger row (`tokens` without `input`), not a training pair';
+  }
+  const required = kind === 'ledger' ? LEDGER_REQUIRED : PAIR_REQUIRED;
+  for (const field of required) {
+    const v = payload[field];
+    if (v === undefined || v === null) return `a ${kind} record is missing the required field \`${field}\``;
+    // EMPTY is not present. An earlier version checked only string-emptiness, so `input: []` and
+    // `output: {}` satisfied the requirement and an empty record reached the file — a pair with no
+    // content is worse than no pair, because it looks captured.
+    if (typeof v === 'string' && v.trim() === '') return `a ${kind} record has an EMPTY \`${field}\``;
+    if (Array.isArray(v) && v.length === 0) return `a ${kind} record has an EMPTY \`${field}\` (empty array)`;
+    if (typeof v === 'object' && !Array.isArray(v) && Object.keys(v as object).length === 0) {
+      return `a ${kind} record has an EMPTY \`${field}\` (empty object)`;
+    }
+  }
+  return null;
+}
+
+export function decideRecordWrite(input: {
+  kind: RecordKind;
+  /** The raw `--row` / `--pair` argument, exactly as the caller passed it. */
+  payloadRaw: string;
+  /** The stage this record belongs to; a record for a stage that produced nothing is refused. */
+  stage: string;
+  stageProducedResult?: boolean;
+  /** A backfill mark already present ⇒ another run got here first — unless the target is absent. */
+  markExists?: boolean;
+  /** Whether the target file exists; a mark without a target is a STALE mark, not a duplicate. */
+  targetExists?: boolean;
+  /** The target already holds this pair. */
+  targetHasPair?: boolean;
+  /** Stamped INTO the object before serialising — never rewritten in the shell afterwards (FR-7). */
+  timestamp?: string | null;
+  maxChars?: number;
+}): RecordDecision {
+  const { kind, payloadRaw, stage } = input;
+  if (kind !== 'ledger' && kind !== 'training-pair') {
+    return refuse(`unknown --kind \`${String(kind)}\` — expected ledger or training-pair`);
+  }
+  if (typeof stage !== 'string' || stage.trim() === '') return refuse('--stage is required');
+  if (input.stageProducedResult === false) {
+    return refuse(`stage \`${stage}\` produced no result — there is nothing to record`);
+  }
+
+  let payload: unknown;
+  try {
+    payload = JSON.parse(payloadRaw);
+  } catch {
+    return refuse('the payload is not valid JSON — refused before any write, the target is untouched');
+  }
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) {
+    return refuse('the payload must be a JSON object');
+  }
+  const obj = payload as Record<string, unknown>;
+
+  const mismatch = shapeMismatch(kind, obj);
+  if (mismatch !== null) return refuse(mismatch);
+
+  // The record is filed under `--stage`, and the payload carries its own. A disagreement means the
+  // row would land in the wrong stage's file (pairs) or under a wrong label (ledger) — both available
+  // here, so leaving them uncompared was a free check declined.
+  const payloadStage = obj['stage'];
+  if (typeof payloadStage === 'string' && payloadStage !== stage) {
+    return refuse(`the payload's stage \`${payloadStage}\` disagrees with --stage \`${stage}\` — the record would be filed under the wrong stage`);
+  }
+
+  // The no-write outcomes are checked AFTER the payload is validated: reporting `duplicate` for a
+  // malformed payload would hide a real defect behind a benign-looking verdict.
+  // A mark whose TARGET does not exist is STALE: a previous run took the mark and died before writing.
+  // Reporting `duplicate` there lets one crash lose the record forever — the silent-loss shape this
+  // whole feature removes (cross-family review, 2026-08-21). A stale mark does NOT stop the write; it
+  // is recorded on the decision so the caller can say why it proceeded anyway.
+  const staleMark = input.markExists === true && input.targetExists === false;
+  if (input.markExists === true && !staleMark) {
+    return noop('duplicate', 'a mark for this record already exists — another run captured it first');
+  }
+  if (input.targetHasPair === true) {
+    return noop('skipped', 'the target already holds this record — nothing to add');
+  }
+
+  // The timestamp goes in BEFORE serialisation. The shell `sed` this replaces rewrote `"date":null`
+  // inside an already-serialised document — text surgery on a structured value, and the exact place
+  // a payload containing that literal token could corrupt itself.
+  const stamped: Record<string, unknown> = { ...obj };
+  if (input.timestamp != null && input.timestamp !== '') {
+    // An EMPTY STRING is a gap, not a value. Stamping only over null/undefined let
+    // `"date":""` through as `written` (cross-family review, 2026-08-21) — a row that looks recorded
+    // and carries no date.
+    const isGap = (v: unknown): boolean => v === null || v === undefined || (typeof v === 'string' && v.trim() === '');
+    if (kind === 'ledger' && isGap(stamped['date'])) stamped['date'] = input.timestamp.slice(0, 10);
+    if (kind === 'training-pair' && isGap(stamped['ts'])) stamped['ts'] = input.timestamp;
+  }
+
+  let line: string;
+  try {
+    line = JSON.stringify(stamped);
+  } catch {
+    return refuse('the payload could not be serialised (circular or unsupported value)');
+  }
+  const cap = input.maxChars ?? RECORD_MAX_LINE_CHARS;
+  if (line.length > cap) {
+    return refuse(`the serialised record is ${line.length} chars, above the ${cap}-char cap — refused rather than truncated`);
+  }
+  if (line.includes('\n')) return refuse('the serialised record contains a newline — one record is one line');
+
+  return {
+    verdict: 'written',
+    exit: 0,
+    reason: staleMark
+      ? `${kind} record ready to append (a STALE mark was found — its target is absent, so a previous holder died before writing)`
+      : `${kind} record ready to append`,
+    blocking: false,
+    line,
+    staleMark,
+  };
+}
+
+/** The read-back verdict (ADR-002): equal bytes or NOT written. Never inferred from the absence of an error. */
+export function decideReadBack(appended: string, lastLineOnDisk: string | null): RecordDecision {
+  if (lastLineOnDisk === null) {
+    return {
+      verdict: 'not-verified',
+      exit: 3,
+      reason: 'the record was appended but the file could not be read back — treat this as NOT written',
+      blocking: false,
+      line: appended,
+    };
+  }
+  if (lastLineOnDisk !== appended) {
+    return {
+      verdict: 'not-verified',
+      exit: 3,
+      reason: 'the last line on disk differs from what was appended — treat this as NOT written',
+      blocking: false,
+      line: appended,
+    };
+  }
+  return { verdict: 'written', exit: 0, reason: 'appended and verified by re-reading the tail', blocking: false, line: appended };
+}
+
+/** The one line every caller reads last, in the shape the other gates use. */
+export function recordVerdictLine(kind: RecordKind, stage: string, d: RecordDecision): string {
+  return `feature-adr record (${kind}/${stage}): ${d.verdict.toUpperCase()} — ${d.reason}`;
+}