@chrono-meta/fh-gate 1.4.51 → 1.4.53

package/bin/fh-codex-doctor.js

@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function usage() {
+  process.stdout.write(`Usage:
+  fh-codex-doctor [--root <path>] [--json] [--strict]
+
+Scans FH skills and agents for Codex runtime compatibility drift.
+
+Options:
+  --root <path>  Repository/package root. Defaults to cwd when it looks like FH,
+                 otherwise this package root.
+  --json         Emit machine-readable JSON.
+  --strict       Exit 1 when high-severity drift is found.
+  --help         Show this help.
+`);
+}
+
+function parseArgs(argv) {
+  const out = { root: defaultRoot(), json: false, strict: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      out.help = true;
+    } else if (arg === '--json') {
+      out.json = true;
+    } else if (arg === '--strict') {
+      out.strict = true;
+    } else if (arg === '--root') {
+      i += 1;
+      if (!argv[i]) throw new Error('--root requires a path');
+      out.root = path.resolve(argv[i]);
+    } else {
+      throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  return out;
+}
+
+function looksLikeFHRoot(dir) {
+  return exists(path.join(dir, 'package.json')) &&
+    exists(path.join(dir, 'plugins')) &&
+    exists(path.join(dir, 'AGENTS.md'));
+}
+
+function defaultRoot() {
+  const cwd = process.cwd();
+  if (looksLikeFHRoot(cwd)) return cwd;
+  return path.resolve(__dirname, '..');
+}
+
+function readText(file) {
+  return fs.readFileSync(file, 'utf8');
+}
+
+function maybeReadText(file) {
+  try {
+    return readText(file);
+  } catch (_err) {
+    return '';
+  }
+}
+
+function exists(file) {
+  try {
+    fs.accessSync(file, fs.constants.F_OK);
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+function walk(dir, predicate) {
+  const results = [];
+  if (!exists(dir)) return results;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walk(p, predicate));
+    } else if (!predicate || predicate(p)) {
+      results.push(p);
+    }
+  }
+  return results;
+}
+
+function rel(root, file) {
+  return path.relative(root, file).split(path.sep).join('/');
+}
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return {};
+  const end = text.indexOf('\n---', 4);
+  if (end === -1) return {};
+  const block = text.slice(4, end).split('\n');
+  const out = {};
+  for (const line of block) {
+    const m = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!m) continue;
+    out[m[1]] = m[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+
+function extractBacktickNames(line) {
+  const names = [];
+  const re = /`([^`]+)`/g;
+  let m;
+  while ((m = re.exec(line)) !== null) {
+    const value = m[1].trim();
+    if (/^[a-z0-9][a-z0-9-]*$/.test(value)) names.push(value);
+  }
+  return names;
+}
+
+function documentedTiers(root) {
+  const sources = [
+    path.join(root, 'AGENTS.md'),
+  ];
+  const tiers = new Map();
+  const evidence = [];
+  for (const source of sources) {
+    const text = maybeReadText(source);
+    if (!text) continue;
+    const lines = text.split('\n');
+    lines.forEach((line, index) => {
+      const tierMatch = line.match(/\|\s*\*\*(M[123])\b/);
+      if (!tierMatch) return;
+      const tier = tierMatch[1];
+      for (const name of extractBacktickNames(line)) {
+        tiers.set(name, { tier, source: rel(root, source), line: index + 1 });
+        evidence.push({ name, tier, source: rel(root, source), line: index + 1 });
+      }
+    });
+  }
+  return { tiers, evidence };
+}
+
+function compatDocTierMentions(root, skillNames) {
+  const source = path.join(root, 'docs', 'codex-compat.md');
+  const text = maybeReadText(source);
+  const mentions = new Map();
+  if (!text) return mentions;
+  const lines = text.split('\n');
+  lines.forEach((line, index) => {
+    const tierMatch = line.match(/\b(M[123])\b/);
+    if (!tierMatch) return;
+    const tier = tierMatch[1];
+    for (const name of extractBacktickNames(line)) {
+      if (!skillNames.has(name)) continue;
+      if (!mentions.has(name)) mentions.set(name, []);
+      mentions.get(name).push({ tier, source: rel(root, source), line: index + 1 });
+    }
+  });
+  return mentions;
+}
+
+const PRIMITIVES = [
+  {
+    id: 'agent-dispatch',
+    severity: 'adapter',
+    regexes: [/Agent\s*\(/, /\bsubagent_type\b/, /\bAgent View\b/, /\bAgent\b tool\b/, /\bAgent invocation instruction\b/, /\bparallel-Agent dispatch\b/],
+  },
+  {
+    id: 'slash-command',
+    severity: 'adapter',
+    regexes: [/(^|[\s`])\/[a-z][a-z0-9-]+(?=($|[\s`),.;:}]))/m],
+  },
+  {
+    id: 'hook',
+    severity: 'claude-native',
+    regexes: [/\bStop hook\b/i, /\bPostToolUse\b/, /\bSessionStart\b/],
+  },
+  {
+    id: 'model-command',
+    severity: 'claude-native',
+    regexes: [/(^|[\s`])\/model\b/m],
+  },
+];
+
+function scanPrimitives(text) {
+  const hits = [];
+  for (const primitive of PRIMITIVES) {
+    for (const regex of primitive.regexes) {
+      const m = regex.exec(text);
+      if (!m) continue;
+      hits.push({
+        id: primitive.id,
+        severity: primitive.severity,
+        line: text.slice(0, m.index).split('\n').length,
+        match: m[0].trim(),
+      });
+      break;
+    }
+  }
+  return hits;
+}
+
+function classify(docTier, primitives) {
+  const hasClaudeNative = primitives.some((p) => p.severity === 'claude-native');
+  const hasAgentDispatch = primitives.some((p) => p.id === 'agent-dispatch');
+  const hasAdapter = primitives.some((p) => p.severity === 'adapter');
+  if (docTier === 'M1' && (hasClaudeNative || hasAgentDispatch)) return 'tier-drift';
+  if (docTier === 'M1') return 'codex-native';
+  if (docTier === 'M2') return 'adapter-required';
+  if (docTier === 'M3') return 'claude-native';
+  if (hasClaudeNative) return 'claude-native-unclassified';
+  if (hasAdapter) return 'adapter-required-unclassified';
+  return 'codex-native-candidate';
+}
+
+function collectSkills(root) {
+  const skillsRoot = path.join(root, 'plugins');
+  const files = walk(skillsRoot, (p) => path.basename(p) === 'SKILL.md');
+  return files.sort().map((file) => {
+    const text = readText(file);
+    const fm = parseFrontmatter(text);
+    const skillName = fm.name || path.basename(path.dirname(file));
+    return {
+      type: 'skill',
+      name: skillName,
+      path: rel(root, file),
+      frontmatter: fm,
+      primitives: scanPrimitives(text),
+    };
+  });
+}
+
+function collectAgents(root) {
+  const agents = [];
+  for (const plugin of ['fh-meta', 'fh-commons']) {
+    const dir = path.join(root, 'plugins', plugin, 'agents');
+    for (const file of walk(dir, (p) => p.endsWith('.md')).sort()) {
+      const text = readText(file);
+      agents.push({
+        type: 'agent',
+        name: path.basename(file, '.md'),
+        path: rel(root, file),
+        plugin,
+        primitives: scanPrimitives(text),
+      });
+    }
+  }
+  return agents;
+}
+
+function loadAgentCards(root) {
+  const file = path.join(root, '.claude', 'registry', 'agent_cards.json');
+  if (!exists(file)) return { present: false, count: 0 };
+  try {
+    const parsed = JSON.parse(readText(file));
+    const count = Array.isArray(parsed)
+      ? parsed.length
+      : (Array.isArray(parsed.agents) ? parsed.agents.length : (parsed.agent_count || Object.keys(parsed).length));
+    return { present: true, path: rel(root, file), count };
+  } catch (err) {
+    return { present: true, path: rel(root, file), error: err.message, count: 0 };
+  }
+}
+
+function buildReport(root) {
+  const docs = documentedTiers(root);
+  const skills = collectSkills(root).map((skill) => {
+    const doc = docs.tiers.get(skill.name);
+    return {
+      ...skill,
+      documentedTier: doc ? doc.tier : null,
+      tierEvidence: doc || null,
+      codexMode: classify(doc && doc.tier, skill.primitives),
+    };
+  });
+  const agents = collectAgents(root);
+  const skillNames = new Set(skills.map((s) => s.name));
+  const compatMentions = compatDocTierMentions(root, skillNames);
+  const findings = [];
+
+  for (const item of skills) {
+    if (item.documentedTier === 'M1') {
+      const bad = item.primitives.filter((p) => p.severity === 'claude-native' || p.id === 'agent-dispatch');
+      if (bad.length > 0) {
+        findings.push({
+          severity: 'HIGH',
+          code: 'M1_HAS_CLAUDE_NATIVE_PRIMITIVE',
+          path: item.path,
+          message: `${item.name} is documented M1 but contains ${bad.map((p) => p.id).join(', ')}`,
+        });
+      }
+    }
+  }
+
+  for (const entry of docs.evidence) {
+    if (!skillNames.has(entry.name)) {
+      findings.push({
+        severity: 'WARN',
+        code: 'DOC_TIER_REFERENCES_MISSING_SKILL',
+        path: `${entry.source}:${entry.line}`,
+        message: `${entry.name} is listed as ${entry.tier} but no matching SKILL.md was found`,
+      });
+    }
+  }
+
+  for (const item of skills) {
+    const mentions = compatMentions.get(item.name) || [];
+    for (const mention of mentions) {
+      if (item.documentedTier && mention.tier !== item.documentedTier) {
+        findings.push({
+          severity: 'HIGH',
+          code: 'CODEX_COMPAT_TIER_DISAGREES_WITH_AGENTS',
+          path: `${mention.source}:${mention.line}`,
+          message: `${item.name} is ${item.documentedTier} in AGENTS.md but ${mention.tier} in docs/codex-compat.md`,
+        });
+      }
+    }
+  }
+
+  const counts = {
+    skills: skills.length,
+    agents: agents.length,
+    modes: {},
+    tiers: { M1: 0, M2: 0, M3: 0, unclassified: 0 },
+    findings: {
+      HIGH: findings.filter((f) => f.severity === 'HIGH').length,
+      WARN: findings.filter((f) => f.severity === 'WARN').length,
+    },
+  };
+  for (const skill of skills) {
+    counts.modes[skill.codexMode] = (counts.modes[skill.codexMode] || 0) + 1;
+    counts.tiers[skill.documentedTier || 'unclassified'] += 1;
+  }
+
+  return {
+    status: findings.some((f) => f.severity === 'HIGH') ? 'DRIFT' : 'OK',
+    root,
+    counts,
+    agentCards: loadAgentCards(root),
+    findings,
+    skills,
+    agents: agents.map((agent) => ({
+      name: agent.name,
+      path: agent.path,
+      plugin: agent.plugin,
+      codexMode: 'adapter-runnable',
+      note: 'Agents are runnable via fh-run --agent or a runtime-specific dispatch adapter; auto-dispatch is host-specific.',
+    })),
+  };
+}
+
+function printText(report) {
+  const lines = [];
+  lines.push('FH Codex Doctor');
+  lines.push(`Status: ${report.status}`);
+  lines.push(`Root: ${report.root}`);
+  lines.push('');
+  lines.push('Summary');
+  lines.push(`- Skills scanned: ${report.counts.skills}`);
+  lines.push(`- Agents scanned: ${report.counts.agents}`);
+  lines.push(`- Documented tiers: M1=${report.counts.tiers.M1} M2=${report.counts.tiers.M2} M3=${report.counts.tiers.M3} unclassified=${report.counts.tiers.unclassified}`);
+  lines.push(`- Codex modes: ${Object.keys(report.counts.modes).sort().map((k) => `${k}=${report.counts.modes[k]}`).join(' ')}`);
+  if (report.agentCards.present) {
+    lines.push(`- Agent cards: ${report.agentCards.count}${report.agentCards.error ? ` (parse error: ${report.agentCards.error})` : ''}`);
+  } else {
+    lines.push('- Agent cards: missing');
+  }
+  lines.push('');
+  lines.push('Findings');
+  if (report.findings.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const finding of report.findings) {
+      lines.push(`- ${finding.severity} ${finding.code} ${finding.path} :: ${finding.message}`);
+    }
+  }
+  lines.push('');
+  lines.push('Codex Runtime Contract');
+  lines.push('- codex-native: run directly with fh-run/codex exec.');
+  lines.push('- adapter-required: core method can run, but Agent/slash steps need adapter substitution.');
+  lines.push('- claude-native: do not auto-pass; require Claude Code host or explicit dedicated adapter.');
+  lines.push('- unclassified modes are drift signals for future manifest backfill.');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`ERROR: ${err.message}\n`);
+    usage();
+    process.exit(11);
+  }
+  if (args.help) {
+    usage();
+    return;
+  }
+  const root = args.root;
+  if (!exists(path.join(root, 'package.json'))) {
+    process.stderr.write(`ERROR: root does not look like a package/repo root: ${root}\n`);
+    process.exit(11);
+  }
+  if (!looksLikeFHRoot(root)) {
+    process.stderr.write(`ERROR: root is missing required FH surfaces (AGENTS.md and plugins/): ${root}\n`);
+    process.exit(11);
+  }
+  const report = buildReport(root);
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  } else {
+    printText(report);
+  }
+  if (args.strict && report.counts.findings.HIGH > 0) {
+    process.exit(1);
+  }
+}
+
+main();

