@chrono-meta/fh-gate 1.4.52 → 1.4.53

package/.claude/registry/README.md

@@ -0,0 +1,26 @@
+# .claude/registry
+
+Machine-readable registries for the forge-harness automation layer.
+
+## agent_cards.json
+
+The **canonical machine-readable mirror** of the agent registry. `AGENTS.md` stays the
+human-facing source of truth (roles, rationale, prose); `agent_cards.json` is its structured
+counterpart for tooling — capability discovery, dispatch routing, and count-drift detection.
+
+Inspired by the **A2A "Agent Card"** pattern (the 2026 standard for agent capability discovery):
+each card declares an agent's `id`, `file`, `role`, `allowed_tools`, `invoked_by`, and a `writes`
+flag. `agent_count` is asserted at the top level and **should equal the number of tracked `.md`
+files in `.claude/agents/`, `plugins/fh-meta/agents/`, and `plugins/fh-commons/agents/`** —
+re-checked on every agent add/remove by `harness-doctor` Step 11-2-B, which compares
+`agent_count` against the live file count; a mismatch is a State-Degradation signal.
+
+### Regeneration
+
+Hand- or script-derived from `AGENTS.md` (Agent Registry + Tool-restrictions tables) plus each
+tracked agent `.md` frontmatter. Regenerate whenever an agent is added, removed, or its tools
+change — and re-check `agent_count`. On any disagreement between `AGENTS.md` and an agent's own
+`.md`, **prefer the agent `.md`** (e.g. `challenger.md` has no `tools:` field, so its tools come
+from `AGENTS.md`).
+
+> Frontier basis: `knowledge/shared/harness-core/harness_frontier_diagnosis_2026-06-02.md` (identity ① Control Tower — closes the "no canonical machine-readable registry / count drift" gap noted in `fh_ecosystem_positioning.md`).

package/.claude/registry/agent_cards.json

