@dzhechkov/harness-core 0.3.149 → 0.4.1

package/src/challenge-panel.ts

@@ -24,6 +24,10 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
+ * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
+export const CHALLENGE_PANEL_BLOB_VERSION = '1.0.0';
+
 export type CId = 'C1' | 'C2' | 'C3' | 'C4' | 'C5' | 'C6' | 'C7' | 'C8';
 export type ChallengeSeverity = 'P0' | 'P1' | 'P2';
 const SEV_RANK: Record<ChallengeSeverity, number> = { P0: 3, P1: 2, P2: 1 };

package/src/export-holdout.ts

@@ -0,0 +1,235 @@
+/**
+ * Domain hold-out for the portable export — DEFENCE IN DEPTH, not the guarantee.
+ *
+ * WHY THIS EXISTS — AND WHY IT IS THE SECOND LINE, NOT THE FIRST.
+ * (This heading once read "the thing that actually protects anything", contradicting the
+ * first line of the same comment. ADR-004 moved the guarantee to a separate store; this
+ * file did not move with it.)
+ *
+ * `health-advisor` teaches lessons learned from a real person's investigations. The
+ * first design tried to keep patient data out of the store by INSPECTING THE TEXT —
+ * deciding, from prose, whether a lesson described a method or a person. Seven rounds
+ * of independent cross-model review graded that F and the finding count never
+ * converged, because the question is about meaning: every pattern answering it fails
+ * in both directions, and none of them can see the case that matters most (a rare
+ * combination identifies a person with no name and no digits in the sentence).
+ *
+ * So the guarantee moved to where a guarantee can live. The realistic way a learned
+ * store leaks is not "somebody read the disk" — it is that the store gets SHARED:
+ * exported to JSON, committed, carried to another machine. `dz recall --all --json` is
+ * that path by design; it is documented as the portable sharing form.
+ *
+ * Holding a domain out of that export is decided by a tag the writer set rather than by
+ * parsing prose, so it is language-independent and provable by a test. But it is NOT the
+ * isolation guarantee, and an earlier version of this comment claiming otherwise was
+ * wrong: filtering each command that emits lesson text is itself an enumeration, and
+ * review produced five more such commands (`guard promote --json`, `epoch-replay
+ * --emit`, `vector harmonize`, `consolidate --prune-quarantine`, the `recall --forget`
+ * preview) the moment four were closed. The guarantee is ADR-004 — health lessons are
+ * written to a SEPARATE store and never reach this one. What remains here is a second
+ * line for stray or legacy records, which is worth having and is not the promise.
+ *
+ * THE PROMISE, NARROWLY. This governs the EXPORT. It does not encrypt the local store,
+ * it does not stop a human from copying a file, and it does not make the lesson text
+ * safe to publish. It means: the one command whose job is to hand the store to someone
+ * else will not hand over this domain unless you say so out loud.
+ */
+
+import type { PatternRecord } from './patterns.js';
+
+/**
+ * Canonical key for hold-out comparison — deliberately NOT `normalizeDomain`.
+ *
+ * `normalizeDomain` serves the RANKING boost, where being slightly wrong costs
+ * ordering. Here being slightly wrong costs a leak, so the two must not share a
+ * definition: review found `Health - Research` normalising to `health---research` and a
+ * FULLWIDTH hyphen (U+FF0D) surviving as its own character — both then exported by the
+ * `else` branch. A hold-out that a spelling variant defeats is not a hold-out.
+ *
+ * So: NFKC-fold first, then lower case, then collapse EVERY run of non-alphanumeric
+ * characters to a single `-`. That is an allowlist over the key (letters and digits
+ * survive, nothing else does) rather than a list of separators to keep up to date.
+ *
+ * NFKC is not decoration. Without it `Ｈｅａｌｔｈ－Ｒｅｓｅａｒｃｈ` in fullwidth forms
+ * produced `ｈｅａｌｔｈ-ｒｅｓｅａｒｃｈ` — a different key, so the record exported. Compatibility
+ * normalisation folds fullwidth, ligature and other presentation variants onto the
+ * characters they stand for, which is exactly the equivalence a tag comparison needs.
+ */
+export function canonicalDomainKey(domain: string | null | undefined): string {
+  return String(domain ?? '')
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Domains held out of the portable export by default.
+ *
+ * `health-research` is written by the `goap-research-ed25519` skill when it runs inside
+ * `health-advisor`. It is listed here rather than configured because a default that has
+ * to be switched ON protects nobody: the person who would have configured it is the
+ * person who already understood the risk.
+ */
+export const DEFAULT_HELD_OUT_DOMAINS: readonly string[] = ['health-research'];
+
+export interface HoldoutResult<T> {
+  /** What the export may hand over. */
+  readonly exported: readonly T[];
+  /** What was withheld — returned, not silently dropped, so the caller can COUNT it. */
+  readonly withheld: readonly T[];
+  /** Which held-out domains actually matched, for an honest message. */
+  readonly domains: readonly string[];
+}
+
+/**
+ * Split records into what may be exported and what is held back.
+ *
+ * Comparison goes through `canonicalDomainKey`, so `Health-Research`, `health_research`,
+ * `Health - Research` and a fullwidth-hyphen spelling are one domain — a tag that leaks
+ * through a spelling variant would be the same class of defect as the text guard this
+ * replaced.
+ *
+ * AN UNTAGGED RECORD IS EXPORTED, and that is a real limit of tag-based isolation rather
+ * than an oversight: with no domain there is nothing to compare, and withholding every
+ * untagged lesson would empty the export for the ordinary case. What closes it upstream
+ * is that the writer always tags — `learning_bridge.py` passes `--domain` on every call.
+ */
+export function applyExportHoldout<T extends { readonly domain?: string | null }>(
+  records: readonly T[],
+  heldOut: readonly string[] = DEFAULT_HELD_OUT_DOMAINS,
+): HoldoutResult<T> {
+  const targets = new Set(heldOut.map(canonicalDomainKey).filter((d) => d !== ''));
+  if (targets.size === 0) return { exported: records, withheld: [], domains: [] };
+  const exported: T[] = [];
+  const withheld: T[] = [];
+  const matched = new Set<string>();
+  for (const record of records) {
+    const domain = canonicalDomainKey(record.domain);
+    if (domain !== '' && targets.has(domain)) {
+      withheld.push(record);
+      matched.add(domain);
+    } else {
+      exported.push(record);
+    }
+  }
+  return { exported, withheld, domains: [...matched].sort() };
+}
+
+/**
+ * The line the export prints when it held something back.
+ *
+ * Empty when nothing was withheld, so the common case stays quiet. When something WAS
+ * withheld the count is stated: a silent hold-out would leave the reader believing they
+ * had exported the whole store, which is its own kind of lie — and it would make a
+ * broken hold-out indistinguishable from an empty domain.
+ */
+export function renderHoldoutNote(result: HoldoutResult<unknown>): string {
+  if (result.withheld.length === 0) return '';
+  const n = result.withheld.length;
+  const domains = result.domains.join(', ');
+  return `  ${n} lesson(s) in ${domains} were HELD BACK from this export — that domain carries medical research and does not travel by default. To include it deliberately: --include-domain ${domains}`;
+}
+
+/** Parse a comma-separated `--include-domain` value into the hold-out list that remains. */
+export function heldOutAfterOptIn(
+  optIn: string | undefined,
+  heldOut: readonly string[] = DEFAULT_HELD_OUT_DOMAINS,
+): readonly string[] {
+  if (optIn === undefined) return heldOut;
+  const requested = new Set(
+    optIn.split(',').map((d) => canonicalDomainKey(d)).filter((d) => d !== ''),
+  );
+  return heldOut.filter((d) => !requested.has(canonicalDomainKey(d)));
+}
+
+/** Convenience for callers holding full `PatternRecord`s. */
+export type PatternHoldout = HoldoutResult<PatternRecord>;
+
+/**
+ * The advice printed when a held-out domain is written into a SHARED store.
+ *
+ * NOT a refusal. Someone who wants their medical lessons in the shared store owns both
+ * directories and the `dz` binary, and stopping them would mean defending a user against
+ * themselves — which this design deliberately does not attempt (ADR-004, threat model).
+ * What it does instead is make sure the choice is INFORMED: say what follows from it,
+ * name the default, and show the one command that does it the other way.
+ *
+ * The distinction that decides whether to warn is the STORE, not the person: a project
+ * whose directory is the health brain is exactly where these lessons belong, so writing
+ * one there is silent. Anywhere else, the lesson is about to join lessons that travel.
+ *
+ * `projectRoot` MUST already be resolved by the caller. Deciding from the unresolved
+ * NAME meant `ln -s <a shared project> /tmp/.health-brain` silenced the advice while the
+ * write landed in the shared store — the advice went quiet in exactly the case it exists
+ * for. A name is a claim about a path; only a resolved path is the path.
+ */
+export function renderSharedStoreAdvice(domain: string | null | undefined, resolvedProjectRoot: string): string {
+  const key = canonicalDomainKey(domain);
+  if (key === '' || !DEFAULT_HELD_OUT_DOMAINS.map(canonicalDomainKey).includes(key)) return '';
+  if (/[\\/]\.health-brain\/?$/.test(resolvedProjectRoot)) return '';
+  return [
+    `  ⚠ "${domain}" is a medical domain, and this is a SHARED store.`,
+    '    Lessons here are read by every command that reads this store, and the portable',
+    '    export (dz recall --all --json) is how a store leaves a machine. We recommend',
+    '    against it by default: keep medical lessons in their own store, which also keeps',
+    '    the prompts and transcripts of that work in one place you can inspect or delete.',
+    `    The other way: dz teach "<lesson>" --domain ${domain} --project <dir>/.health-brain`,
+    '    Nothing was blocked — this is your call, and it is now on the record.',
+  ].join('\n');
+}
+
+export interface VectorExportDecision {
+  readonly allow: boolean;
+  /** Why it was refused — empty when allowed. */
+  readonly reason: string;
+  /** What the caller should pass to proceed deliberately. */
+  readonly optInHint: string;
+}
+
+/**
+ * Whether `dz vector export` may write a checkpoint.
+ *
+ * EXTRACTED SO IT CAN BE TESTED. The decision used to live inline in the CLI behind an
+ * earlier `return` (the RVF engine is opt-in and absent on most machines), so the branch
+ * that matters could not be exercised at all in a normal checkout — I could reason about
+ * it and not run it, which is the position this project treats as unverified.
+ *
+ * The rule: a `.rvf` checkpoint carries embeddings keyed by id and NO domain, so its
+ * contents cannot be classified from the file. This export is also all-or-nothing — the
+ * adapter copies the store whole. So when such a file exists the answer is REFUSE unless
+ * the caller names what travels; `recall --forget` deletes a lexical record and leaves
+ * its embedding behind, which is exactly why the lexical store cannot stand in for this.
+ */
+export function decideVectorExport(input: {
+  readonly rvfExists: boolean;
+  readonly heldOutLexicalCount: number;
+  readonly heldOutDomains: readonly string[];
+  readonly optedIn: string | undefined;
+}): VectorExportDecision {
+  // "NAMED" means the HELD-OUT domain was named, not that some flag was passed. The
+  // first version accepted any non-empty value, so `--include-domain security` unlocked
+  // an unclassifiable checkpoint — the message said "name what travels" and the code
+  // asked only "did you type something". Worse, the test I wrote alongside it asserted
+  // the same weak condition, so it locked the defect in instead of catching it.
+  const optedKeys = new Set(
+    (input.optedIn ?? '').split(',').map((d) => canonicalDomainKey(d)).filter((d) => d !== ''),
+  );
+  const named = DEFAULT_HELD_OUT_DOMAINS.some((d) => optedKeys.has(canonicalDomainKey(d)));
+  const hint = (input.heldOutDomains.length > 0 ? input.heldOutDomains : DEFAULT_HELD_OUT_DOMAINS).join(',');
+  if (input.rvfExists && !named) {
+    return {
+      allow: false,
+      reason: 'a .rvf checkpoint stores embeddings keyed by id with no domain, so this gate cannot tell whether it holds held-out lessons — and it is exported whole',
+      optInHint: hint,
+    };
+  }
+  if (input.heldOutLexicalCount > 0 && !named) {
+    return {
+      allow: false,
+      reason: `the store holds ${input.heldOutLexicalCount} lesson(s) in ${input.heldOutDomains.join(', ')}, and this export is all-or-nothing`,
+      optInHint: hint,
+    };
+  }
+  return { allow: true, reason: '', optInHint: hint };
+}

package/src/feature-adr-checkpoints.ts

@@ -24,6 +24,10 @@
  * the wiring test asserts the mirror stays present.
  */
 
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
+ * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
+export const BLOB_VERSION = '1.0.0';
+
 /** Stages the workflow checkpoints, in pipeline order. Cheap side-channel agents (usage probes,
  * fa-record, auto-cost selects) are never checkpointed; the opt-in Delivery gate re-runs by design
  * (advisory verdicts should reflect the CURRENT tree). */
@@ -74,7 +78,7 @@ export function fnv1a(str: string): string {
  * findable collisions (Codex QE #9 produced a real pair at `11a08b58`); two passes make the
  * single-pair collision odds ~2^-64 — adequate for one slug's checkpoint file. */
 export function fnv1a64(str: string): string {
-  return fnv1a(str) + fnv1a('
fa-ckpt-salt
' + str);
+  return fnv1a(str) + fnv1a('fa-ckpt-salt' + str);
 }
 
 /** The stage's input fingerprint: a JSON-tuple (delimiter-ambiguity class — never a separator join)
@@ -219,3 +223,190 @@ export function checkpointAppendCmd(fdirAbs: string, line: string): string {
   const file = shellQuote(fdirAbs + '/.fa-state/checkpoints.jsonl');
   return 'mkdir -p ' + dir + " && printf '%s\\n' " + shellQuote(line) + ' >> ' + file;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Training-pair capture (backlog 70e0f083) — the PURE half.
+//
+// Goal: fully-local development on compact models in 4–6 months needs a dataset of
+// STAGE INPUT (full context+prompt) → STAGE OUTPUT (artifact/result) → EVALUATION
+// (QE grade + the lessons injected into context) records. Everything is already in
+// hand at the moment each feature-adr stage completes — so capture is instrumented
+// NOW (every un-captured run is a lost pair); the dataset itself is built later.
+//
+// Storage: ONE JSONL file per stage under .dz/fa-training/<slug>/<stage>.jsonl
+// (owner decision 2026-08). Deliberately NOT gitignored (owner decision — pairs may
+// contain target-repo code; the capture dir carries a README privacy note instead).
+//
+// Stage asymmetry (the reason provenance.family is load-bearing): the downstream
+// dataset must honour the cross-model rule — QE pairs must come from a DIFFERENT
+// family than the coder's pairs; router/plan distill easily, code is hardest.
+//
+// Pure and deterministic like the checkpoint half: ts is PASSED IN (never Date.now()
+// — the workflow sandbox forbids Date, and tests must stay deterministic); the
+// workflow mirrors these functions inline and fills ts shell-side via sed.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Training-pair record format version. Bump on any field-shape change. */
+export const TRAINPAIR_SCHEMA_VERSION = 'fa-trainpair-1';
+
+/** Oversize guard cap over input+output combined (same posture as
+ * CHECKPOINT_MAX_RESULT_CHARS, sized for full stage prompts): an over-cap pair is
+ * TRUNCATED with a named marker + a hash of the full text — never silently dropped
+ * (a lost pair is a lost training sample), never unbounded (a 10MB line would make
+ * the JSONL unusable and the write-agent prompt explode). */
+export const TRAINPAIR_MAX_IO_CHARS = 48_000;
+
+export type TrainingPairFamily = 'claude' | 'codex';
+
+/** The family a model spec/label/runner-name belongs to. Family ∈ {claude, codex} —
+ * the field the cross-model dataset rule stands on. Anything naming codex/gpt/openai
+ * is 'codex' (incl. 'codex-fallback' — codex ACTUALLY produced that stage); everything
+ * else (opus/sonnet/fable/haiku, role agentTypes, 'claude-fallback') is 'claude'. */
+export function trainingPairFamily(spec: unknown): TrainingPairFamily {
+  return /codex|gpt|openai/i.test(String(spec ?? '')) ? 'codex' : 'claude';
+}
+
+export interface TrainingPairEvaluation {
+  /** The QE grade for this pair, or null when the stage honestly has none (router). */
+  grade: string | null;
+  /** Who graded it (runner + model label), or null when ungraded. */
+  gradedBy: string | null;
+  /** Lesson texts/ids recalled into THIS stage's context (Step-0 recall). */
+  lessonsInjected: string[];
+}
+
+export interface TrainingPairProvenance {
+  /** The model label that produced the stage output. */
+  model: string;
+  /** The model FAMILY — load-bearing for the cross-model dataset rule. */
+  family: TrainingPairFamily;
+  /** The stage role: 'router' | 'design:*' | 'planner' | 'coder' | 'reviewer' | 'fleet-qe'. */
+  role: string;
+  tokens: number | null;
+  minutes: number | null;
+}
+
+export interface TrainingPairTruncation {
+  /** Original (pre-truncation) char counts + full-text hashes — what was cut is NAMED. */
+  inputChars: number;
+  outputChars: number;
+  inputHash: string;
+  outputHash: string;
+}
+
+/** One SFT-ready record: prompt → completion → evaluation, one JSON object per line. */
+export interface TrainingPair {
+  schema: string;
+  slug: string;
+  stage: string;
+  ts: number | string | null;
+  input: string;
+  output: string;
+  evaluation: TrainingPairEvaluation;
+  provenance: TrainingPairProvenance;
+  truncated: TrainingPairTruncation | null;
+}
+
+/** Per-stage JSONL path, relative to the repo root. ONE file per stage. */
+export function trainingPairPath(slug: string, stage: string): string {
+  return '.dz/fa-training/' + slug + '/' + stage + '.jsonl';
+}
+
+/** README dropped once into the capture dir. The caveat is documented ON DISK because the
+ * directory is deliberately not gitignored (explicit owner decision, 2026-08). */
+export const TRAINPAIR_PRIVACY_NOTE =
+  'feature-adr TRAINING PAIRS (backlog 70e0f083): per-stage SFT records - STAGE INPUT (full prompt/context) -> STAGE OUTPUT (artifact/result) -> EVALUATION (QE grade + injected lessons) with model+family provenance; one JSONL file per stage per slug. PRIVACY: pairs may contain TARGET-REPO CODE and full prompts. This directory is NOT gitignored yet by explicit owner decision - review contents before sharing or publishing anything that embeds it.';
+
+/** Coerce a stage input/output to text: strings pass through; objects serialize to JSON;
+ * an unserializable value degrades to String(v) — buildTrainingPair NEVER throws (capture
+ * is non-blocking by contract). */
+function coerceText(v: unknown): string {
+  if (typeof v === 'string') return v;
+  if (v === null || v === undefined) return '';
+  try {
+    const s = JSON.stringify(v);
+    return typeof s === 'string' ? s : String(v);
+  } catch {
+    return String(v);
+  }
+}
+
+/** Assemble one SFT-ready training pair. Deterministic (ts passed in). Applies the oversize
+ * guard: when input+output exceed TRAINPAIR_MAX_IO_CHARS combined, each over-budget side is
+ * truncated with a marker naming the cut char count + the fnv1a64 of its FULL text (the
+ * budget flows to the smaller side, so a small prompt next to a huge output stays verbatim).
+ * Evaluation honesty: an empty/whitespace grade normalizes to null — a stub never reads as
+ * a real evaluation. Provenance: an explicit valid family wins; otherwise it is DERIVED from
+ * the model spec via modelFamily (an invalid family never leaks into the dataset). */
+export function buildTrainingPair(opts: {
+  slug: string;
+  stage: string;
+  ts: number | string | null;
+  input: unknown;
+  output: unknown;
+  evaluation?: Partial<TrainingPairEvaluation> | null;
+  provenance?: Partial<TrainingPairProvenance> | null;
+}): TrainingPair {
+  let input = coerceText(opts.input);
+  let output = coerceText(opts.output);
+  let truncated: TrainingPairTruncation | null = null;
+  if (input.length + output.length > TRAINPAIR_MAX_IO_CHARS) {
+    truncated = { inputChars: input.length, outputChars: output.length, inputHash: fnv1a64(input), outputHash: fnv1a64(output) };
+    const half = Math.floor(TRAINPAIR_MAX_IO_CHARS / 2);
+    let inKeep = input.length;
+    let outKeep = output.length;
+    if (outKeep <= half) inKeep = TRAINPAIR_MAX_IO_CHARS - outKeep;
+    else if (inKeep <= half) outKeep = TRAINPAIR_MAX_IO_CHARS - inKeep;
+    else { inKeep = half; outKeep = TRAINPAIR_MAX_IO_CHARS - half; }
+    if (inKeep < input.length) input = input.slice(0, inKeep) + '\n…[TRUNCATED ' + (truncated.inputChars - inKeep) + ' chars — full-text fnv1a64=' + truncated.inputHash + ']';
+    if (outKeep < output.length) output = output.slice(0, outKeep) + '\n…[TRUNCATED ' + (truncated.outputChars - outKeep) + ' chars — full-text fnv1a64=' + truncated.outputHash + ']';
+  }
+  const ev = opts.evaluation || {};
+  const pv = opts.provenance || {};
+  return {
+    schema: TRAINPAIR_SCHEMA_VERSION,
+    slug: opts.slug,
+    stage: opts.stage,
+    ts: opts.ts === undefined ? null : opts.ts,
+    input,
+    output,
+    evaluation: {
+      grade: typeof ev.grade === 'string' && ev.grade.trim() !== '' ? ev.grade : null,
+      gradedBy: typeof ev.gradedBy === 'string' && ev.gradedBy !== '' ? ev.gradedBy : null,
+      lessonsInjected: Array.isArray(ev.lessonsInjected) ? ev.lessonsInjected.filter((s): s is string => typeof s === 'string' && s !== '') : [],
+    },
+    provenance: {
+      model: typeof pv.model === 'string' && pv.model !== '' ? pv.model : 'unknown',
+      family: pv.family === 'claude' || pv.family === 'codex' ? pv.family : trainingPairFamily(pv.model),
+      role: typeof pv.role === 'string' && pv.role !== '' ? pv.role : 'unknown',
+      tokens: typeof pv.tokens === 'number' && Number.isFinite(pv.tokens) ? pv.tokens : null,
+      minutes: typeof pv.minutes === 'number' && Number.isFinite(pv.minutes) ? pv.minutes : null,
+    },
+    truncated,
+  };
+}
+
+/** Serialize one training pair to a JSONL line. The oversize guard already bounds the pair,
+ * so this only fails on the impossible (all fields are plain data) — null on that, never a throw. */
+export function serializeTrainingPair(pair: TrainingPair): string | null {
+  try {
+    const line = JSON.stringify(pair);
+    return typeof line === 'string' ? line : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The one Bash command the write agent runs: mkdir the slug dir, drop the privacy README
+ * once (if-absent guard), then append ONE line (single-quote-escaped byte-faithfully, same
+ * idiom as checkpointAppendCmd). */
+export function trainingPairAppendCmd(repoAbs: string, slug: string, stage: string, line: string): string {
+  const dirAbs = repoAbs + '/.dz/fa-training/' + slug;
+  const readmeAbs = repoAbs + '/.dz/fa-training/README.md';
+  const fileAbs = dirAbs + '/' + stage + '.jsonl';
+  return (
+    'mkdir -p ' + shellQuote(dirAbs) +
+    ' && { [ -f ' + shellQuote(readmeAbs) + ' ] || printf \'%s\\n\' ' + shellQuote(TRAINPAIR_PRIVACY_NOTE) + ' > ' + shellQuote(readmeAbs) + '; }' +
+    " && printf '%s\\n' " + shellQuote(line) + ' >> ' + shellQuote(fileAbs)
+  );
+}

package/src/feature-adr-routing.ts

@@ -27,6 +27,10 @@
  * @packageDocumentation
  */
 
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs (feature loop-designer, ADR-004) — the
+ * ONLY loop-designer change to this canonical file; bump when any blob-exported semantic changes. */
+export const BLOB_VERSION = '1.0.0';
+
 /** A resolved `agent()` opts fragment: either a Claude `{model}` or a codex spec. */
 export interface StageOpts {
   readonly model?: string;

package/src/guard.ts

@@ -12,6 +12,7 @@
 // counts, store size) that the CLI gathers. No filesystem here → deterministic + unit-testable without a repo.
 
 import { type RuleTemplate, type TemplateParams, type ChangeSet, templateFires, validTemplateParams } from './guard-promotion.js';
+import { STUB_MARKERS, STUB_PHRASES, checkNoStubs, type StubWaiver } from './no-stubs.js';
 
 export type GuardSeverity = 'hard' | 'soft';
 export type GuardOp = 'publish' | 'teach' | 'consolidate' | 'reindex';
@@ -46,6 +47,13 @@ export interface GuardResult {
   readonly violations: readonly Violation[];
   /** ids of the rules that ran for this op (so a report can show what was checked, not just what failed). */
   readonly checked: readonly string[];
+  /**
+   * Informational notes (FN-7): things a rule wants ON THE RECORD that are NOT violations and never
+   * touch the verdict — e.g. "no-stubs: N changed scannable file(s) not scanned". A fail-open skip
+   * that leaves no trace is fail-SILENT, the worst kind by the gate's own cost-of-detection
+   * argument; a note is the cheap fix. Present only when non-empty.
+   */
+  readonly notes?: readonly string[];
 }
 
 /** Facts the CLI injects; each rule reads only the fields it needs. Missing evidence ⇒ that rule is skipped. */
@@ -79,7 +87,37 @@ export interface GuardFacts {
   readonly change?: {
     readonly files: readonly string[];
     readonly contents?: Readonly<Record<string, string>>;
+    /**
+     * FN-7: how many changed STUB-SCANNABLE files the gatherer did NOT read (deleted, non-regular,
+     * oversize, read error, or beyond the file cap). The no-stubs scan stays fail-open on each of
+     * them — but the skip must be ON THE RECORD (a GuardResult note), never silent.
+     */
+    readonly stubSkipped?: number;
   };
+  /**
+   * for no-stubs: config waivers from `.dz/guard.json` `stubWaivers: [{path, reason}]` — path-keyed,
+   * reason MANDATORY (the feature-adr-setup --guards shape). The scan itself reads `change.files` +
+   * `change.contents`, the SAME working-tree diff every other diff-aware rule uses.
+   */
+  readonly stubWaivers?: readonly StubWaiver[];
+  /**
+   * for licence-hold: per package that DECLARES a licence hold (package.json `licenseHold` field —
+   * ADR-001 of feature hermes-claude-adaptation), the raw evidence the checker needs. The checker
+   * fires only for packs that are actually publishable (`privateFlag !== true`): while `private:true`
+   * the npm layer itself refuses, and blocking every unrelated publish for a parked pack would train
+   * the --no-guard habit. The moment `private` is dropped without the hold being satisfied, this rule
+   * HARD-blocks publish.
+   */
+  readonly licenceHold?: readonly {
+    readonly name: string;
+    readonly privateFlag: boolean;
+    /** LICENSE file text; null ⇒ absent. */
+    readonly licenseText: string | null;
+    /** THIRD_PARTY_NOTICES(.md) text; null ⇒ absent. */
+    readonly noticesText: string | null;
+    /** package.json `license` field. */
+    readonly licenseField: string | null;
+  }[];
   readonly lockfile?: {
     readonly parsed: boolean;
     readonly importers?: readonly {
@@ -191,8 +229,15 @@ export const DEFAULT_RULES: readonly GuardRule[] = [
   { id: 'readme-first', severity: 'soft', ops: ['publish'], description: 'a package with a staged version bump must update its own README.md in the same change (README-first)' },
   { id: 'lockfile-in-sync', severity: 'soft', ops: ['publish'], description: 'every workspace @dzhechkov/* dependency spec matches the specifier pnpm-lock.yaml records for that importer (a dep bump without a lockfile refresh breaks CI with ERR_PNPM_OUTDATED_LOCKFILE). SOFT-ONLY — a config cannot promote it to HARD' },
   { id: 'store-bloat-cap', severity: 'soft', ops: ['teach', 'consolidate'], description: 'the learned store is within its size cap' },
+  // Description ASSEMBLED from STUB_MARKERS so guard.ts itself stays clean under the scan it defines
+  // (structural self-exemption — tested in no-stubs.test.ts).
+  { id: 'no-stubs', severity: 'soft', ops: ['publish'], description: `an unfinished-stub marker (${STUB_MARKERS.join('/')} / "${STUB_PHRASES.join('", "')}") left in a CHANGED file — any unwaived match means the change ships incomplete; waive per line with "no-stubs: <reason>" or per path in .dz/guard.json stubWaivers (reason MANDATORY)` },
+  { id: 'licence-hold', severity: 'hard', ops: ['publish'], description: 'a pack that declares a licence hold (package.json.licenseHold — ADR-001 hermes-claude-adaptation) must not become publishable until the hold is satisfied: LICENSE present without the PENDING grant placeholder, a Grant-Confirmation URL, non-empty THIRD_PARTY_NOTICES, and a clean SPDX license field' },
 ];
 
+/** The exact placeholder LICENSE marker the licence-hold rule looks for (shared with pack tests). */
+export const LICENCE_HOLD_PENDING_MARKER = '<!-- PENDING:';
+
 /**
  * Secret patterns — high-signal, low-false-positive. Each is anchored to a real credential shape, so ordinary
  * prose does not trip it. Extend deliberately (a broad `[A-Za-z0-9]{32}` would flag every hash).
@@ -317,6 +362,53 @@ const CHECKERS: Record<string, (f: GuardFacts, sev: GuardSeverity) => Violation[
     if (!s || !Number.isFinite(s.count) || !Number.isFinite(s.cap) || s.cap <= 0) return [];
     return s.count <= s.cap ? [] : [{ rule: 'store-bloat-cap', severity: sev, detail: `learned store has ${s.count} patterns, over the cap of ${s.cap} — run dz consolidate --prune-noise` }];
   },
+  'no-stubs': (f, sev) => {
+    // Backlog 0b403a0106103901 (Karpathy-Michaels rule XI), layer-1 on the cost-of-detection ladder:
+    // a stub marker left in a file of THIS change-set means the task shipped incomplete. SCOPE is the
+    // change-set on purpose (MEASURED: a whole-tree scan is ~78% ancient-marker noise and would be
+    // switched off within a day). SOFT: it warns — an unfinished stub is a fact worth a record, but a
+    // publish of an unrelated package must not be blocked by it. Fail-open on missing evidence: no
+    // `change` fact, or a changed file whose contents were not gathered, reports nothing.
+    const ch = f.change;
+    if (!ch || typeof ch !== 'object' || !Array.isArray(ch.files)) return [];
+    return checkNoStubs(ch.files, ch.contents, f.stubWaivers).map((s) => ({
+      rule: 'no-stubs',
+      severity: sev,
+      detail: s.kind === 'marker'
+        ? `${s.path}:${s.line}: stub marker "${s.detail}" in a changed file — finish it, or waive the line with "no-stubs: <reason>" (or .dz/guard.json stubWaivers with a reason)`
+        : `${s.path}${s.line > 0 ? ':' + s.line : ''}: ${s.detail}`,
+    }));
+  },
+  'licence-hold': (f, sev) => {
+    // ADR-001 (hermes-claude-adaptation), machine-armed: a pack parked behind a licence hold carries
+    // `private:true` (the npm layer refuses it) + a `licenseHold` trigger field. THIS rule is the second
+    // belt — it fires the moment the pack becomes PUBLISHABLE (private dropped) while the hold is still
+    // unsatisfied, and refuses `dz publish` HARD. Clearing the hold means: real LICENSE (no PENDING
+    // placeholder, a Grant-Confirmation URL), non-empty THIRD_PARTY_NOTICES, and a clean SPDX id in
+    // package.json.license. The trigger field itself stays — a satisfied hold passes with it in place.
+    const out: Violation[] = [];
+    for (const p of f.licenceHold ?? []) {
+      if (!p || typeof p.name !== 'string') continue;
+      if (p.privateFlag === true) continue; // npm refuses it; other packs' publishes stay unblocked
+      const problems: string[] = [];
+      const lic = (p.licenseText ?? '').trim();
+      const notices = (p.noticesText ?? '').trim();
+      if (lic.length < 40) problems.push('LICENSE missing or empty');
+      else {
+        if (lic.includes(LICENCE_HOLD_PENDING_MARKER)) problems.push('LICENSE still carries the PENDING grant placeholder');
+        if (!/Grant-Confirmation:\s*https?:\/\/\S+/.test(lic)) problems.push('LICENSE has no "Grant-Confirmation: <url>" line');
+      }
+      if (notices.length < 40) problems.push('THIRD_PARTY_NOTICES missing or empty');
+      const field = (p.licenseField ?? '').trim();
+      if (!/^[A-Za-z0-9][A-Za-z0-9.+-]*(\s+(AND|OR|WITH)\s+[A-Za-z0-9][A-Za-z0-9.+-]*)*$/.test(field) || /^UNLICENSED$/i.test(field)) {
+        problems.push(`package.json license "${field}" is not a clean SPDX id`);
+      }
+      if (problems.length > 0) {
+        out.push({ rule: 'licence-hold', severity: sev, detail: `${p.name}: publishable (private flag removed) but the ADR-001 licence hold is UNSATISFIED — ${problems.join('; ')}` });
+      }
+    }
+    return out;
+  },
 };
 
 /**
@@ -431,7 +523,17 @@ export function evaluateGuard(facts: GuardFacts, rules: readonly GuardRule[] = D
     }
   }
   const verdict: GuardVerdict = violations.some((v) => v.severity === 'hard') ? 'block' : violations.length > 0 ? 'warn' : 'pass';
-  return { op, verdict, violations, checked };
+  // FN-7 — the fail-open skips go ON THE RECORD. The no-stubs scan is fail-open by contract
+  // (missing contents ⇒ nothing reported), but a skip nobody can see is fail-SILENT. One aggregate
+  // note, computed AFTER the verdict so it can never block or warn: information, not a violation.
+  const notes: string[] = [];
+  if (checked.includes('no-stubs')) {
+    const skipped = facts.change?.stubSkipped;
+    if (typeof skipped === 'number' && Number.isFinite(skipped) && skipped > 0) {
+      notes.push(`no-stubs: ${skipped} changed scannable file(s) not scanned (deleted/oversize/unreadable/beyond the file cap) — the stub scan is fail-open, so this is a coverage gap on the record, not a violation`);
+    }
+  }
+  return { op, verdict, violations, checked, ...(notes.length > 0 ? { notes } : {}) };
 }
 
 /** An append-only audit record. `ts` is injected by the caller (no wall-clock here → deterministic tests). */
@@ -440,6 +542,8 @@ export interface GuardAuditRecord {
   readonly op: GuardOp;
   readonly verdict: GuardVerdict;
   readonly violations: readonly Violation[];
+  /** informational notes (FN-7 — e.g. the no-stubs skipped-files note); on the record, never a verdict input. */
+  readonly notes?: readonly string[];
   /** set when the operator overrode a block with `--force <reason>` — the override is logged, never silent. */
   readonly override?: { readonly forced: true; readonly reason: string };
 }
@@ -451,6 +555,7 @@ export function auditRecord(result: GuardResult, ts: string, override?: { reason
     op: result.op,
     verdict: result.verdict,
     violations: result.violations,
+    ...(Array.isArray(result.notes) && result.notes.length > 0 ? { notes: result.notes } : {}),
     ...(override && typeof override.reason === 'string' ? { override: { forced: true, reason: override.reason } } : {}),
   };
 }