package/docs/codex-compat.md

@@ -2,7 +2,7 @@
 
 > Status: **beta**. This document is beta-removal condition #2 (see `AGENTS.md` → Codex Compatibility → Beta removal conditions). It lists what works, what breaks, and what to expect when applying forge-harness (FH) methodology through OpenAI Codex (`codex exec`) instead of Claude Code.
 
-FH is a 2-layer system: a **methodology layer** (`tracks/`, `knowledge/`, `SKILL.md` docs) that is model-agnostic, and an **automation layer** (Claude Code hooks, `.claude/agents/`, `/model`, settings.json) that is Claude-native. Codex users run the methodology layer by reading `SKILL.md` files directly; automation steps either run through runtime adapters (`fh-gate`, `fh-run`) or require manual substitution.
+FH is a 2-layer system: a **methodology layer** (`tracks/`, `knowledge/`, `SKILL.md` docs) that is model-agnostic, and an **automation layer** (Claude Code hooks, plugin-channel agents under `plugins/*/agents/`, field-project overrides under `.claude/agents/`, `/model`, settings.json) that is Claude-native. Codex users run the methodology layer by reading `SKILL.md` files directly; automation steps either run through runtime adapters (`fh-gate`, `fh-run`) or require manual substitution.
 
 ## Validated invocation pattern
 