@@ -0,0 +1,73 @@
+{
+  "version": "1.0",
+  "generated": "2026-06-07",
+  "source": "derived from AGENTS.md (Agent Registry + Tool restrictions tables) and tracked agent files",
+  "convention": "A2A Agent Card pattern — machine-readable capability discovery, count-synced to plugin agents/ directories",
+  "agent_count": 8,
+  "agents": [
+    {
+      "id": "beginner",
+      "file": "plugins/fh-meta/agents/beginner.md",
+      "role": "First-contact cold-read standpoint (user-mastery spectrum entry tier) — surfaces onboarding friction a fluent author cannot feel; constructive, not adversarial",
+      "allowed_tools": ["Read"],
+      "invoked_by": ["sim-conductor", "marketplace-gate", "install-wizard", "direct"],
+      "writes": false
+    },
+    {
+      "id": "main-player",
+      "file": "plugins/fh-meta/agents/main-player.md",
+      "role": "Engaged-user standpoint (user-mastery spectrum core tier) — intelligently scopes Light/Midcore/Heavy; Heavy carries the classic power-user edge/limit lens",
+      "allowed_tools": ["Read", "Grep", "Glob"],
+      "invoked_by": ["sim-conductor", "direct"],
+      "writes": false
+    },
+    {
+      "id": "expert",
+      "file": "plugins/fh-meta/agents/expert.md",
+      "role": "Domain-authority standpoint (user-mastery spectrum frontier tier) — web-grounded accuracy + SOTA currency, citation-enforced; checks against the external world, not internal assets",
+      "allowed_tools": ["Read", "WebSearch", "WebFetch"],
+      "invoked_by": ["sim-conductor", "paper-review", "direct"],
+      "writes": false
+    },
+    {
+      "id": "challenger",
+      "file": "plugins/fh-meta/agents/challenger.md",
+      "role": "Frontier-grade adversarial evaluator — adapts attack vectors to artifact type, enforces evidence citation, models its own information asymmetry; U1 absorbs the skeptic 'why not just X?' lens",
+      "allowed_tools": ["Read", "Grep", "Glob", "WebSearch", "WebFetch"],
+      "invoked_by": ["steel-quench", "harvest-loop", "sim-conductor", "direct"],
+      "writes": false
+    },
+    {
+      "id": "fact-checker",
+      "file": "plugins/fh-meta/agents/fact-checker.md",
+      "role": "Pre-recommendation deduplication — greps hub assets for existing skills/agents/patterns before a new recommendation; catches stale facts and duplicate work",
+      "allowed_tools": ["Read", "Grep", "Glob"],
+      "invoked_by": ["main-agent-before-new-asset"],
+      "writes": false
+    },
+    {
+      "id": "hub-persona-auditor",
+      "file": "plugins/fh-meta/agents/hub-persona-auditor.md",
+      "role": "Pre-publication audit of external-facing assets — 3+ persona simulation, 4-axis review (resonance/confusion/resistance/supplement), 3-tier revision proposals",
+      "allowed_tools": ["Read", "Grep", "Glob"],
+      "invoked_by": ["hub-cc-pr-reviewer", "sim-conductor", "direct"],
+      "writes": false
+    },
+    {
+      "id": "persona-innovator",
+      "file": "plugins/fh-meta/agents/persona-innovator.md",
+      "role": "Naming gap detection + frame proposals + external frontier absorption signals",
+      "allowed_tools": ["Read", "Grep", "Glob", "WebSearch", "WebFetch"],
+      "invoked_by": ["sim-conductor", "harvest-loop", "direct"],
+      "writes": false
+    },
+    {
+      "id": "quench-challenger",
+      "file": "plugins/fh-commons/agents/quench-challenger.md",
+      "role": "Steel-quench dedicated adversary — 3-DNA synthesis of Devil + Innovator + Prescriber; every attack paired with a concrete fix direction",
+      "allowed_tools": ["Read", "Grep", "Glob"],
+      "invoked_by": ["steel-quench", "install-doctor", "marketplace-gate"],
+      "writes": false
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "name": "forge-harness",
+  "owner": {
+    "name": "chrono-meta",
+    "email": "chrono-meta@users.noreply.github.com"
+  },
+  "metadata": {
+    "description": "forge-harness — Multi-instance persona orchestration and meta-tooling marketplace for Claude Code. Harness engineering toolkit for teams that want to evolve their AI collaboration practices.",
+    "pluginRoot": "./plugins"
+  },
+  "plugins": [
+    {
+      "name": "fh-meta",
+      "version": "1.4.53",
+      "description": "Hub meta-operations toolkit — 33 skills + 7 agents. New in 1.4.53: `fh-codex-doctor` (npm bin) — Codex adapter drift scanner; reads the documented M1/M2/M3 skill tier map + skill/agent source and reports codex-native/adapter-required/claude-native/unclassified per unit, wired into `npm test`/`prepublishOnly` (fail-closed on unclassified Claude-native primitives). New in 1.4.49: steel-quench gains Step 0.6 Verdict-Invariance Probe (groundedness axis — a load-bearing judged gate's verdict must track behavior, not rubric phrasing; measured flip-count over cross-family paraphrases; arXiv:2605.06161 Policy Invariance anchor); multi_model_sidecar_strategy §Vendor-native harness (a model is strongest in its own vendor CLI — Claude/CC, GPT/codex, Gemini/Antigravity; a universal router degrades all of them, so it stays an autocomplete/QA sidecar, never orchestration); predelete_check.sh fail-closed rewrite; memory-hygiene A-TMA anchor. New in 1.4.48: phantom-quench + steel-quench gain external frontier anchors (arXiv:2607.02052 package-hallucination; arXiv:2607.02057 prompt-coverage-adequacy); README model-flat claim reframed from a per-release point-curve to structural invariants (operation flattens across tiers; depth tier-order fixed within a generation). New in 1.4.47: onboarding step ① surfaces the Mode D companion-store session-start load in the auto-read salience anchor (previously only in the local binding + rules, so a greeting could skip the load). New in 1.4.46: context-doctor command-output axis (route to rtk/proxy for verbose CLI stdout, complementing .claudeignore; risk-gated to token-scarce envs). New in 1.4.41: context-doctor 2026 trigger vocab (context engineering/rot/collapse) + phantom-citation hardening; hub measurement-integrity-checklist (cross-model measurement pre-flight: display-name pin/reps≥3/discriminating probe). New in 1.4.40: install-wizard queryable-wiki scaffold (INDEX + session-start read + R/W/C ingest). New in 1.4.39: auto-decorrelation (cross-family verifier sidecar recruitment) + video-ingest (capability-routed video ingestion). New in 1.4.x: verify-axis check-class taxonomy (mandatory-pass/measured/judged), no-reinvention Tier-0 inventory, 7-class failure taxonomy, Destructive-Op Gate, Wave-T (Temper), tier-floor governance, Mode D Model Notice, FC consent lane, default-Sonnet guidance. New in 1.3.0: public-surface-audit, field-harvest Mode B auto-trigger, 4-axis gate scope ext. Validated cross-CLI: Claude Code, Codex, Gemini.",
+      "source": "./plugins/fh-meta"
+    },
+    {
+      "name": "fh-commons",
+      "version": "1.4.53",
+      "description": "Project-agnostic utility skills — 4 skills (convergence-loop · deliberation · mcp-circuit-breaker · token-budget-gate) + 1 agent (quench-challenger). Domain-independent utilities transplantable into any project.",
+      "source": "./plugins/fh-commons"
+    }
+  ]
+}

package/AGENTS.md

@@ -138,8 +138,8 @@ echo "Apply the following skill to the artifact below." | \
 
 | Tier | Definition | Examples |
 |---|---|---|
-| **M1 — Full** | All phases run without CC-native dependencies — no Stop hook, no `.claude/agents/` dispatch, no `/model` | `token-budget-gate`, `asset-placement-gate`, `phantom-quench`, `deep-clarify`, `deliberation`, `convergence-loop` |
-| **M2 — Partial** | Core workflow runs; CC-native phases require manual adaptation or skip | `steel-quench` (Wave 1–3 ✅; quench-challenger agent = manual), `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop` (git scan phase ✅; PR auto-proposal = manual) |
+| **M1 — Full** | All phases run without CC-native dependencies — no Stop hook, no `.claude/agents/` dispatch, no `/model` | `token-budget-gate`, `asset-placement-gate`, `phantom-quench`, `deep-clarify`, `convergence-loop` |
+| **M2 — Partial** | Core workflow runs; CC-native phases require manual adaptation or skip | `deliberation` (Mediator/Jury Agent steps = manual), `steel-quench` (Wave 1–3 ✅; quench-challenger agent = manual), `harness-doctor`, `context-doctor`, `sim-conductor`, `harvest-loop` (git scan phase ✅; PR auto-proposal = manual) |
 | **M3 — CC-only** | Requires CC Stop hook or session-scoped agent dispatch; methodology reference only | `goal-quench` (Phase 3 Stop hook), `hub-cc-pr-reviewer` (CC session context), `install-wizard` (settings.json write) |
 
 **M2 adaptation pattern**: when a step references `Agent(subagent_type=...)` or a slash command, substitute with `fh-run` (preferred) or a direct `codex exec` call reading the sub-agent's SKILL.md — same workflow, different runtime.

package/CHEATSHEET.md

@@ -197,6 +197,7 @@ FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-gate   # Codex backend (d
 # Run a skill or agent doc through a backend, outside Claude Code
 npx --package @chrono-meta/fh-gate fh-run --skill <name>
 npx --package @chrono-meta/fh-gate fh-goal "<goal text>"      # goal runner
+npx --package @chrono-meta/fh-gate fh-codex-doctor --strict  # Codex adapter drift check
 ```
 
 | Knob | Values | Effect |

package/README.md

@@ -95,7 +95,7 @@ forge-harness is structured as **two distinct layers**:
 | Layer | Contents | AI compatibility |
 |---|---|---|
 | **Methodology layer** | `tracks/`, `knowledge/`, `SKILL.md` docs, session protocols | Any AI model |
-| **Automation layer** | `.claude/agents/`, hooks, slash commands, `CLAUDE.md` rules | Claude Code only |
+| **Automation layer** | `plugins/*/agents/` (FH agents), `.claude/agents/` (field-project overrides), hooks, slash commands, `CLAUDE.md` rules | Claude Code only |
 
 The methodology layer is the portable core — persistent hub, accumulating learnings, curating cross-project knowledge. The automation layer makes it frictionless when running Claude Code.
 
@@ -149,6 +149,17 @@ FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --skill phantom-quenc
 FH_BACKEND=codex npx --package @chrono-meta/fh-gate fh-run --agent fh-commons:quench-challenger --file plugins/fh-meta/skills/foo/SKILL.md
 ```
 
+To check whether a changed FH skill/agent surface still has a clean Codex adapter path, run:
+
+```bash
+npx --package @chrono-meta/fh-gate fh-codex-doctor --strict
+```
+
+`fh-codex-doctor` scans the canonical skill/agent registry and reports which units are Codex-native,
+adapter-required, Claude-native, or unclassified. It is a drift detector for the thin adapter boundary;
+it does not try to clone the Claude Code automation layer. When run from an FH checkout it scans the
+current working tree; outside a checkout it scans the installed package.
+
 For Codex-primary work, keep using Codex's native goal/session features when available. `fh-goal` is only a portable wrapper for one-off non-interactive runs that should be followed by FH governance:
 
 ```bash

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/sonnet_floor_doctrine.md

@@ -33,6 +33,13 @@ markers) — never silently drop a capability.
   → SessionStart hook), the tone salience gap (2026-07-08 → recorded, prompt-layer), the
   card-reconcile blind spot (2026-07-10 → mtime-independent STATUS map in the hook). The doctrine
   is a name for what the fix pattern already was.
+- **The value does not vanish at the top tier — the harness complements the strongest model too**
+  (operator observation, 2026-07-10, same-day measured): a Sonnet blind probe caught a SIGPIPE
+  silent-death defect in a script the top-tier session had just written (5/5 repro), and the new
+  close-chain checker blocked that same top-tier session's card-last violation twice on its first
+  day. Structure-enforcing checks are tier-blind by construction — so the harness raises the floor
+  for weak models *and* guards the ceiling for strong ones. Weak-model benefit is the larger term
+  (H1), top-tier benefit is the existence proof that the harness is not scaffolding-only.
 
 ## The defect class: tier-gated capability
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrono-meta/fh-gate",
-  "version": "1.4.52",
+  "version": "1.4.53",
   "description": "FH runtime adapters — run FH governance, skills, and agents via Claude or Codex with machine-parseable gates.",
   "license": "MIT",
   "keywords": [
@@ -20,10 +20,11 @@
   "bin": {
     "fh-gate": "bin/fh-gate.js",
     "fh-run": "bin/fh-run.js",
-    "fh-goal": "bin/fh-goal.js"
+    "fh-goal": "bin/fh-goal.js",
+    "fh-codex-doctor": "bin/fh-codex-doctor.js"
   },
   "scripts": {
-    "prepare": "chmod +x bin/fh-gate.js bin/fh-run.js bin/fh-goal.js scripts/fh-gate.sh scripts/fh-run.sh scripts/fh-goal.sh",
+    "prepare": "chmod +x bin/fh-gate.js bin/fh-run.js bin/fh-goal.js bin/fh-codex-doctor.js scripts/fh-gate.sh scripts/fh-run.sh scripts/fh-goal.sh",
     "test": "bash scripts/selfcheck.sh",
     "prepublishOnly": "bash scripts/selfcheck.sh && bash scripts/public_surface_scan_files.sh",
     "release": "bash scripts/public_surface_scan_files.sh && npm publish"
@@ -45,10 +46,13 @@
   },
   "files": [
     "AGENTS.md",
+    ".claude-plugin/marketplace.json",
     "CATALOG.md",
     "CHEATSHEET.md",
     "CLAUDE.md",
+    ".claude/registry/agent_cards.json",
     "docs/CONTRIBUTING.md",
+    "bin/fh-codex-doctor.js",
     "bin/fh-gate.js",
     "bin/fh-run.js",
     "bin/fh-goal.js",
@@ -57,9 +61,13 @@
     "scripts/fh-gate.sh",
     "scripts/fh-run.sh",
     "scripts/fh-goal.sh",
+    "scripts/count_check.sh",
     "scripts/selfcheck.sh",
+    "templates/local_fh_context.md",
+    "plugins/fh-meta/.claude-plugin/plugin.json",
     "plugins/fh-meta/skills",
     "plugins/fh-meta/agents",
+    "plugins/fh-commons/.claude-plugin/plugin.json",
     "plugins/fh-commons/skills",
     "plugins/fh-commons/agents",
     "knowledge/shared/harness-core",

package/plugins/fh-commons/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "fh-commons",
+  "version": "1.4.53",
+  "engines": {
+    "claudeCode": ">=1.0.0"
+  },
+  "description": "Cross-project utility skill bundle — 4 skills + 1 agent. Domain-agnostic and portable: convergence-loop, deliberation, mcp-circuit-breaker, token-budget-gate + quench-challenger agent.",
+  "author": {
+    "name": "chrono-meta",
+    "email": "chrono-meta@users.noreply.github.com"
+  },
+  "keywords": [
+    "commons",
+    "convergence-loop",
+    "gate-reinforcement",
+    "multi-round-validation",
+    "deliberation",
+    "multi-perspective-synthesis",
+    "forge-skill",
+    "domain-agnostic",
+    "cross-project"
+  ]
+}

package/plugins/fh-meta/.claude-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "fh-meta",
+  "version": "1.4.53",
+  "engines": {
+    "claudeCode": ">=1.0.0"
+  },
+  "description": "Hub meta-engineering toolkit — 33 skills + 7 agents. New in 1.4.48: phantom-quench + steel-quench gain external frontier anchors (arXiv:2607.02052 package-hallucination; arXiv:2607.02057 prompt-coverage-adequacy); README model-flat claim reframed from a per-release point-curve to structural invariants (operation flattens across tiers; depth tier-order fixed within a generation). New in 1.4.47: onboarding step ① surfaces the Mode D companion-store session-start load in the auto-read salience anchor (previously only in the local binding + rules, so a greeting could skip the load). New in 1.4.46: context-doctor gains a command-output axis — routes to a command-output proxy/hook (rtk) to trim verbose CLI stdout, complementing .claudeignore; risk-gated to token-scarce environments (lossy filtering, off gate-input paths). New in 1.4.41: context-doctor 2026 trigger vocab (context engineering/rot/collapse) + phantom-citation hardening; hub measurement-integrity-checklist (cross-model measurement pre-flight: display-name pin/reps≥3/discriminating probe). New in 1.4.40: install-wizard scaffolds the companion store as a queryable wiki (INDEX + session-start read + Raw/Wiki/Conversation ingest axis). New in 1.4.39: auto-decorrelation (cross-family verifier sidecar recruitment, calibration-gated) + video-ingest (capability-routed video ingestion). New in 1.4.37: corpus-grounding-expander + persona-roster-expander (field-harvested verbatim-relay capability skills). New in 1.3.0: public-surface-audit (git-tracked private-token leak scan), field-harvest Mode B session-end auto-trigger, 4-axis gate scope extension (docs/ + AGENTS.md). New in 1.2.0: pipeline-conductor (4-pipeline gated sweep), return-path-gate (chain closure audit), goal-quench (Stop hook + quality gate), steel-quench Wave 5 (multi-model sidecar challenger), 2-layer architecture docs, YAML validation script. Validated cross-CLI: Claude Code, Codex, Gemini.",
+  "author": {
+    "name": "chrono-meta",
+    "email": "chrono-meta@users.noreply.github.com"
+  },
+  "keywords": [
+    "hub-meta",
+    "fact-check",
+    "self-verification",
+    "bidirectional-validation",
+    "cross-ecosystem-synergy",
+    "plugin-recommender",
+    "pr-review",
+    "harness-engineering",
+    "ai-collaboration",
+    "token-efficiency",
+    "context-doctor",
+    "harness-doctor",
+    "install-doctor",
+    "install-conflict-detection",
+    "install-wizard",
+    "onboarding-automation",
+    "marketplace-gate",
+    "marketplace-readiness",
+    "meta-prompt-builder",
+    "prompt-delegation",
+    "circular-validation",
+    "2d-adversary"
+  ]
+}

package/scripts/count_check.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# count_check.sh — skill/agent count-consistency check (single source).
+# Class: mandatory-pass (harness_6axis_framework.md §Axis 5) — exit 1 on drift.
+#
+# Called by ALL THREE count-consistency boundaries so one logic runs everywhere:
+#   - scripts/selfcheck.sh            → publish-readiness (prepublishOnly + npm test)
+#   - templates/.git-hooks/pre-commit → local commit time, `--staged` (index mode)
+#   - .github/workflows/validate.yml  → PR/merge boundary (checked-out tree == committed)
+#
+# Origin (fh_signal_2026-06-21): the count check used to live ONLY at the publish boundary.
+# But the actor that breaks it — a commit/merge that adds/removes a skill dir — acts at
+# commit/merge time, so a skill-adding PR (#111) merged with stale counts and they sat
+# undetected on main until the next publish. This is the gate-locality gap (a gate must
+# live where the breaking action happens). One source, three boundaries, no reinvention.
+#
+# Modes:
+#   (default)  count the WORKING TREE — selfcheck (publish; tree == HEAD) and CI
+#              (a checked-out PR IS the committed state). cat/glob the on-disk files.
+#   --staged   count the INDEX (exactly what THIS commit will contain) — the pre-commit
+#              hook. Fixes steel-quench S1 (2026-06-21): a worktree-only count can
+#              FALSE-PASS a commit that stages a skill add but leaves the count-file
+#              updates unstaged — the gate would verify a different tree than it commits.
+set -u
+cd "$(dirname "${BASH_SOURCE[0]}")/.." || { echo "COUNT-CHECK: FAIL (cannot cd to repo root)"; exit 1; }
+
+MODE="worktree"
+[ "${1:-}" = "--staged" ] && MODE="staged"
+fail=0
+
+# Read a tracked file's content from the active tree (index in --staged, disk otherwise).
+read_tree() { # read_tree <path>
+  if [ "$MODE" = staged ]; then git show ":$1" 2>/dev/null; else cat "$1" 2>/dev/null; fi
+}
+# List a plugin's top-level SKILL.md paths in the active tree.
+list_skills() { # list_skills <plugin>
+  if [ "$MODE" = staged ]; then
+    git ls-files --cached -- "plugins/$1/skills" 2>/dev/null \
+      | grep -E "^plugins/$1/skills/[^/]+/SKILL\.md$"
+  else
+    local s
+    for s in plugins/"$1"/skills/*/SKILL.md; do [ -f "$s" ] && echo "$s"; done
+  fi
+}
+# Count a plugin's top-level agent .md files in the active tree.
+count_agents() { # count_agents <plugin>
+  if [ "$MODE" = staged ]; then
+    git ls-files --cached -- "plugins/$1/agents" 2>/dev/null \
+      | grep -cE "^plugins/$1/agents/[^/]+\.md$"
+  else
+    ls plugins/"$1"/agents/*.md 2>/dev/null | wc -l | tr -d ' '
+  fi
+}
+# Active skill = SKILL.md whose head (first 20 lines) carries no deprecation marker
+# (a whole-file grep false-positives on skills that merely mention the word).
+count_active() { # count_active <plugin>
+  local n=0 s
+  while IFS= read -r s; do
+    [ -z "$s" ] && continue
+    read_tree "$s" | head -20 | grep -qE 'deprecated: true|DEPRECATED' || n=$((n+1))
+  done < <(list_skills "$1")
+  echo "$n"
+}
+
+meta_sk=$(count_active fh-meta); meta_ag=$(count_agents fh-meta)
+com_sk=$(count_active fh-commons); com_ag=$(count_agents fh-commons)
+total_sk=$((meta_sk + com_sk)); total_ag=$((meta_ag + com_ag))
+
+# Impossible-zero guard (steel-quench A4 — fail CLOSED): fh-meta always has active skills.
+# A 0 means the tree/glob resolved to nothing (wrong cwd, empty index, sh-as-bash shim) —
+# a gate must never return "consistent" from an empty tree.
+if [ "$meta_sk" -eq 0 ]; then
+  echo "COUNT-CHECK: FAIL (0 active fh-meta skills — empty/wrong tree, mode=$MODE)"
+  exit 1
+fi
+
+count_check() { # count_check <label> <file> <expected-string>
+  if read_tree "$2" | grep -q "$3"; then
+    echo "PASS  count: $1"
+  else
+    echo "FAIL  count: $1 — expected \"$3\" in $2 (actual: fh-meta ${meta_sk}sk/${meta_ag}ag, fh-commons ${com_sk}sk/${com_ag}ag)"
+    fail=1
+  fi
+}
+count_check "fh-meta plugin.json"      plugins/fh-meta/.claude-plugin/plugin.json    "${meta_sk} skills + ${meta_ag} agents"
+count_check "fh-commons plugin.json"   plugins/fh-commons/.claude-plugin/plugin.json "${com_sk} skills"
+count_check "marketplace.json fh-meta" .claude-plugin/marketplace.json               "${meta_sk} skills + ${meta_ag} agents"
+count_check "README header"            README.md                                     "${total_sk} skills · ${total_ag} agents"
+count_check "local_fh_context fh-meta" templates/local_fh_context.md                 "(fh-meta, ${meta_sk})"
+
+if [ "$fail" -ne 0 ]; then
+  echo "COUNT-CHECK: FAIL"
+  exit 1
+fi
+echo "COUNT-CHECK: PASS (mode=$MODE)"
+exit 0

package/scripts/selfcheck.sh

@@ -25,6 +25,11 @@ for f in bin/*.js; do
   check "node --check $f" node --check "$f"
 done
 
+# Codex adapter drift: the thin Codex runtime must keep reading canonical FH
+# skill/agent surfaces without silently accepting Claude-native primitives as
+# Codex-native.
+check "fh-codex-doctor --strict" bash -c 'node bin/fh-codex-doctor.js --strict >/dev/null'
+
 # Bash surface: npm-shipped scripts + local bin wrappers + gate-chain infra
 for f in scripts/*.sh bin/fh-gate bin/fh-run bin/fh-goal \
          templates/regression_guard.sh templates/temper_check.sh templates/predelete_check.sh templates/.git-hooks/pre-commit; do
@@ -43,26 +48,28 @@ if ! bash scripts/count_check.sh; then
   fail=1
 fi
 
-# Referenced-path existence: backtick-quoted repo-relative file refs in the always-loaded
-# governance surface (CLAUDE.md + .claude/rules/*.md) must exist. Phantom-reference class
-# recurred N>=3 in the 2026-06-11 audit window (operations.md _scanner.sh, claude-chrono path,
-# stale templates ref) — instrument-not-habit. Globs/placeholders/{vars} are excluded by the
-# filter; tracks/ is machine-local and deliberately out of scope. Gitignored refs (e.g.
-# `.claude/settings.json` named in prose *about* gitignored files) are skipped — they exist
-# locally but not on a fresh clone, and "must exist" here means "must ship".
-while IFS= read -r p; do
-  if git check-ignore -q "$p" 2>/dev/null; then
-    echo "SKIP  ref-path (gitignored): $p"
-  elif [ -f "$p" ]; then
-    echo "PASS  ref-path: $p"
-  else
-    echo "FAIL  ref-path: $p — referenced in CLAUDE.md/.claude/rules but missing"
-    fail=1
-  fi
-done < <(grep -hoE '\`[^\` ]+\`' CLAUDE.md .claude/rules/*.md 2>/dev/null \
-  | sed 's/\`//g' \
-  | grep -E '^(knowledge|templates|scripts|docs|plugins|\.claude)/[^*{}<>$]+\.(md|sh|ya?ml|jsonc|json)$' \
-  | sort -u)
+# Referenced-path existence is a source-tree check. The npm package intentionally
+# ships a narrower runtime surface, so package-mode selfcheck skips this section.
+if [ -d ".claude/rules" ]; then
+  # Backtick-quoted repo-relative file refs in the always-loaded governance surface
+  # (CLAUDE.md + .claude/rules/*.md) must exist. Phantom-reference class recurred
+  # N>=3 in the 2026-06-11 audit window — instrument-not-habit.
+  while IFS= read -r p; do
+    if git check-ignore -q "$p" 2>/dev/null; then
+      echo "SKIP  ref-path (gitignored): $p"
+    elif [ -f "$p" ]; then
+      echo "PASS  ref-path: $p"
+    else
+      echo "FAIL  ref-path: $p — referenced in CLAUDE.md/.claude/rules but missing"
+      fail=1
+    fi
+  done < <(grep -hoE '\`[^\` ]+\`' CLAUDE.md .claude/rules/*.md 2>/dev/null \
+    | sed 's/\`//g' \
+    | grep -E '^(knowledge|templates|scripts|docs|plugins|\.claude)/[^*{}<>$]+\.(md|sh|ya?ml|jsonc|json)$' \
+    | sort -u)
+else
+  echo "SKIP  ref-path (package mode: .claude/rules absent)"
+fi
 
 if [ "$fail" -ne 0 ]; then
   echo "SELFCHECK: FAIL"

package/templates/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+## Session Start
+
+When a user starts a session with greetings like "hello", "let's start", "resume", "continuing from where we left off", or says "read root memory", **both layers must activate**:
+
+### Layer A — Auto read (4 steps required)
+
+1. **Read CATALOG.md** — `~/projects/forge-harness/CATALOG.md` (recent work context + latest meta cwd work cross-link)
+2. **Read latest session file** — `~/projects/forge-harness/tracks/{project}/` most recent mtime item (last work on domain + next round reverse-injection intent persistence location / use `ls -lat` or `find -mtime`)
+3. **Check MEMORY.md next-session trigger** — if project memory `MEMORY.md` auto-load is truncated, explicitly Read to supplement the next-session trigger section
+4. **Check todo/plan files if present** — `*todo*`/`*plan*` pattern (supplementary materials)
+5. **Search for duplicate installs in same root** — `ls ../ | grep -iE '(harness|forge)'` to catch sibling assets in parent directory. If found, report to user + delegate branching decision (use existing install / proceed with new / archive then proceed)
+
+### Layer B — Proactive initiative (active onboarding 5-skill cascade)
+
+After Layer A completes, **when the user enters a task**, activate AI proactive initiative mode:
+
+1. **Auto-initiative (1-line question)** — *"What task/project would you like to start? (e.g., 'Spring Boot API development', 'React component refactoring', 'continue existing [X] track')"* (if active track exists: *"Would you like to continue active track [X], or enter a new task?"*)
+2. **5-skill cascade** — `plugin-recommender` (internal GHE → external → built-in candidates) → `cross-ecosystem-synergy-detection` (synergy grade table) → `.claudeignore` standard initiative (`cp templates/.claudeignore`) → model switching guidance (default `/model sonnet` — FH dispatches floored skills/agents at higher tiers itself; pin a stronger model for harness-editing sessions, or when the Field Depth-Escalation Notice below fires — see README §Model setup) → `verify-bidirectional`·`harvest-loop` natural emergence waiting
+3. **User consent → actual setup** — plugin install / skill pre-activation / `.claudeignore` application / model switch
+4. **Project cwd handover guidance** — *"Setup complete. Move to the project cwd and call `claude` to start working."*
+
+**Simplification guard**: When an explicit task utterance is made (e.g., "debug X code"), enter task immediately (skip onboarding). Activates once per session.
+
+### Field Depth-Escalation Notice (advisory — once per session)
+
+The Sonnet default covers routine field work because FH dispatches floored skills/agents at higher
+tiers itself. But when **main-thread development visibly strains the session tier**, surface a
+one-line escalation proposal — do not leave it to recall:
+
+**Triggers** (any one): the same problem survives 2–3 correction loops · the work enters
+architecture/design reasoning that cannot be decomposed into a dispatchable unit · the user
+signals being stuck ("keeps failing", "why is this still wrong").
+
+**Two-step ladder** (propose the cheaper rung first):
+1. **Opus dispatch (sidecar)** — if the heavy reasoning packages into a unit (a design review, a
+   root-cause hunt, an adversarial pass), propose dispatching it to an Opus agent: the session
+   stays on Sonnet, cost stays local to the unit.
+2. **Session pin** — if the work is inherently main-thread (iterative dialogue design, repeated
+   whole-context reasoning), propose: *"This work demands session-level design depth — pinning
+   `/model opus` is recommended. Proceeding as-is also works: dispatches still cover floored units."*
+3. **No higher tier available** — common in metered API routing (a Bedrock-style Sonnet-only
+   deployment) or alternative runtimes (Hermes / OpenCode-class) that don't offer higher Claude
+   tiers: skip the proposal, proceed at the available tier, and **flag depth-sensitive
+   deliverables with an explicit below-floor limitation note** (F2 semantics — tier-floor
+   resolution, `multi_model_sidecar_strategy.md §Tier-floor`). Silent proceeding is the failure
+   mode this rung exists to prevent; the note makes the deliverable a re-review candidate when a
+   floor tier becomes reachable.
+
+**Guards** (mirrors the hub's Mode D Model Notice): once per session · advisory only — **never
+switch the session model autonomously** (human override is inviolable) · sessions where nothing
+strains never see it — the Sonnet default stays friction-free.
+
+**Basis**: Meta-harness mission *"easy and convenient + no setup burden + token savings"* direct implementation mechanism. Natural hub/action-leader division (single trigger in meta-harness cwd → handover to action-leader cwd).
+
+**3 usage modes — "don't block those who come, don't stop those who leave"** (meta-harness operating philosophy):
+- **Mode A (standard)**: meta-harness cwd setup → handover to separate project cwd (4 steps above)
+- **Mode B (resident)**: create **separate project directory** within the forge-harness install environment and work there. Keep the forge-harness directory itself as reference only — use `.gitignore` to block forge-harness assets from mixing into the project
+- **Mode C (plugin/skill only)**: install only plugins/skills without going through forge-harness (available via marketplace without cloning). Skill output accumulates as history within the user's own project. No automatic signals from the forge-harness side expected — indirect contribution depends on user's active communication (issues · PR · channels)
+
+If the user explicitly states a mode, immediately guide that mode. Do not force standard mode. Do not accumulate personal work artifacts in the forge-harness directory itself (protect reference asset identity).
+
+## Asset Synergy Branching Decision (meta vs. action-leader)
+
+When persisting new assets (memory · feedback · patterns · rules) during a session, asset location determination is required:
+
+| Location | Nature | Examples |
+|---|---|---|
+| **Meta-harness side seed** | Useful as-is when installed in other projects (cross-project synergy) | User baseline propositions, environment common conventions, common action rules for all personas, session operation patterns |
+| **Action-leader project side persistence** | Meaningful only in this project's domain/session context | Domain knowledge, session records, domain-specific validation loop outputs, per-project identity |
+
+When the judgment is ambiguous, the AI **states synergy potential first** then delegates the location decision to the user.
+
+## Knowledge Hub (forge-harness)
+
+Persistent knowledge for this project is stored at `~/projects/forge-harness/`.
+
+- **Past work search**: First read `~/projects/forge-harness/CATALOG.md`, identify related files by tags
+- **Learnings/feedback originals**: `~/projects/forge-harness/tracks/{project_name}/`
+- **At session end**: follow the Sync Protocol in `~/projects/forge-harness/CLAUDE.md` to sync
+- **When new patterns are found**: follow the Push Protocol in `~/projects/forge-harness/CLAUDE.md` to feed back
+
+<!-- [CUSTOMIZE] Replace {project_name} with the actual project name -->
+<!-- [CUSTOMIZE] If there is a domain knowledge path, add:
+- **Domain knowledge**: `~/projects/forge-harness/knowledge/domain/{domain}/`
+-->

package/templates/local_fh_context.md

@@ -0,0 +1,18 @@
+---
+scope: local-only
+description: forge-harness path and skill list pointer — local only, do not commit to shared repo
+---
+
+# forge-harness Cross-Context
+
+> Install: `cp {FH_ROOT}/templates/local_fh_context.md .claude/rules/local_fh_context.md`
+> Local only: `echo ".claude/rules/local_fh_context.md" >> .git/info/exclude`
+
+**forge-harness path**: `~/path/to/forge-harness` (replace with your actual install path)
+**Session records**: `{FH_ROOT}/tracks/_meta/`
+
+**Available skills (fh-meta, 33)**: agent-composer · apex-review · asset-placement-gate · auto-decorrelation · context-doctor · contention-layer · corpus-grounding-expander · cross-ecosystem-synergy-detection · deep-clarify · edit-manifest · field-harvest · frontier-digest · goal-quench · harness-doctor · harvest-loop · hub-cc-pr-reviewer · install-doctor · install-wizard · marketplace-gate · memory-hygiene · meta-prompt-builder · persona-roster-expander · phantom-quench · pipeline-conductor · plugin-recommender · prompt-regression · public-surface-audit · return-path-gate · sim-conductor · salience-splitter · steel-quench · verify-bidirectional · video-ingest
+
+**Available skills (fh-commons)**: convergence-loop · deliberation · mcp-circuit-breaker · token-budget-gate
+
+Skill details available on demand at `{FH_ROOT}/plugins/{plugin}/skills/{skill-name}/SKILL.md`.