@chrono-meta/fh-gate 1.4.41 → 1.4.42

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

@@ -0,0 +1,217 @@
+---
+name: fh-synergy-playbook
+description: Concrete workflow specifications for using FH governance alongside OpenCode, Hermes, and OpenHuman — grounded in empirical results, no unverified claims.
+date: 2026-05-31
+tags: [synergy, integration, opencode, hermes, openhuman, governance, playbook, marketing]
+---
+
+# FH Synergy Playbook — How to Use FH with OpenCode, Hermes, and OpenHuman
+
+This document describes **exact workflows** for combining forge-harness with three AI agent projects. Every outcome stated here is backed by a recorded experiment or a structural guarantee from the software itself. Nothing is promised without evidence.
+
+---
+
+## The Core Pattern (Abstract)
+
+```
+AI agent generates or mutates code
+    ↓
+FH governance pass (before merge)
+    ↓
+Structured verdict: PASS | PENDING | BLOCKED
+    ↓
+Merge (if PASS) or fix-cycle (if PENDING/BLOCKED)
+```
+
+**What FH adds:** a structured verification layer that runs the same criteria every time, regardless of which model generated the code or which CI system is in use. It reads files the agent writes — no API integration, no runtime adapter.
+
+**What FH does NOT do:**
+- It does not fix the code for you (it produces findings, not patches)
+- It does not replace CI (unit tests and FH governance are complementary, not competing)
+- It does not guarantee zero bugs in output — it guarantees that structured verification ran
+
+---
+
+## With OpenCode — AI Code Generation + FH Quality Gate
+
+### The gap FH closes
+
+OpenCode generates code rapidly. Its own CI (unit tests, type checks) validates syntax and basic behavior. What it misses: security-adjacent logic, arity/allowlist edge cases, AI-generated assumptions that pass tests but break real-world usage.
+
+### Workflow
+
+```bash
+# 1. Let OpenCode do its work
+opencode run "implement the feature"
+
+# 2. Capture what changed
+export FH_TARGET_FILES=$(git diff main..HEAD --name-only)
+
+# 3. Run FH governance pass
+./scripts/fh-gate.sh "$FH_TARGET_FILES"
+# → generates structured prompt for steel-quench + pipeline-conductor
+
+# 4. Read the verdict
+# FH_STATUS: SUCCESS
+# FH_GATE_VERDICT: PASS | PENDING | BLOCKED
+# findings: (YAML block — actionable issues with grade A/B/C)
+```
+
+### Evidence
+
+**Controlled trial (2026-05-31):** Applied to `packages/opencode/src/permission/arity.ts` — 163 lines, AI-generated, 6 unit tests all passing, self-evaluation verdict: DONE.
+
+FH governance verdict: **PENDING**.
+
+Findings:
+- **A-grade:** `prefix()` short-token path — permission allowlist may not cover bare commands. Untested execution path.
+- **A-grade:** `npx`, `opencode`, `claude`, `bunx`, `uvx` absent from ARITY table — `npx <anything>` receives the same broad allow pattern, security model weakened.
+- **B-grade:** AI-generated dictionary has no maintenance protocol.
+
+**Causal attribution:** same code, same model (Claude), same CI — different methodology layer. The delta is attributed to the governance pass, not the model.
+
+### When to use
+
+- After any OpenCode session that touches security-sensitive files (`permission/`, `auth/`, `token/`, `key/`)
+- Before merging AI-generated code to main
+- As part of a Stop hook: OpenCode exits → fh-gate.sh auto-triggers → verdict in git notes
+
+---
+
+## With Hermes — Skill Configuration Audit Before Dispatch
+
+### The gap FH closes
+
+Hermes orchestrates agents through skill files. Skill configuration errors (missing validation, unsandboxed context, credential exposure) only surface at runtime — sometimes in production. FH governance catches these before the skill is dispatched.
+
+### Workflow
+
+```bash
+# 1. After adding or modifying a Hermes skill
+SKILL_PATH="skills/autonomous-ai-agents/opencode/SKILL.md"
+
+# 2. Run FH governance on the skill file
+export FH_TARGET_FILES="$SKILL_PATH"
+export FH_CALLER="hermes"
+export FH_GATE_LEVEL="standard"
+./scripts/fh-gate.sh "$FH_TARGET_FILES" "$FH_GATE_LEVEL" "$FH_CALLER"
+
+# 3. Before dispatching the skill, check verdict
+# If PENDING → review findings before allowing live dispatch
+```
+
+### Evidence
+
+**Gemini sidecar review (2026-05-31):** Applied to Hermes `skills/autonomous-ai-agents/opencode/SKILL.md`.
+
+Findings:
+- **A-grade:** No pre-execution plan validation — OpenCode operates directly on `workdir` without a review step before file mutations. Destructive rewrites land unreviewed.
+- **A-grade:** Secret ingestion risk — OpenCode may ingest `.env` files or `.git` history into prompt context, potentially exposing credentials to external LLM providers.
+- **B-grade:** No convergence verification — background sessions can exit with success status while leaving codebase in broken state.
+
+**Filed as:** Hermes issue [#35709](https://github.com/NousResearch/hermes-agent/issues/35709).
+
+### When to use
+
+- Before committing any new Hermes skill that dispatches an external agent
+- During Hermes skill review cycles
+- As part of Hermes CI: run fh-gate.sh on changed skill files in PRs
+
+---
+
+## With OpenHuman — Memory Tree Staleness Audit
+
+### The gap FH closes
+
+OpenHuman's Memory Tree stores persistent context (technical decisions, file paths, architectural claims). These are validated once at write time, then trusted indefinitely. FH's `memory-hygiene` + `phantom-quench` pattern re-verifies memory entries against live state.
+
+### Workflow
+
+```bash
+# 1. Extract memory entries that reference file paths or technical claims
+# (OpenHuman Memory Tree format — paths, decisions, URLs)
+
+# 2. For each entry, verify it still holds
+for entry in memory_entries:
+    verify file paths exist in current codebase
+    verify external URLs still reachable
+    verify technical claims match current code
+
+# 3. Verdict per entry:
+#   GROUNDED  — verified, safe to use
+#   STALE     — entry exists but referenced reality changed (warn, prompt for update)
+#   BROKEN    — hard reference failure (flag for immediate update)
+```
+
+### Evidence
+
+**Structural analysis (2026-05-31):** OpenHuman's `pr-review-shepherd` skill documentation notes that "Composio catalog slugs occasionally drift" — an acknowledgment that the stale-but-confident failure mode exists in the project's own documentation.
+
+**FH's `memory-hygiene` skill** implements this pattern for harness memory with a verified weekly cadence. The same algorithm applies directly to OpenHuman's Memory Tree.
+
+**Filed as:** OpenHuman issue [#3069](https://github.com/tinyhumansai/openhuman/issues/3069).
+
+### When to use
+
+- Weekly, or on session start if >7 days since last audit
+- After major refactors that move or delete files
+- After reversing a significant architectural decision
+
+---
+
+## Expected Outcomes (Honest Estimates)
+
+Based on the controlled trial and sidecar experiments:
+
+| Scenario | Expected FH Verdict | Finding Rate |
+|---|---|---|
+| AI-generated code, CI passing, no prior governance | PENDING (expected) | 1–3 A/B-grade findings per session (empirical: 2A+1B on arity.ts) |
+| Hermes skill configuration, new external agent | PENDING (expected) | 1–2 A-grade findings per skill (empirical: 2A+1B on opencode skill) |
+| Human-written code, existing tests passing | PASS (expected) | 0–1 B-grade; A-grade unlikely but possible |
+| Previously FH-reviewed code, no changes | PASS | Near-zero new findings (compounding effect) |
+
+**Important caveat:** These are estimates from a small sample. Your actual finding rate depends on code quality, domain, and how much adversarial pressure the governance pass applies. The finding rate is not guaranteed — the governance execution is.
+
+---
+
+## The "No Integration Required" Value Proposition
+
+All three workflows above require:
+1. `git diff` to capture changed files
+2. `./scripts/fh-gate.sh` to generate a structured governance prompt
+3. Reading the verdict
+
+No API integration. No OpenCode plugin. No Hermes adapter. No OpenHuman SDK.
+
+FH reads files OpenCode / Hermes / OpenHuman write. The protocol is the interface.
+
+This also means FH governance can be added **at any point in an existing workflow** — no architectural changes required.
+
+---
+
+## Compounding Effect
+
+The first FH governance pass on a codebase finds the most issues. Each subsequent pass finds fewer — not because the tool is degrading, but because the codebase is improving. This is the governance dividend:
+
+```
+Pass 1: PENDING (2 A-grade, 1 B-grade)
+    ↓ fix
+Pass 2: PENDING (0 A-grade, 1 B-grade)
+    ↓ fix
+Pass 3: PASS
+    ↓ future changes re-enter at Pass 1 only for the changed files
+```
+
+Over time, the governance overhead per PR decreases while baseline code quality rises. The tool does not get harder to satisfy — the codebase gets easier to verify.
+
+---
+
+## References
+
+- **Controlled trial (Experiment 2):** `tracks/_meta/fh_opencode_governance_experiment_2026_05_31.md`
+- **Sidecar experiment (Experiment 1):** `knowledge/shared/harness-core/multi_model_sidecar_strategy.md`
+- **Integration contract spec:** `knowledge/shared/harness-core/fh_integration_contract.md`
+- **fh-gate.sh:** `scripts/fh-gate.sh`
+- **OpenCode issue:** github.com/anomalyco/opencode/issues/30057
+- **Hermes issue:** github.com/NousResearch/hermes-agent/issues/35709
+- **OpenHuman issue:** github.com/tinyhumansai/openhuman/issues/3069

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

@@ -0,0 +1,57 @@
+---
+name: gate-locality-principle
+description: A safety gate must live where the actor that needs it actually reads it — a gate defined in a place the enforcing actor never loads is decorative, not enforced.
+type: reference
+date: 2026-06-20
+tags: [governance, gate-locality, multi-runtime, judge-robustness, field-harvest]
+originProjects: [two restricted-env field harnesses]
+---
+
+# Gate-Locality Principle
+
+> **A safety gate must live where the actor that needs it actually reads it.**
+> A gate defined in a place the enforcing actor never loads provides the *appearance* of safety
+> with none of the enforcement. Locality is part of the gate's correctness, not an afterthought.
+
+This is a sibling of the **judge-robustness / mechanical-anchor** spine: judge-robustness says *don't
+let a foolable judge hold the terminal verdict*; gate-locality says *don't put the gate somewhere the
+enforcer can't see it*. Both fail the same way — a control that looks present but cannot actually fire.
+
+## The failure mode (two observed shapes)
+
+| Shape | Where the gate was | Who needed it | Why it didn't fire |
+|---|---|---|---|
+| **Code-locality** | absent from the write path entirely | the function that writes to JIRA | the writeback gate checked confidence but not provenance, so a self-inferred finding auto-posted as if verified |
+| **File-locality** | only in a Claude-only `CLAUDE.md` | a Gemini/Codex orchestrator that auto-loads root `AGENTS.md`, not `CLAUDE.md` | the runtime assumed the commander *role* without inheriting the *gates* |
+
+Both were found 2026-06-20 across **two field harnesses** (Harness-A: a provenance gate missing from a
+write path; Harness-B + Harness-A: orchestration gates that lived only in a Claude-only file). The
+recurrence across two contexts is what lifts this past a
+single anecdote; it is N=2 within one operator's projects, so **cross-operator confirmation is the
+upgrade path** that would harden it from a working principle to a validated one.
+
+## The fix pattern
+
+Move the gate into the artifact the enforcing actor actually reads:
+- **Code path** → put the guard *in the function that performs the irreversible action* (e.g. gate the
+  writeback candidate generator on `provenance == verified`, not in a doc that describes it).
+- **Multi-runtime orchestration** → put orchestration gates in a **model-agnostic** file every
+  runtime loads (`AGENTS.md`), not in a Claude-only `CLAUDE.md`. A non-Claude orchestrator that never
+  reads `CLAUDE.md` otherwise gets the role without the governance.
+
+## Verification (how to know the locality fix worked)
+
+A **blind target-tier sim** is the honest check: feed the enforcing actor ONLY the file/path it
+actually loads (e.g. `AGENTS.md` alone, no `CLAUDE.md`) and present a trap the gate should catch
+(e.g. a high-confidence but unverified finding to auto-write). Pre-fix the actor has no basis to
+refuse; post-fix it refuses, citing the now-local gate. The behavioral delta *is* the proof of
+locality — review alone cannot show it (review reads all files; the runtime does not).
+
+## Relationship to other FH assets
+
+- **steel-quench** carries this as a Wave-1 attack angle ("Gate-locality — is every safety gate
+  readable by the actor that must enforce it?").
+- **judge-robustness / mechanical-anchor** (`[[feedback_judge_robustness_mechanical_anchor]]`) — the
+  sibling principle for *verdict* placement; gate-locality is for *gate* placement.
+- **Non-Model Ground** — multi-runtime orchestration is exactly where gate-locality bites, because
+  different runtimes load different files.

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

@@ -0,0 +1,104 @@
+---
+name: goal-quench-anthropic-issue
+description: Draft Anthropic GitHub issue — native /goal token budget + quality verification hook. Reference for when arXiv number is confirmed.
+type: reference
+date: 2026-05-31
+tags: [goal, anthropic, feature-request, token-budget, quality-gate]
+---
+
+# [Feature Request] /goal — native token budget control + quality verification hook
+
+## Summary
+
+`/goal` is powerful but ships two structural gaps: no token budget enforcement and a binary completion evaluator (Haiku yes/no) with no quality signal. This issue proposes three native flags to close these gaps, with a userspace proof-of-concept as reference.
+
+---
+
+## Problem
+
+### 1. Token explosion with no mid-run intervention
+
+`/goal` runs until Haiku says "done" or context is exhausted. There is no mechanism to:
+- Set a token ceiling before the run
+- Intervene at a percentage threshold (e.g., 80% consumed)
+- Save and checkpoint progress when budget runs low
+
+Real-world symptom: users report running `/goal "finish all of this"`, going to sleep, and waking to a fully exhausted context with no recovery path for incomplete work.
+
+### 2. Completion ≠ quality
+
+Haiku's binary evaluator (`done? yes/no`) checks whether the stated goal condition is satisfied — not whether the output is correct, well-structured, or regression-free.
+
+A session can reach `done = yes` while having introduced bugs, phantom references, or broken existing behavior. There is no hook for a quality gate on the completion verdict.
+
+### 3. No checkpoint / resume
+
+When budget exhaustion forces a stop, there is no structured record of what was completed vs. what remains. The next session starts cold.
+
+---
+
+## Proposed Native Flags
+
+### `--budget <N>`
+
+Enforce a token ceiling for the `/goal` session.
+
+Behavior:
+- At 70% of `N`: surface a warning to the user — "Budget at 70%. Recommend re-prioritizing remaining tasks."
+- At 85% of `N`: pause the session. Prompt: "Budget at 85%. Options: (a) continue / (b) reduce scope / (c) stop and save."
+- At 95% of `N`: force stop. Commit completed work. Output structured summary: `Completed: [...] | Remaining: [...]`
+
+### `--verify <command>`
+
+Run a shell command when Haiku returns `done = yes`. Accept the completion verdict only if the command exits 0.
+
+```bash
+# Example: test suite must pass before /goal accepts "done"
+/goal "all tests pass" --verify "npm test"
+
+# Example: FH quality gate before accepting completion
+/goal "refactor complete" --verify "claude -p 'run pipeline-conductor --quick'"
+```
+
+This separates the concerns that a single evaluator cannot serve simultaneously:
+- **Haiku**: completion detection (fast, cheap, every turn)
+- `--verify` command: quality gate (once, on completion, user-defined)
+
+The same principle that motivated separating the Haiku evaluator from Claude's self-assessment (avoiding cognitive bias) applies here: the completion judge should not also be the quality judge.
+
+### `--checkpoint`
+
+Auto-commit on structured sub-goal boundaries. Requires Haiku to output sub-goal markers (not just yes/no), which is a separate RFC — listed here for completeness.
+
+---
+
+## Reference Implementation
+
+**forge-harness `goal-quench`** implements a userspace version of `--budget` + `--verify` using:
+- Pre-run: `token-budget-gate` skill estimates cost and sets thresholds
+- Mid-run: thresholds injected as session instructions (Claude self-enforces)
+- Post-run: Stop hook detects `/goal` completion → triggers `pipeline-conductor --quick`
+
+Limitations of the userspace approach (why native support is needed):
+- Mid-run token ceiling cannot be hard-enforced without native hook
+- Stop hook cannot invoke Claude recursively (verification triggers on next session, not immediately)
+- Checkpoint requires manual commit — no structured sub-goal output from Haiku
+
+**Paper reference**: forge-harness: A Meta-Harness Engineering Platform for Terminal-Native Claude Code Workflows. Zenodo DOI: 10.5281/zenodo.20397566. arXiv: [pending number].
+
+---
+
+## Adoption signal
+
+`/goal` was introduced in Claude Code Week 20 (2026-05-11), absorbing the community `claude-goal` project (Stop hook implementation) 11 days after OpenAI Codex CLI v0.128.0 shipped a similar feature. Community demand is established. This request addresses the production-readiness gap that community implementations cannot close without native runtime access.
+
+---
+
+## Related issues / PRs
+
+- `claude-goal` (community Stop hook implementation): [link if available]
+- OpenAI Codex CLI `/goal` reference: v0.128.0 release notes
+
+---
+
+*Drafted: 2026-05-31. Submit after arXiv number confirmed.*

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

@@ -0,0 +1,136 @@
+# Harness 6-Axis Framework
+
+> Top-level meta-framework for forge-harness operations. The 6 axes form a decision tree that governs all harness-level work — from initial structure through continuous improvement.
+
+**Core principle (field harness)**: "A good harness gets simpler over time. If it's getting more complex, something is wrong."
+
+**Meta-harness variant**: A good meta-harness *optimizes* over time — complexity is justified when it earns its scope. Red flags: orphaned skills (never invoked), redundant overlap (two skills doing the same thing), decorative structure (exists but doesn't change behavior). Complexity itself is not the warning signal.
+
+**Completeness model (frame-wise ultimate)**: A harness is never *finally* complete — it is **frame-wise ultimate**. A *frame* is the scope one verification cycle can currently see: per-asset, an edit-manifest RECORD (Axis 3) → verify (Axis 5) cycle; for FH-as-a-whole, a release/version milestone (cf. a model's knowledge cutoff = its release frame's timestamp). A frame is *closed* — ultimate **for that frame** — when every **visible** gap is resolved or **named**: a named gap is evidence the frame closed (you saw the edge), not evidence against it; the only signal of incompleteness is an **un-named** gap. This reframes the existing completion-claim discipline (Axis 5 before "done", residuals declared) — growth is not the opposite of completeness but its **ladder**: Axis 6 carries one frame's closure into the next frame's baseline. **Two guards keep this honest, not self-congratulatory:** (1) never declare a frame closed before the gap-surfacing pass (Axis 5) has run — premature closure (e.g. "downloads ≠ validated usage"); (2) the verdict "are all *visible* gaps named?" is **judged, so it is adversarially paired** (Axis 5's challenger, or an external sister-GT) — never self-asserted, because an un-named gap is invisible *to the self-judge by construction*; only a non-self pass expands what is visible (mechanical-anchor / Non-Model-Ground principle, §Scope Hierarchy's no-self-commit kin). An *irreducible* gap (visible but unclosable — e.g. the 4-axis gate's autonomous-runner self-verification residual, documented honest in CLAUDE.md §FH 4-Axis Gate) closes its frame **at the ceiling**; the next frame opens only when a new capability changes what is visible.
+
+---
+
+## The 6 Axes
+
+| Axis | Name | Question it answers |
+|:---:|---|---|
+| **1** | **Structure** | Where does this work live? (hub vs. project, rules vs. skills, knowledge vs. tracks) |
+| **2** | **Context** | What does the AI need to know before starting? (session card, CATALOG, relevant docs) |
+| **3** | **Plan** | What is the intended change and its predicted impact? (edit-manifest RECORD) |
+| **4** | **Execute** | What is the minimal, reversible action? (direct edit, agent dispatch, parallel dispatch) |
+| **5** | **Verify** | Did the change do what was predicted? (regression guard, adversarial, source-grounding) |
+| **6** | **Improve** | What pattern is worth keeping? (harvest-loop, field-harvest, compounding loop) |
+
+---
+
+## Decision Tree (Condensed)
+
+```
+New work arrives
+    │
+    ▼ Axis 1 — Structure
+    Where does this live?
+    ├── Hub meta (rules/skills/templates) → FH 4-axis auto-gate applies
+    ├── Field project → route via Agent dispatch or direct edit
+    └── Cross-project knowledge → knowledge/shared/
+
+    ▼ Axis 2 — Context
+    What must the AI know?
+    ├── Read session_card (reference_next_session_starter.md)
+    ├── Read CATALOG.md → candidate files only
+    └── Load LOCAL_SKILL_REGISTRY if cross-project dispatch
+
+    ▼ Axis 3 — Plan
+    What will change?
+    └── edit-manifest RECORD entry: branch, change, predicted_impact, verify_next
+
+    ▼ Axis 4 — Execute
+    Minimum viable action:
+    ├── Direct edit (simple, known file, absolute path)
+    ├── Single Agent dispatch (field task, one project)
+    └── Parallel Agent dispatch (2+ independent tasks — no asking, just dispatch)
+
+    ▼ Axis 5 — Verify
+    Did it work?
+    ├── Axis 1 (backward): regression_guard.sh
+    ├── Axis 2 (adversarial): steel-quench
+    ├── Axis 3 (forward): phantom-quench
+    ├── Axis 4 (record): confirm edit-manifest entry exists
+    └── Before claiming "done": attach (a) evidence (b) failure-checks run
+        (c) residual risk — bare "completed" does not pass (see Completion-claim discipline)
+
+    ▼ Axis 6 — Improve
+    Worth keeping as a pattern?
+    ├── 3+ repeats → skill-candidate tag → field-harvest
+    ├── Session end → harvest-loop (weekly cycle)
+    └── Compounding: hub_compounding_loop.md
+```
+
+---
+
+## Axis 5 — FH 4-Axis Verification Gate (detail)
+
+Applies automatically when any FH asset is modified (SKILL.md, rules, templates, CLAUDE.md, substantive knowledge/ docs).
+
+| Gate axis | Tool | Class | What it catches |
+|---|---|---|---|
+| **Backward** | `regression_guard.sh` | mandatory-pass | Critical section loss, broken refs, syntax errors, line reduction |
+| **Adversarial** | `steel-quench` | judged | Trigger phrase collisions, design attack surface, over-engineered steps |
+| **Forward** | `phantom-quench` | judged | Phantom references, paths that don't exist, stale external links |
+| **Record** | `edit-manifest RECORD` | mandatory-pass | Logs predicted impact — closes the predict-verify loop |
+
+**Check classes**: every verify check is one of three classes — **mandatory-pass**
+(deterministic; blocks on fail), **measured** (quantitative; tracked, not blocking alone —
+e.g. `token-budget-gate`, goal-quench calibration), **judged** (LLM-judge emitting verdict +
+cited evidence + a corrective action — a judge score without a fix path is unactionable, and
+self-judges grade leniently). **Judged rule**: a judge verdict alone never passes — it must be
+paired with adversarial re-verification (`steel-quench` / `verify-bidirectional`), and its
+cited evidence is itself subject to `phantom-quench`. (Taxonomy adapted from external
+supervisor-loop discourse, 2026-06; FH adds the judged-pairing rule and evidence
+re-verification, which the source leaves open.)
+
+**Completion-claim discipline** (judged-class sharpening): a "done" / "passed" claim is itself a judged
+verdict and must carry three things, not just an assertion — **(a) an evidence artifact** (the output,
+diff, or run that shows it), **(b) the enumerated failure-checks actually run** (which negative cases
+were tested, not only that it "works"), and **(c) the explicit residual risk** (what could still be
+wrong). A bare "completed" with none of these is an ungrounded judge verdict and does not pass. Each of
+(a)–(c) must be **non-vacuous** — a named artifact, an enumerated case list, and a specific risk; "it
+works" / "tested" / "none known" are vacuous fills and fail the discipline (same non-vacuity bar as the
+CLAUDE.md §marker rule: a recorded verdict/count, not "it ran"). Bounded scope: (b) means the negative
+cases you *actually ran*, not all conceivable ones; (c) means the one or two risks you can name now, not
+an exhaustive proof of safety. Applies to every skill's Done When and to `goal-quench` /
+`pipeline-conductor` completion gates. (Harvested as independent-convergence reinforcement from sister
+assets — oh-my-claudecode "Ralph" Done-When + book/19689's verification-before-completion-claim theme;
+cross-audit `tracks/_audit/session_2026_06_14_wikidocs-deep-sweep.md`.)
+
+**Hard gate**: git pre-commit hook (`templates/.git-hooks/pre-commit`) blocks commit until marker + manifest entry exist.
+
+**Lightweight exception** (Axis 1 + 4 only): sessions where zero SKILL.md/rules/templates files changed.
+
+---
+
+## Scope Hierarchy
+
+```
+Hub common principles (CLAUDE.md)
+    └── Project CLAUDE.md
+            └── Domain session rules (.claude/rules/session.md)
+```
+
+Lower levels cannot override higher. AI contribution → PR proposal only (no direct commit to shared repos without explicit user approval).
+
+---
+
+## Related
+
+- `harness_design_decision_lens.md` — orthogonal companion: the 7 architectural-bet decisions (which design point at Axis 1 / Axis 4) + default-bias checklist + scaffolding-removal method
+- `crucible_mode.md` — total-immersion absorption stance: chains Axis 5 (the melt) + Axis 6 (the rebirth) with an unmeltable identity core; used when a whole corpus on a core FH axis is absorbed
+- `hub_compounding_loop.md` — Axis 6 automation (weekly/monthly/quarterly cycles)
+- `ai_dialogue_playbook.md` — Axis 2 dialogue principles (how to ask, delegate, record)
+- `claude_code_runtime_flow.md` — Axis 4 runtime behavior (chronological session flow)
+- `.claude/rules/operations.md` — Sub-agent operations, weekly cycle detail
+
+**External sibling (independent convergence)**
+
+- arXiv:2603.25723 (*Natural-Language Agent Harnesses*, NLAH) — external academic sibling that independently converges on the same core thesis: a harness control layer can be an executable natural-language object, not code. NLAH measures the natural-language-harness form empirically; FH governs and compounds it.
+- arXiv:2606.06324 (*HarnessFix / ETCLOVG*, 2026-06) — sibling on the **orthogonal** axis: where NLAH and FH describe the harness as a *process/control* object, HarnessFix supplies a *component taxonomy* of what a deployed harness contains (7 layers — Execution · Tooling · Context · Lifecycle · Observability · Verification · Governance). Its **V layer maps onto FH's Axis-5 gate on 3 of its 4 functions** (intermediate validation → steel/phantom-quench · final-output eval → completion-claim discipline · regression testing → regression_guard); its *readiness-check* function maps to FH pre-flight gates (install-doctor / asset-placement-gate) that sit outside Axis-5. Its named **Observability** layer is a structural axis FH lacks — FH's nearest coverage is *retrospective audit* (weekly_audit, subagent_invocations_log), not runtime observability (import candidate for `harness-doctor`). Cross-audit: `tracks/_audit/session_2026_06_19_harnessfix-etclovg-cross-audit.md`.

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

@@ -0,0 +1,108 @@
+# Harness Design-Decision Lens
+
+> A complement to `harness_6axis_framework.md`. The 6-axis framework is a **lifecycle** decomposition —
+> it answers *when, in the flow of a piece of work*, each concern applies (structure → context → plan →
+> execute → verify → improve). This lens is **orthogonal**: it answers *which architectural bet to place*
+> at Axis 1 (Structure) and Axis 4 (Execute), where the 6-axis tree says "route it" but not "which design
+> point." Use the two together — the 6-axis says *which stage*; this lens says *which trade-off setting*.
+>
+> **Open this doc when** you are about to add agents, tools, permissions, or harness thickness — or when
+> the 6-axis tree says "route it" (Axis 1 / Axis 4) but not *which way*. For lifecycle questions (what
+> stage am I in, what must I verify), stay in the 6-axis framework.
+
+**Provenance (independent-convergence harvest — not clone-and-own):** the decision-table framing was
+harvested from the sister asset `wikidocs.net/book/19689` 「하네스 엔지니어링 백과사전」 Ch12 (governor
+source-closed 2026-06-14; cross-audit `tracks/_audit/session_2026_06_14_wikidocs-deep-sweep.md`). **The
+single net-new increment from the harvest is the orthogonal-bets *framing* itself** — presenting harness
+architecture as ~7 trade-off axes set against the 6-axis lifecycle. The governor source-close ruled the
+individual decisions, the contrarian checklist, and the scaffolding-removal method **ALREADY-HAVE** (FH
+embodies them — see column 3 and the `measured`/judged check classes). They are reproduced below only to
+make the already-placed bets *explicit and operational in one place*, not as novel imports. Where this
+doc restates an existing FH principle, it says so.
+
+---
+
+## The seven decisions (architectural bets)
+
+Each is a spectrum, not a right answer. The third column names the FH asset that already embodies the
+bet — so this is a *map of bets FH is already placing*, made explicit, plus the two FH was placing only
+implicitly (agent-count, reasoning-strategy).
+
+| Decision | Spectrum | Where FH already places the bet | "Which point, when" |
+|---|---|---|---|
+| **Agent count** | single ↔ multi-agent | `agent-composer` (single vs parallel dispatch) | Single by default; split only on genuinely independent sub-tasks (agent-composer's per-wave fan-out cap, ≤4). Isolation cost rises with agent count. |
+| **Reasoning strategy** | ReAct (think each step) ↔ plan-then-execute | 6-axis Axis 3 (Plan) → Axis 4 (Execute); `goal-quench` decomposition | Plan-then-execute for parallelizable / known work; ReAct for genuinely exploratory steps. |
+| **Context strategy** | strong compression ↔ rich context | `context-doctor`, compact-before-saturation reflex, layered memory (MEMORY.md index / `memory/*.md` keyword-load / `tracks/` archive) | Compress on long sessions; keep rich context where verification needs the evidence intact (phantom-quench tension). |
+| **Verification** | computational ↔ judged | check-class taxonomy: mandatory-pass / measured / **judged** (`harness_6axis_framework.md` Axis 5) | Prefer computational anchors; a judged verdict never passes alone (judge-robustness rule). |
+| **Permissions** | permissive ↔ restrictive | `mcp_tool_gating` allow / ask / deny; Destructive-Op + Pre-Publish gates | Restrictive on irreversible / external-facing actions; permissive on reversible local work. |
+| **Tool scope** | all tools always ↔ staged minimal | ToolSearch (deferred-tool fetch), `mcp_tool_gating` | Stage tools in; broad always-on exposure degrades selection accuracy. (Vercel measured 17 specialized tools → 80% success vs 2 general-purpose tools → 100%, at lower token + latency: "We removed 80% of our agent's tools", vercel.com/blog/we-removed-80-percent-of-our-agents-tools, accessed 2026-06-14.) |
+| **Harness thickness** | thin (trust model) ↔ thick (control by code/rules) | field principle "simpler over time" vs meta principle "complexity earns its scope" (`harness_6axis_framework.md` Core principle) | FH already holds a *more nuanced* field-vs-meta split than a single thin/thick dial. Thicker buys predictability but encodes "things the model can't do" — assumptions that age as the model improves (design intuition, not a benchmarked claim). |
+
+The decisions are **not independent**: more agents raises the cost of context isolation + verification;
+always-on tools raises the stakes of permission design; a thicker harness raises the carrying cost of
+stale assumptions.
+
+**Orthogonality is partial, not total.** Two of the seven bets — *reasoning strategy* and *verification* —
+are placed *at* a 6-axis stage (Axis 3→4 for reasoning, Axis 5 for verification), so for those the lens
+and the lifecycle touch rather than run perpendicular. The lens is still the right tool for "which setting"
+(plan-vs-ReAct, computational-vs-judged); the 6-axis is the right tool for "at which stage." The orthogonal
+claim holds strongly for the other five bets and loosely for these two.
+
+---
+
+## Default-bias checklist (the contrarian inversions)
+
+> *Already-embodied (governor: ALREADY-HAVE) — restated here as a one-place design-time pass, not a novel
+> import. FH already runs these instincts through `steel-quench` and the meta-harness red-flag scan.*
+
+Four intuitions that feel right while building and fail in operation. Run this as a quick adversarial
+pass on any harness design (it is the design-time analogue of `steel-quench`'s attack lenses):
+
+1. **"More tools = more capable."** Often false — broad tool exposure hurts selection accuracy. Prefer
+   staged, single-purpose tools over a wide general surface.
+2. **"Reason at every step (ReAct always)."** Often false — for parallelizable / known work,
+   plan-then-execute is faster and cheaper.
+3. **"Broader permissions = faster."** False under operations — the cost lands as irreversible mistakes,
+   not saved time. Gate the irreversible.
+4. **"Thicker harness = safer."** True short-term, debt long-term — a thick harness encodes "things the
+   model can't do," and those assumptions age. Safety that does not get revisited becomes a burden.
+
+---
+
+## Scaffolding-removal method (operationalizes "simpler over time")
+
+> *The principle is already FH's (governor: ALREADY-HAVE — 6-axis core principle). What is operationalized
+> here is the **method** the principle left unstated, consistent with FH's `measured` check class.*
+
+FH's core principle states the *goal* — "a good harness gets simpler over time" — but not the *method*.
+A testable one, consistent with FH's verification identity:
+
+> **Remove scaffolding one piece at a time, and compare.** When simplifying, ablate a single support at a
+> time and check what actually holds quality before removing the next. Removing several at once loses the
+> signal of which support was load-bearing.
+
+This is the disciplined form of the meta-harness red-flag scan (orphaned / redundant / decorative units):
+do not bulk-delete suspected-decorative structure — ablate-one, measure, then proceed. It pairs with the
+`measured` check class (the comparison is the measurement).
+
+---
+
+## How it plugs into the 6-axis flow
+
+- **Axis 1 (Structure)** — when deciding where work lives and how it is shaped, consult the seven
+  decisions for the architectural bet, and the default-bias checklist before committing to "more"
+  (agents, tools, permissions, thickness).
+- **Axis 4 (Execute)** — the agent-count and reasoning-strategy decisions set the dispatch shape
+  (direct / single agent / parallel) the 6-axis tree otherwise leaves to habit.
+- **Axis 6 (Improve)** — apply the scaffolding-removal method when the simplification principle fires.
+
+**Check class:** this doc is a *judged* design aid (it informs human/AI design choices, it does not gate
+mechanically). Its adversarial pairing is the default-bias checklist above + `steel-quench` on any design
+it informs — no judge-only path.
+
+---
+
+## Related
+- `harness_6axis_framework.md` — the lifecycle framework this lens complements (Core principle: thickness; Axis 5: check-class taxonomy)
+- `tracks/_audit/session_2026_06_14_wikidocs-deep-sweep.md` — the governor-closed cross-audit this harvest came from
+- `.claude/rules/auto_project_mapping.md` — Full-Harness Mode, where thickness/permission bets are placed per project