@@ -65,6 +65,20 @@ Resolution order:
 | `--agent plugin:name` | `plugins/plugin/agents/name.md` first |
 | `--unit path` | explicit file path |
 
+### `fh-codex-doctor`
+
+`fh-codex-doctor` is the drift detector for the thin Codex adapter boundary. It reads the canonical
+FH skill/agent files plus the documented M1/M2/M3 tier table, then reports which surfaces are
+Codex-native, adapter-required, Claude-native, or unclassified:
+
+```bash
+npx --package @chrono-meta/fh-gate fh-codex-doctor --strict
+```
+
+Use it before promoting a new Codex automation path. Unknown Claude-native primitives fail closed as
+"manual adaptation required" instead of being treated as compatible by default. When run from an FH
+checkout it scans the current working tree; outside a checkout it scans the installed package.
+
 ### `fh-goal`
 
 Codex has native goal/session features. Use those directly when they fit. `fh-goal` is not a replacement for Codex goal; it is a non-interactive wrapper for "run backend task, then run FH governance on changed files":
@@ -92,7 +106,7 @@ Both ran end-to-end with no Claude-native dependency. The M1 tier claim holds fo
 When `codex exec` runs **inside this repo**, FH's Claude-native git/Stop/PostToolUse hooks attempt to fire and emit `hook: Stop Failed` / `hook: PostToolUse Failed` lines interleaved with output. These are **harmless to the skill result** — the skill's verdict is produced correctly — but they are visible noise. Running from a directory **without** FH's `.claude/settings.json` (the normal Codex-user case) avoids them entirely. Filter with `grep -vE "^hook:"` if needed.
 
 ### 2. M2 skills need manual agent substitution
-M2 skills (`steel-quench`, `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop`) have a core workflow that runs under Codex, but any step that dispatches `Agent(subagent_type=...)` or a slash command must be replaced by `fh-run` or a direct `codex exec` call reading the sub-agent's `SKILL.md`/agent `.md` — same workflow, different runtime (the "M2 adaptation pattern" in `AGENTS.md`). Example: `steel-quench` Waves 1–3 run; the `quench-challenger` agent step becomes `fh-run --agent fh-commons:quench-challenger`.
+M2 skills (`deliberation`, `steel-quench`, `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop`) have a core workflow that runs under Codex, but any step that dispatches `Agent(subagent_type=...)` or a slash command must be replaced by `fh-run` or a direct `codex exec` call reading the sub-agent's `SKILL.md`/agent `.md` — same workflow, different runtime (the "M2 adaptation pattern" in `AGENTS.md`). Example: `steel-quench` Waves 1–3 run; the `quench-challenger` agent step becomes `fh-run --agent fh-commons:quench-challenger`.
 
 ### 3. M3 skills do not run automatically under Codex
 M3 skills (`goal-quench` Phase-3 Stop hook, `hub-cc-pr-reviewer` CC session context, `install-wizard` settings.json write) require Claude-Code-native runtime and are **methodology reference only** under Codex unless a dedicated adapter exists. Use Codex's native goal/session features for goal control, and use `fh-gate` after completion for FH quality gating.
@@ -107,8 +121,8 @@ The sibling pattern for Gemini is `gemini -p "$(cat <skill+artifact>)"`. Outside
 
 | Tier | Under Codex | Action |
 |---|---|---|
-| **M1** | Runs fully | `cat SKILL.md artifact \| codex exec -m gpt-5.5 -` |
-| **M2** | Core runs; agent/slash steps via adapter | Substitute each dispatch with `fh-run` or a direct `codex exec` on the sub-agent's `.md` |
+| **M1** | Runs fully (`token-budget-gate`, `asset-placement-gate`, `phantom-quench`, `deep-clarify`, `convergence-loop`) | `cat SKILL.md artifact \| codex exec -m gpt-5.5 -` |
+| **M2** | Core runs; agent/slash steps via adapter (`deliberation`, `steel-quench`, `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop`) | Substitute each dispatch with `fh-run` or a direct `codex exec` on the sub-agent's `.md` |
 | **M3** | Does not run automatically | Use native Codex session features where available; otherwise read as methodology reference or use a dedicated adapter |
 
 ## Beta removal — remaining (external-blocked)

package/knowledge/shared/harness-core/capability_escalation_consent.md

@@ -123,3 +123,10 @@ to offload exec cost off the paid API entirely. The protocol turns hard-won econ
   protocol never flips the model itself.
 - **Sonnet floor is a floor, not a ceiling** — declined-floor-up still escalates *within* Sonnet's
   harness depth (sub-agents, good structure); it does not cap capability, only cost/trust surface.
+
+---
+
+> **Canonical axiom cross-ref (2026-07-10)**: the "Sonnet floor is first-class, not degraded" stance
+> this protocol operationalizes is now named — `sonnet_floor_doctrine.md` (base ops 100% Sonnet;
+> tier-gated capability = defect; escalation = dispatch, consent-gated **here**). This file remains
+> the consent mechanics home; the doctrine node does not restate them.

package/knowledge/shared/harness-core/claude_md_gate_details.md

@@ -69,10 +69,13 @@ demand a strict YES/NO + one-line reason, judge whether the rule fired (mechanis
 directions — a claim checkable against that skill — re-validating that day's salience-binding fix at a
 sub-Sonnet tier).
 
-**FAIL-triage**: a FAIL never blocks alone — the opus orchestrator triages it as a *real salience gap* (fix
-the rule) vs a *floor-model quirk* (small-model loop/hallucination, per the public "Local AI is not Opus"
-finding + the cheap-oracle ceiling — a small model adds nothing where one grep already settles the check).
-The terminal verdict stays with the frontier (Sonnet sim + opus judge) — no judge-only path, no
+**FAIL-triage**: a FAIL never blocks alone — the orchestrator (whatever tier is driving; the triage
+judgment is *trusted* at opus+ and run-or-ask below, per §Floor governance) triages it as a *real
+salience gap* (fix the rule) vs a *floor-model quirk* (small-model loop/hallucination, per the public
+"Local AI is not Opus" finding + the cheap-oracle ceiling — a small model adds nothing where one grep
+already settles the check). The terminal verdict stays with the **Sonnet-or-higher governor bound to a
+mechanical anchor** (Sonnet sim verdict + the anchor evidence; an opus judge is the *dispatch-recommended*
+strengthener, not a requirement — Sonnet-Floor Doctrine 2026-07-10) — no judge-only path, no
 weak-local-judge regression of the judge-robustness principle (mechanical anchor over judge-only verdict).
 The cross-family-panel upgrade spec lives in the private companion store's `handoff/` design note.
 
@@ -190,11 +193,15 @@ to be modified), check the **session model** (self-identity; if the runtime with
 unknown) and surface **one line** — then proceed, never block:
 
 - Model known and opus-tier or above → no notice (already optimal).
-- Model known and below opus-tier → *"이 작업은 FH 자체개발(Mode D)입니다 — 가용 최강 모델 핀을
-  권장합니다 (`/model opus` 이상; 측정 근거: README §Model setup). 그대로 진행해도 floored
-  디스패치가 깊이 턴을 커버하지만, 세션-레벨 설계 깊이는 핀이 좌우합니다."*
+- Model known and below opus-tier → **dispatch-first** (Sonnet-Floor Doctrine 2026-07-10 — the
+  primary recommendation keeps the Sonnet substrate and routes depth to dispatch; a session pin is
+  the *secondary* option): *"이 작업은 FH 자체개발(Mode D)입니다 — Sonnet 그대로 진행하면서 깊이
+  턴(적대검증·설계리뷰)은 사이드카/opus 디스패치로 커버하는 걸 권장합니다(동의 게이트:
+  capability_escalation_consent). 세션 전체가 설계-깊이 중심이면 차선으로 `/model opus` 핀도
+  가능합니다."*
 - Model unknown (runtime withholds identity) → static fallback: *"FH 자체개발 작업입니다 — 세션
-  모델이 opus 이상이 아니라면 핀 전환을 권장합니다 (`/model opus`+)."*
+  모델이 opus 미만이면 깊이 턴을 디스패치로 커버하세요(권장); 설계-깊이 세션이면 `/model opus`
+  핀이 차선입니다."*
 
 **Guards**: once per session · advisory only — **never switch the session model** (human override is
 inviolable; a pin is not a cap — tier-floor resolution §Floor governance) · field-project operation

package/knowledge/shared/harness-core/deep_research_capability_ladder.md

@@ -23,7 +23,7 @@ research-heavy task can pull it.
 | Rung | Capability | When it applies | Tier note |
 |---|---|---|---|
 | **1. Agentic research skill** | An autonomous multi-step researcher **present in the live session skill list** — in Claude Code that is `octo:research` (Claude Octopus, multi-AI synthesis) when installed. A native `/deep-research` was **not registered in CC in this install** (measured 2026-06-14: Skill `deep-research` → "Unknown skill"; the Claude **app** surfaces it highlighted, this CC build does not). Treat it as **app-side / operator-invoked unless a future CC build surfaces it** — re-detect from the live skill list, don't assume CC *cannot* have it (capability is install- and version-dependent — `[[feedback_verify_before_downgrade]]`) | Best when agent-fireable: runs its own search→read→synthesize loop | Self-contained; an external multi-AI path (Octopus → Gemini/Codex) bills **outside** CC's budget |
-| **2. Claude multi-source synthesis** | `WebSearch` + `WebFetch` tools, synthesized in-context | The always-available floor for any Claude session — no extra install | **Tier-sensitive**: synthesis depth tracks the session model. Routine survey = Sonnet default; deep analysis / contested findings = pin Opus (tier-floor, `multi_model_sidecar_strategy.md §Tier-floor resolution`) |
+| **2. Claude multi-source synthesis** | `WebSearch` + `WebFetch` tools, synthesized in-context | The always-available floor for any Claude session — no extra install | **Tier-sensitive**: synthesis depth tracks the session model. Routine survey = Sonnet default; deep analysis / contested findings = dispatch-first (route the deep-read to an opus/sidecar agent, consent-gated; session pin secondary — sonnet_floor_doctrine.md; tier-floor mechanics: `multi_model_sidecar_strategy.md §Tier-floor resolution`) |
 | **3. `frontier-digest`** | The narrow specialization — HN + arxiv trend scan with FH-context synthesis | Use **only** when the research *is* AI/harness trend-scanning, not general topic research | FH-native; has its own WebSearch fallback |
 
 **Resolution rule**: detect research-heavy intent → check the live skill list → take rung 1 if a

package/knowledge/shared/harness-core/fh_detail_protocols.md

@@ -175,6 +175,10 @@ priority: high|medium|low
 
 **forge-harness is not meant to use more tokens** — standard tier delivers meaningful improvements while minimizing token usage.
 
+> Terminology guard: the S/M/L/XL **execution tier is a token-depth budget, NOT a model tier** — it is
+> orthogonal to the Sonnet-floor / model-floor axis (`sonnet_floor_doctrine.md`); an XL run on Sonnet and
+> an S run on Opus are both legal combinations.
+
 ```yaml
 EXECUTION_TIER: standard   # light / standard / full / max
 ```

package/knowledge/shared/harness-core/loop_engineering.md

@@ -0,0 +1,80 @@
+# Loop Engineering — the 5-question discipline and FH's loop inventory
+
+> Companion node to the CLAUDE.md §Field-Harness Diagnostic **Loop-readiness lens** (its detail
+> home) and to `sonnet_floor_doctrine.md` (PROSE loop legs are exactly where Sonnet-tier misses
+> live — one spine, two lenses). Origin: 황민호 loop-eng 5-question review (2026-07-10, C-tier
+> sister ledger — dedup hit on coverage, the *lens* absorbed) + Loop Engineering sister
+> (`[[project_loop_engineering_sister]]`, Prompt→Context→Harness→Loop layering).
+
+## The 5 questions — from diagnostic to design-time discipline
+
+A path that *runs* is not a path that *loops*. Before authoring any autonomous path (skill step
+chain, routine, close sequence), answer all five **at design time** — the diagnostic lens then only
+re-checks what authoring already declared:
+
+| # | Question | FH's mechanical form |
+|---|---|---|
+| 1 | **Initiate** — what starts it, mechanically or by utterance? | trigger phrases (≥3, gate-checked) · hooks (SessionStart/Stop/pre-commit) · cadence rules |
+| 2 | **Complete** — is there a Done-When? | Done-When with declared check class (mandatory-pass / measured / judged) — already a skill-gate item |
+| 3 | **Validate** — is the check anchored, not judge-only? | mechanical anchor over judge verdict (`[[feedback_judge_robustness_mechanical_anchor]]`); judged conditions name their adversarial pairing |
+| 4 | **Halt** — budget guard, convergence detection, runaway stop? | token-budget-gate · convergence-loop N-round cap · goal-quench thresholds · the 1000-agent backstop |
+| 5 | **Persist** — does state reach the next run? | session card · handoff STATUS stamps · edit-manifest predict-verify · memory |
+
+**Design-time rule**: a new autonomous path whose author cannot answer one of the five has found a
+defect *before shipping it* — cheaper than the diagnostic finding it later. The field-asset
+scaffold (auto_project_mapping §6) carries halt + persist stubs so field skills answer #4/#5 by
+construction, the same by-construction pattern as the gate-compliant skeleton.
+
+## FH loop inventory — legs, enforcement class, measured gaps
+
+Census 2026-07-10, all rows cross-family source-verified (codex gpt-5.5 — xhigh for micro/session/
+weekly, high for quarterly/substrate; the substrate row's original governor self-assessment was
+4/5 REFUTED by the external pass — the census discipline earning its keep). MECH = hook /
+script / exit-code (tier-independent); PROSE = salience-dependent (Sonnet-floor risk surface).
+
+| Loop | initiate | complete | validate | halt | persist |
+|---|---|---|---|---|---|
+| **Micro** — goal-quench | MECH (`.active` state) | mixed (Done-When explicit; `/goal` invocation manual) | MECH (`.pending` + pipeline-conductor gate) | **PROSE** (mid-run thresholds instructional) | MECH (calibration record) |
+| **Session** — close chain ①–⑥ | PROSE (closing-phrase trigger) | **mixed** (card-last + step coverage now verified by `scripts/session_close_check.sh` — exit 1 on violation; the *performing* stays with the session, the *catching* is MECH, 2026-07-10) | mixed (git/PR inputs mech, synthesis remembered) | PROSE (no budget/stop guard) | **mixed** (companion-store sync script + SessionStart STATUS map + close-check ⑤ invariant, 2026-07-10) |
+| **Weekly** — harvest-loop / audit cycle | PROSE (proposal at session start) | PROSE (self-reported Done-When) | mixed (`below_floor_scan.sh` exit code; rest hand-gathered) | mixed (critic retry cap 1; no global budget) | PROSE (audit file by hand) |
+| **Quarterly** — maturity roadmap | PROSE (~90d cadence, no auto-detection) | PROSE (phase gates, checked manually) | PROSE (basis-path obligations, no anchor bundle) | **PROSE** (transition deferral / Phase-regression guards exist — hub_maturity_roadmap §6.1 — prose, NOT n/a) | PROSE (roadmap doc, no canonical state file) |
+| **Substrate** — self-adaptation mission | **mixed→MECH improving** (routine schedules + context-entry proposals; the "substrate-version jump" detector now EXISTS — `scripts/substrate_jump_detector.sh`, SessionStart-wired, silent-unless-jump; was a phantom until 2026-07-10) | PROSE (routine terminal states are prompt-following) | mixed (weekly change runs the 4-axis gate — marker form MECH at commit; removal approval prose/HITL) | PROSE (one-proposal-per-week · deferred-draft-PR fallback · stop-after-PR — guards exist, all prose, NOT n/a) | mixed (GitHub issue comments + draft PRs are the durable spine, plus gate markers/edit-manifest/fh_signals — not "memory") |
+
+**Reading the map**: the 4-axis auto-gate is FH's only all-MECH loop (initiate=hook detect,
+complete=all-axes-or-block, halt=missing-marker-fails, persist=marker+manifest) — and it is also
+FH's most trusted loop. That correlation is the doctrine: **trust tracks mechanization, not model
+tier.** The PROSE-densest loops (session close, weekly) are where the measured misses actually
+occurred (card staleness 2026-07-10; audit cadence slips).
+
+## Case study — persist-leg mechanization (2026-07-10)
+
+Company sessions push results to the companion store but never run the local close chain, so the
+card's ⑤ update was the only reconcile point — prose, and mtime-blind: a status stamp landing
+*before* a card rewrite became permanently invisible to the "newer than card" list. Fix: the
+SessionStart hook now emits an **mtime-independent STATUS map** (all DONE/SUPERSEDED/RESOLVED
+stamps, every session) with an explicit cross-check imperative. One measured miss → one mechanized
+leg — the standing pattern (`sonnet_floor_doctrine.md §Why`).
+
+## Hardening backlog — evidence-threshold, NOT built speculatively
+
+The census surfaces candidate hardenings (close-chain checklist script, weekly-audit scaffold
+script, harvest-loop evidence bundle, goal-quench checkpoint files). Per the build discipline
+(`[[feedback_evidence_threshold_build_discipline]]`), each is built **only when its miss is
+measured** (a real slip attributable to that PROSE leg), mirroring how the SessionStart hook and
+STATUS map each shipped on a production miss, not a guess. Recording the map here *is* the
+instrument: the next slip finds its leg pre-diagnosed.
+
+| Backlog item | Fires when (measured trigger) |
+|---|---|
+| ~~Close-chain ordered-checklist script~~ | **BUILT 2026-07-10** (`scripts/session_close_check.sh`) — operator strengthen-instruction; the miss class (card staleness) was already measured, only the build trigger was overridden (recorded, not silent) |
+| Weekly-audit scaffold + data-gather script | a weekly audit missed or hand-gathered wrong window data |
+| harvest-loop Step 0-b/0-c evidence check | a harvest run misses completed items despite `fh_completed_*` existing |
+| goal-quench mid-run checkpoint files (70/85/95%) | a /goal run blows through a threshold unnoticed |
+| ~~Substrate-jump detector~~ | **BUILT 2026-07-10** (`scripts/substrate_jump_detector.sh`, SessionStart-wired) — same operator instruction; structure-enforcing class (out-of-context drift), permanent per the durable-mechanization criterion |
+| Quarterly maturity checker (`quarterly_maturity_check.sh` — criterion status + §6.1 BLOCKED emit) | a quarterly re-diagnosis is missed >90d or a phase transition skips the simplification checklist |
+
+## Done When (for a new/changed autonomous path)
+
+- All 5 questions answered at design time, each leg labeled MECH or PROSE *(mandatory-pass)*.
+- Any judged validate-leg names its adversarial pairing *(mandatory-pass — inherits the skill gate)*.
+- PROSE legs on load-bearing paths carry a Sonnet blind-sim verdict *(measured — doctrine §ladder step 2)*.

package/knowledge/shared/harness-core/multi_model_sidecar_strategy.md

@@ -396,7 +396,11 @@ because it has opus?". A floor is satisfied by the chosen engine's **strongest f
 **Human override is inviolable — and a pin is not a cap**: if the operator pins a session default
 (stronger or weaker), FH follows it for **session turns**; floors govern FH's **own sub-agent
 dispatches** and a session pin does not lower them — that separation *is* the Sonnet-main +
-Opus-dispatch doctrine (pinned-sonnet sessions still dispatch floored agents at opus).
+Opus-dispatch doctrine (pinned-sonnet sessions still dispatch floored agents at opus). Canonical
+axiom + defect-class + prescription ladder: `sonnet_floor_doctrine.md` (2026-07-10) — this section
+remains the operating mechanics (F1/F2, floor governance) under that axiom; SKILL.md hard `model:`
+pins were retired the same day (session-inherit + dispatch recommendation), agent-side dispatch
+floors unchanged.
 
 **Field depth-escalation (the upward complement)**: floors push *dispatches* up automatically, but
 main-thread depth on a field session has no floor — so the templates bundle carries a Field