harness-everything 0.19.0 → 0.19.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.19.0",
+      "version": "0.19.1",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.19.0",
+  "version": "0.19.1",
   "author": {
     "name": "Miya Daniel"
   },

package/AGENTS.md

@@ -40,9 +40,10 @@ The retained [OpenCode evidence](benchmarks/results/live-host/opencode-2026-09-1
 7. **Runtime/workflow claims are generated facts.** `package.json`, `.nvmrc`, Dockerfile, and active workflows feed `scripts/repository-contract.js`; run `npm run docs:sync` after relevant changes.
 8. **CHANGELOG.md keeps pending human-authored notes under `[Unreleased]`.** Semantic-release owns stable headings/tags/release notes.
 9. **Conventional Commit type is release input.** Breaking→major; `feat`→minor; `fix`/`perf`/`refactor`/`build`/`revert`→patch; docs/test/ci/style/chore do not release by themselves.
-10. **Selected workflow is planning guidance; reasoning and execution stay flexible.** Before omitting a suggested skill, read/evaluate its complete `SKILL.md` flow. Do not turn routing into a universal TODO/TDD/Fable sequence. Missing workflow evidence should produce a reminder, not a persistent Harness lock.
+10. **Selected workflow is a semantic contract; tactics remain flexible.** Suggested skills MUST be read/evaluated before omission; applicable skill core contracts MUST be followed, while not-applicable requires a flow-grounded reason. Selected-topology required obligations MUST resolve. Missing host evidence may produce reminders, not a persistent Harness lock.
 11. **User-visible Harness Status is mandatory for non-trivial work.** Render one readable Markdown block headed `### 🚦 Harness Status`, with bullet-aligned bold `Current`, `Read / Evidence`, `Next`, plus optional `Risk / Blocked`; use nested evidence bullets when useful. Emit it before substantive execution, after major phases, on direction changes, during long work at meaningful boundaries, and before final completion. The routing checkpoint is internal source state, not a second user-facing block. This semantic MUST does not create a hard lock.
-12. **Prefer Git worktree isolation for major mutation.** Read-only discovery may stay in the bound repository. Tier 3 / Fable source and artifact changes should use a verified linked worktree when practical; failure to create one is a prominent risk reminder, not a Harness-owned deadlock. See [workflow-runtime.md](docs/workflow-runtime.md).
+12. **Tier-3/Fable isolation disposition is mandatory before broad mutation.** Use/reuse a verified linked Git worktree, or record an explicit degraded fallback when isolation is unavailable or the user explicitly chooses to stay in place. Ordinary isolation SHOULD be used when it materially reduces collision/risk. Failure to isolate is a visible semantic gap, not a Harness-owned deadlock. See [workflow-runtime.md](docs/workflow-runtime.md).
+13. **Use contract strength deliberately.** MUST = required semantic obligation; SHOULD = expected default with an evidence-based exception; MAY = optional optimization. Do not use recommend/prefer/advisory/guidance to weaken a MUST. See [philosophy.md](docs/philosophy.md#contract-strength-must--should--may).
 
 ## Verification Before You Claim Done
 

package/CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.19.1](https://github.com/dyphn1/Harness-everything/compare/v0.19.0...v0.19.1) (2026-09-21)
+
 ## [0.19.0](https://github.com/dyphn1/Harness-everything/compare/v0.18.1...v0.19.0) (2026-09-21)
 
 ### Features

package/README.md

@@ -19,7 +19,7 @@ AI coding agents are highly capable, but they struggle with self-regulation, env
 
 Harness acts as an automated system supervisor. It remains completely silent and out of the way, intervening only when execution boundaries are violated or failures are detected.
 
-Harness deliberately follows a **minimal rails, maximum freedom** design: the runtime establishes routing context, observes verification evidence, and emits lightweight reminders. It does not hard-stop work on iteration/revision/replan/worker counts. The one cognitive hard boundary is Rule of 3: three matching failures pause mutation for a zoom-out reflection. When routing emits skill suggestions, it adds one conditional rail: **evaluate before skip**. The agent must read each suggested skill's `SKILL.md` entry/basic flow before omitting it, but remains free to choose, combine, reorder, or skip execution after that evaluation.
+Harness deliberately follows a **minimal rails, maximum freedom** design: semantic obligations are explicit, while runtime observation remains lightweight and mostly fail-open. It does not hard-stop work on iteration/revision/replan/worker counts. The one cognitive hard boundary is Rule of 3: three matching failures pause mutation for a zoom-out reflection. Router suggestions are conditional by applicability, not optional by default: the agent MUST read/evaluate each suggested skill; if applicable, its core contract MUST be followed, and if not applicable a flow-grounded reason MUST be retained. Implementation tactics remain flexible inside those obligations.
 
 ### Comparison: Prompt vs. Skill vs. Harness
 
@@ -48,7 +48,7 @@ The exact "Harness" behavior depends on the installation surface. Claude Code ha
 
 Harness integrates directly into your workspace. There is no heavy daemon, no paid external APIs, and zero configuration required.
 
-**Runtime:** Harness supports **Node.js 22+**. Node.js **24** is the primary/recommended development and CI runtime (`.nvmrc`). The generated current-state runtime/workflow summary is [docs/repository-contract.md](docs/repository-contract.md).
+**Runtime:** Harness supports **Node.js 22+**. Node.js **24** is the primary development and CI runtime (`.nvmrc`). The generated current-state runtime/workflow summary is [docs/repository-contract.md](docs/repository-contract.md).
 
 ```bash
 # Option A: Claude Code plugin (marketplace manifest included)
@@ -73,7 +73,7 @@ npx github:dyphn1/Harness-everything install
 1. **Use the selected surface's real mechanism:** Claude Code hooks, the local OpenAI plugin lifecycle hooks, OpenCode's plugin API, or advisory instructions depending on what you installed.
 2. **Preflight / session context where packaged:** Hook-capable surfaces can inject environment/session context automatically; advisory-only surfaces must not be described as if they do.
 3. **Verification boundary:** Completion claims require objective evidence; whether that boundary is mechanically invoked or explicitly called depends on the host surface.
-4. **Mandatory applicable workflow:** Evaluate each suggested skill's complete `SKILL.md` before omission, then resolve the selected topology with objective evidence. Reasoning and implementation remain flexible; escape applies only to a declared uncovered stage with evidence. Tier 3 / Fable mutation requires a verified Git worktree. See the [workflow runtime contract](docs/workflow-runtime.md) for entry, completion, and host limits. Harness does not impose one universal TODO/TDD/Fable sequence.
+4. **Mandatory applicable workflow:** MUST evaluate each suggested skill's complete `SKILL.md`; applicable core contracts MUST be followed, while not-applicable needs a flow-grounded reason. Selected-topology required obligations MUST resolve with objective evidence. Reasoning and implementation remain flexible; escape applies only to declared uncovered scope with evidence. Tier-3/Fable broad mutation MUST resolve isolation: verified linked worktree or explicit degraded fallback. See the [workflow runtime contract](docs/workflow-runtime.md). Harness does not impose one universal TODO/TDD/Fable sequence.
 5. **Unified user-visible status:** For non-trivial software/project work, the agent MUST render one scannable Markdown `### 🚦 Harness Status` block with bold bullet labels for `Current`, `Read / Evidence`, `Next`, plus optional `Risk / Blocked`; multiple evidence items may use nested bullets. Use it at major phase/direction boundaries and before final completion. The routing checkpoint remains internal source state. This is a communication contract, not a hard runtime lock.
 
 ### What Gets Installed (and How to Remove It)
@@ -127,7 +127,7 @@ flowchart TD
 ```mermaid
 flowchart TD
     U([User Request]) --> K[Harness Kernel<br/>classify scope + establish invariants]
-    K --> T{Tier recommendation}
+    K --> T{Tier classification}
     T --> S{Suggested skills?}
     S -->|Yes| R[Read each suggested SKILL.md<br/>evaluate flow + applicability]
     S -->|No| A[Agent chooses smallest useful tactic / skill set]
@@ -147,7 +147,7 @@ flowchart TD
     style Gate fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
 ```
 
-The Tier changes the **recommendations**, not the required order. Tier 2 may suggest `tdd`, `todo-driven-workflow`, or `verification-loop`; Tier 3 may suggest Fable or multi-agent capabilities. Suggestions are **mandatory to evaluate and advisory to execute**: read each suggested skill's `SKILL.md` flow before omission, then let the model decide what actually helps.
+The Tier changes task shape and the set of **suggested skills**, not a universal required order. Tier 2 may suggest `tdd`, `todo-driven-workflow`, or `verification-loop`; Tier 3 may select Fable or multi-agent topologies. Every suggestion is **MUST-evaluate**: if its real flow is applicable, the core contract becomes **MUST-follow**; otherwise retain a flow-grounded not-applicable reason. Tactics inside the resulting contract remain model-controlled.
 
 ---
 
@@ -155,7 +155,7 @@ The Tier changes the **recommendations**, not the required order. Tier 2 may sug
 
 Harness operates through six core cognitive concepts:
 
-1. **Kernel Router (`kernel-router.js` + `tier-router.js`):** `tier-router.js` remains the classifier, dynamic-skill detector, and knowledge-guide matcher. `kernel-router.js` is the public runtime boundary: it preserves the classifier result, removes legacy fixed-pipeline instructions, injects the baseline invariants, and adds `evaluate-suggestions-before-skip` whenever domain skills are suggested. Suggestions are mandatory to evaluate by reading their `SKILL.md` entry/basic flow, but advisory to execute after evaluation. This prevents host peer-skill selection or superficial routing summaries from bypassing Harness while preserving agent autonomy. If nothing matches at all — including nothing already kept from the open skills ecosystem — `find-skills` checks `npx skills list` live and, if still nothing, searches `skills.sh`/`npx skills` with explicit approval before installation.
+1. **Kernel Router (`kernel-router.js` + `tier-router.js`):** `tier-router.js` remains the classifier, dynamic-skill detector, and knowledge-guide matcher. `kernel-router.js` is the public runtime boundary: it preserves the classifier result, injects baseline MUST invariants, and adds `evaluate-suggestions-before-skip` whenever domain skills are suggested. Suggestions MUST be evaluated from their real `SKILL.md` flow; an applicable skill's core contract MUST be followed, while not-applicable needs evidence. Selected-topology obligations are also semantic MUSTs, but the runtime generally observes/reminds rather than hard-blocking. This preserves agent autonomy over tactics without allowing confidence to erase the lifecycle. If nothing matches at all — including nothing already kept from the open skills ecosystem — `find-skills` checks `npx skills list` live and, if still nothing, searches `skills.sh`/`npx skills` with explicit approval before installation.
 2. **Guard (`rule-of-3.js`):** The fail-safe circuit breaker. Tracks failure signatures across terminal runs on integration surfaces that package the required lifecycle hooks. If a test or command fails 3 times with the same signature, it locks mutating tools and forces a `zoom-out` reflection: re-verify every assumption with read-only tools, write a fact-checked report, then resume on a fresh diagnosis. A companion `Stop` hook (`stop-gate.js`) emits a non-blocking reminder when edits were never followed by successful verification on hosts where that hook is installed.
 3. **Memory (`state-persist.js`):** Session transaction logging for stateful hook/plugin integrations. Static skills/instructions alone do not create WAL state.
 4. **Reflection (`self-evolve`):** Long-term workspace immunization. Upon task completion, the agent reflects on the root cause of resolved issues, then judges whether the lesson is a simple rule or a reusable, complex pattern: simple rules are appended to local workspace rules (`RULES.md`); genuinely reusable patterns are instead packaged as a dynamic skill (via `skill-creator`'s Dynamic Skill Generation Contract) and registered in `manifest.json` so the Router picks it up in future sessions. Either path is validated by a hermetic self-regression suite before it's persisted.
@@ -172,10 +172,10 @@ The authoritative current matrix is [docs/platform-capabilities.md](docs/platfor
 
 | AI Agent Tool / Surface | Integration Method | Local Target Location | Enforcement claim |
 |---|---|---|---|
-| **Claude Code** | Native lifecycle hooks (`PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`) | `.claude/settings.json`, `.claude/skills/`, `.claude/agents/` | Workflow/productivity guidance is reminder-oriented; Rule-of-3 reflection and explicit permission boundaries may block |
+| **Claude Code** | Native lifecycle hooks (`PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`) | `.claude/settings.json`, `.claude/skills/`, `.claude/agents/` | Semantic workflow contracts are reminder-observed; Rule-of-3 reflection and explicit permission boundaries may block |
 | **OpenCode** | Native plugin module ([`opencode-plugin/index.mjs`](opencode-plugin/index.mjs), install as `harness-enforcement.js`) | `.opencode/plugins/` | **Partial live-host evidence** — project-scope `.js` loading and edit/verification state on OpenCode 1.18.31 (macOS); current workflow/verification behavior is reminder-oriented, with only the third-failure reflection boundary blocking edits |
-| **Codex — general installer path** | Skills + `AGENTS.md` guidance | `AGENTS.md` + repo-scoped `.agents/skills/` | **Advisory/instruction-oriented** where the host only consumes instructions |
-| **Codex / local OpenAI plugin** | `.codex-plugin` package with session, prompt, supported-tool, subagent, and stop hooks plus 26 canonical skills | `.agents/plugins/marketplace.json` → `plugins/harness-everything/` | **Mechanism-tested local guidance plus explicit permission/Rule-of-3 boundaries** for the packaged mappings; live host loading remains unverified |
+| **Codex — general installer path** | Skills + `AGENTS.md` instructions | `AGENTS.md` + repo-scoped `.agents/skills/` | **Instruction/advisory delivery only**; semantic MUST/SHOULD/MAY still applies, without a hard-enforcement claim |
+| **Codex / local OpenAI plugin** | `.codex-plugin` package with session, prompt, supported-tool, subagent, and stop hooks plus 26 canonical skills | `.agents/plugins/marketplace.json` → `plugins/harness-everything/` | **Mechanism-tested local contract observation plus explicit permission/Rule-of-3 boundaries** for the packaged mappings; live host loading remains unverified |
 | **Public OpenAI Skills-only plugin** | Public Skills-only bundle | Generated submission ZIP from `plugins/harness-everything/skills/` | **Skill/workflow behavior only**; no local `.codex-plugin` lifecycle hooks in the public artifact |
 | **Cursor** | Native Project Rules + project skills | `.cursorrules` + `.cursor/skills/` | Advisory only |
 | **GitHub Copilot agent surfaces** | Agent Skills + repository custom instructions | `.github/copilot-instructions.md` + `.github/skills/` | Agent Skills path is documented; no live Harness session or plugin install is verified |
@@ -246,9 +246,9 @@ This repo uses a flat layout (waza/agentskills.io convention). The table below m
 | `skill-creator` | **Meta** | Create new skills from patterns |
 | `skill-style` | **Meta** | Skill authoring style guide |
 | `tdd` | **Skill (Tier 2)** | Test-driven development when executable behavior benefits from it |
-| `to-spec` | **Advisory (Tier 2/3)** | Publish specs from settled conversations |
-| `to-tickets` | **Advisory (Tier 2/3)** | Decompose settled specs into tracked tickets |
-| `todo-driven-workflow` | **Advisory Foundation** | Progress tracking when explicit multi-step state helps |
+| `to-spec` | **Optional (MAY, Tier 2/3)** | Publish specs from settled conversations |
+| `to-tickets` | **Optional (MAY, Tier 2/3)** | Decompose settled specs into tracked tickets |
+| `todo-driven-workflow` | **Optional Foundation (MAY)** | Progress tracking when explicit multi-step state helps |
 | `using-git-worktrees` | **Skill (Tier 2)** | Git worktree concurrency patterns |
 | `verification-loop` | **Skill (Tier 2)** | Select systematic verification evidence; kernel still requires evidence before completion |
 | `verify-before-claim` | **Always-on discipline** | Fact-audit before asserting claims |
@@ -263,7 +263,7 @@ For a deep dive into individual modules and the underlying philosophy, explore o
 
 * [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
 * [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
-* [Guidance and Safety Boundary Diagnostic Flows](docs/enforcement-locks.md): Distinguish reminders from the two intentional blocking boundaries and understand recovery.
+* [Semantic Contracts and Safety Boundary Diagnostic Flows](docs/enforcement-locks.md): Distinguish MUST/SHOULD/MAY obligations from reminder mechanics and the two intentional blocking boundaries.
 * [Platform Capability Matrix](docs/platform-capabilities.md): Canonical current enforcement/install/evidence boundary per surface.
 * [Repository Runtime & Workflow Contract](docs/repository-contract.md): Generated Node/action/workflow/gate state used by consistency CI.
 * [OpenAI / ChatGPT Plugin Packaging](docs/openai-plugin.md): Local Codex/OpenAI plugin packaging plus public Skills-only submission boundary.
@@ -273,7 +273,7 @@ For a deep dive into individual modules and the underlying philosophy, explore o
 
 Fable model selection is documented in [fable-mode/references/model-matrix.md](fable-mode/references/model-matrix.md); the explicit entrypoints are `fable-haiku`, `fable-sonnet`, and `fable-opus`.
 
-Maintainers should follow [RELEASING.md](RELEASING.md) for tag-driven npm releases and record observations in [docs/release-evidence.md](docs/release-evidence.md). Issue #20 is closed (2026-09-10); its coordination history lives in git.
+Maintainers **MUST** follow [RELEASING.md](RELEASING.md) for tag-driven npm releases and record observations in [docs/release-evidence.md](docs/release-evidence.md). Issue #20 is closed (2026-09-10); its coordination history lives in git.
 
 ---
 

package/ci/invariant-routing.test.js

@@ -4,18 +4,18 @@ const fs=require('fs'),path=require('path'),{spawnSync}=require('child_process')
 const ROOT=path.resolve(__dirname,'..');let failed=0;
 function check(c,m){if(c)console.log('  PASS '+m);else{console.error('  FAIL '+m);failed++;}}
 function read(p){return fs.readFileSync(path.join(ROOT,p),'utf8');}
-console.log('=== Guidance-First Routing Contract ===');
+console.log('=== Semantic Contract-Strength Routing Contract ===');
 const kernel=path.join(ROOT,'harness-everything/scripts/kernel-router.js');
 const tier2=spawnSync(process.execPath,[kernel,'add a login endpoint with tests and update the implementation'],{cwd:ROOT,encoding:'utf8'});
 check(tier2.status===0,'kernel router exits successfully');
 check(/RECOMMENDED TIER:\s*Tier 2/i.test(tier2.stdout),'classifier result is preserved');
-check(tier2.stdout.includes('"strategy":"iterative-single"'),'Tier 2 selects iterative-single guidance');
+check(tier2.stdout.includes('"strategy":"iterative-single"'),'Tier 2 selects iterative-single workflow');
 check(tier2.stdout.includes('loop-awareness:'),'iterative work exposes loop-awareness instead of a hard budget');
-check(tier2.stdout.includes('SELECTED WORKFLOW IS GUIDANCE'),'suggested workflow is explicitly guidance');
-check(tier2.stdout.includes('ORCHESTRATION POLICY: Selected topology is planning guidance'),'orchestration policy is guidance-first');
-check(tier2.stdout.includes('WORKFLOW GUIDANCE (ADVISORY WHEN SELECTED)'),'kernel emits advisory workflow guidance');
-check(tier2.stdout.includes('missing isolation is a strong reminder, not a Harness lock'),'worktree guidance is non-blocking');
-check(!tier2.stdout.includes('WORKFLOW EXECUTION CONTRACT (MANDATORY'),'old mandatory execution contract is absent');
+check(tier2.stdout.includes('WORKFLOW SKILLS (APPLICABILITY MUST BE RESOLVED)'),'skill applicability is explicitly mandatory');
+check(tier2.stdout.includes('ORCHESTRATION POLICY: Selected-topology required obligations and applicable skill core contracts are semantic MUSTs'),'orchestration policy preserves semantic MUST obligations');
+check(tier2.stdout.includes('WORKFLOW SEMANTIC CONTRACT (NON-BLOCKING OBSERVATION)'),'kernel separates semantic contract from non-blocking observation');
+check(tier2.stdout.includes('Tier 3 / Fable broad mutation MUST resolve isolation'),'worktree isolation disposition is a semantic MUST');
+check(!tier2.stdout.includes('SELECTED WORKFLOW IS GUIDANCE'),'old planning-guidance label is absent');
 check(!tier2.stdout.includes('unavailable isolation means BLOCKED'),'old worktree hard-block wording is absent');
 check(tier2.stdout.includes('evaluate-suggestions-before-skip'),'skill suggestions still require evaluation before omission');
 check(tier2.stdout.includes('visible-status-updates'),'workflow plan carries mandatory user-visible status invariant');
@@ -31,46 +31,69 @@ check(tier2.stdout.includes('semantic communication MUST, not a hard execution l
 const tier3=spawnSync(process.execPath,[kernel,'audit the entire repository architecture and coordinate multiple modules'],{cwd:ROOT,encoding:'utf8'});
 check(tier3.status===0,'Tier 3 routing exits successfully');
 check(/RECOMMENDED TIER:\s*Tier 3/i.test(tier3.stdout),'macro task remains Tier 3');
-check(tier3.stdout.includes('using-git-worktrees'),'Tier 3 still recommends worktree guidance');
-check(tier3.stdout.includes('WORKFLOW GUIDANCE (ADVISORY WHEN SELECTED)'),'Tier 3 workflow remains advisory');
+check(tier3.stdout.includes('using-git-worktrees'),'Tier 3 still routes the worktree skill');
+check(tier3.stdout.includes('Tier 3 / Fable broad mutation MUST resolve isolation'),'Tier 3 requires an isolation disposition without a hard lock');
 
 const hs=read('harness-everything/SKILL.md');
-check(/workflow state and numeric limits guide; they do not hard-stop execution/i.test(hs),'Harness skill states non-blocking workflow contract');
+check(/required obligations are MUST; tactics MAY adapt/i.test(hs),'Harness skill separates required obligations from adaptable tactics');
 check(/only Rule-of-3 reflection and explicit user\/host permission boundaries may block/i.test(hs),'Harness skill names the only intentional blocking boundaries');
-check(/Surface status.*MUST render.*Harness Status/i.test(hs)&&/bold bullets/i.test(hs)&&/Read \/ Evidence/i.test(hs),'Harness skill requires the readable unified user-visible status');
+check(/Surface status \(MUST\).*Harness Status/i.test(hs)&&/Read \/ Evidence/i.test(hs),'Harness skill requires the readable unified user-visible status');
 check(read('plugins/harness-everything/skills/harness-everything/SKILL.md')===hs,'Harness skill mirror matches');
 
 const wt=read('using-git-worktrees/SKILL.md');
-check(/safer in a linked worktree/i.test(wt),'worktree skill strongly recommends isolation');
+check(/Tier 3 \/ Fable \(MUST resolve\)/i.test(wt)&&/explicit degraded fallback/i.test(wt),'worktree skill requires isolation disposition but permits degraded fallback');
 check(!/Creation\/entry failure => `BLOCKED`/i.test(wt),'worktree creation failure is not a cognitive blocked state');
 check(read('plugins/harness-everything/skills/using-git-worktrees/SKILL.md')===wt,'worktree skill mirror matches');
 
 const triage=read('harness-everything/references/triage-and-tiers.md');
-check(/Guidance-first workflow/i.test(triage),'triage reference uses guidance-first policy');
+check(/Contract-first lifecycle/i.test(triage),'triage reference uses contract-first policy');
 check(/User-visible status contract/i.test(triage)&&/Harness Status/i.test(triage)&&/MUST/i.test(triage),'triage defines the mandatory unified status contract');
 check(read('plugins/harness-everything/skills/harness-everything/references/triage-and-tiers.md')===triage,'triage mirror matches');
 
-for(const p of ['docs/routing.md','docs/architecture.md','docs/philosophy.md','docs/mechanism-first-skill-mesh.md']){
- const t=read(p); check(/guidance/i.test(t),'current doc '+p+' describes guidance');
+for(const p of ['docs/routing.md','docs/architecture.md','docs/philosophy.md']){
+ const t=read(p); check(/MUST/i.test(t)&&/MAY/i.test(t),'current doc '+p+' preserves explicit semantic strength');
 }
 for(const p of ['docs/routing.md','docs/architecture.md','docs/workflow-runtime.md']){
  const t=read(p); check(/Harness Status/i.test(t)&&/MUST/i.test(t),'current doc '+p+' defines mandatory user-visible status');
 }
+const philosophy=read('docs/philosophy.md');
+check(/Contract Strength: MUST \/ SHOULD \/ MAY/i.test(philosophy),'philosophy defines canonical MUST/SHOULD/MAY strength');
+for(const phrase of [
+  'Route before software/project execution',
+  'Read/evaluate every suggested skill before omission',
+  'Resolve selected-topology invariants/stages/checks/synthesis/verification',
+  'Discover relevant environment/host facts',
+  'Resolve Tier-3/Fable isolation before broad mutation',
+  'Numeric iteration/revision/replan/worker values',
+  'Durable memory writes'
+]){
+  check(philosophy.includes(phrase),'contract-strength audit classifies '+phrase);
+}
+check(!/Applicable workflow is guidance:/i.test(philosophy),'old ambiguous philosophy wording is removed');
+
 const advisory=read('scripts/lib/advisory-text.js');
-check(/selected workflow topology.*planning guidance/i.test(advisory),'installer advisory text keeps workflow non-blocking');
+check(/Selected-topology required obligations are MUSTs/i.test(advisory)&&/numeric.*MAY guide planning/i.test(advisory),'instruction-only installer preserves MUST/MAY semantics');
 check(/USER-VISIBLE STATUS \(MUST\)/i.test(advisory)&&/### 🚦 Harness Status/i.test(advisory)&&/\*\*Read \/ Evidence:\*\*/i.test(advisory),'instruction-only installers carry the readable mandatory status contract');
 check(/Rule of 3/i.test(advisory)&&/Permission boundaries are separate/i.test(advisory),'installer text preserves Rule-of-3 and permission boundaries');
 check(read('plugins/harness-everything/scripts/lib/advisory-text.js')===advisory,'OpenAI advisory mirror matches');
 
 const agents=read('AGENTS.md');
-check(/Selected workflow is planning guidance/i.test(agents),'repository agent contract is guidance-first');
+check(/Selected workflow is a semantic contract/i.test(agents),'repository agent contract is contract-first');
 check(/User-visible Harness Status is mandatory/i.test(agents)&&/### 🚦 Harness Status/i.test(agents)&&/nested evidence bullets/i.test(agents),'repository agent contract requires readable unified user-visible status');
-check(/Prefer Git worktree isolation/i.test(agents),'repository worktree rule is a recommendation');
+check(/Tier-3\/Fable isolation disposition is mandatory/i.test(agents)&&/degraded fallback/i.test(agents),'repository worktree rule requires disposition without hard lock');
+
+const envSkill=read('environment-detection/SKILL.md');
+check(/semantic \*\*MUST\*\*/i.test(envSkill)&&/environment-sensitive/i.test(envSkill),'environment discovery is a conditional semantic MUST');
+check(read('plugins/harness-everything/skills/environment-detection/SKILL.md')===envSkill,'environment skill mirror matches');
+
+const commitSkill=read('git-commit/SKILL.md');
+check(/MUST.*git diff --cached/i.test(commitSkill)&&/SHOULD.*split/i.test(commitSkill),'commit skill separates staged-diff MUST from split SHOULD');
+check(read('plugins/harness-everything/skills/git-commit/SKILL.md')===commitSkill,'git-commit skill mirror matches');
 
 const hooks=JSON.parse(read('hooks/hooks.json'));
 check((hooks.hooks.PreToolUse||[]).some(e=>e.id==='harness:pre:workflow-gate'),'Claude packages workflow reminder hook');
 check((hooks.hooks.PreToolUse||[]).some(e=>e.id==='harness:pre:rule-of-3'),'Claude preserves Rule-of-3 boundary');
 check((hooks.hooks.PreToolUse||[]).some(e=>e.id==='harness:pre:action-gate'),'Claude preserves action permission gate');
 
-console.log('\n'+(failed===0?'PASS':'FAIL')+': guidance-first routing contract ('+failed+' failures)');
+console.log('\n'+(failed===0?'PASS':'FAIL')+': semantic contract-strength routing contract ('+failed+' failures)');
 process.exit(failed===0?0:1);

package/ci/mechanism-2af-worktree-isolation.test.js

@@ -16,10 +16,10 @@ try{
  fs.writeFileSync(path.join(dir,'workflow-run.json'),JSON.stringify({schemaVersion:1,sessionId:'worktree-guidance',tier:'tier3',strategy:'iterative-single',state:'active'}));
  const primary=runGate('Write',repo,{file_path:path.join(repo,'src.js'),content:'x'});
  check(primary.status===0,'Tier-3 primary-tree mutation is not hard-blocked',primary.stderr);
- check(/worktree/i.test(primary.stderr),'Tier-3 primary-tree mutation emits worktree guidance',primary.stderr);
+ check(/semantic MUST/i.test(primary.stderr)&&/worktree/i.test(primary.stderr),'Tier-3 primary-tree mutation emits mandatory isolation disposition without blocking',primary.stderr);
  const mutator=runGate('Bash',repo,{command:'git status --short && rm -rf src'});
  check(mutator.status===0,'mutation-shaped shell command remains available',mutator.stderr);
- check(/worktree/i.test(mutator.stderr),'mutation-shaped shell command receives worktree guidance',mutator.stderr);
+ check(/semantic MUST/i.test(mutator.stderr)&&/worktree/i.test(mutator.stderr),'mutation-shaped shell command receives the same isolation contract',mutator.stderr);
  const readOnly=runGate('Bash',repo,{command:'git status --short'});
  check(readOnly.status===0,'read-only discovery remains available');
  const create=git(repo,['worktree','add',linked,'-b','guidance-test']);check(create.status===0,'linked worktree fixture creates',create.stderr);
@@ -37,4 +37,4 @@ try{
  check(corrupt.status===0,'corrupt workflow state fails open',corrupt.stderr);
 }finally{fs.rmSync(temp,{recursive:true,force:true});}
 if(failed)process.exit(1);
-console.log('PASS: worktree isolation is guidance, not a cognitive lock');
+console.log('PASS: worktree isolation is a semantic MUST disposition, not a cognitive lock');

package/ci/mechanism-2ag-router-worktree-contract.test.js

@@ -18,6 +18,7 @@ assert.strictEqual(tier3.strategy, 'fable-staged');
 assert.ok(tier3.requiredInvariants.includes('isolated-worktree-before-mutation'), 'Tier 3 plan must carry mutation isolation invariant');
 assert.ok(tier3.suggestedSkills.includes('using-git-worktrees'), 'Tier 3 plan must surface the worktree workflow');
 assert.strictEqual(tier3.workspace.required, false, 'Git worktree isolation must remain distinct from durable multi-agent workspace state');
+assert.strictEqual(tier3.mutationIsolation.onUnavailable, 'degraded', 'unavailable isolation records an explicit degraded fallback instead of a cognitive hard block');
 
 const tier2 = router.buildRouterContract({
   routingStatus: 'ok',

package/ci/mechanism-2an-workflow-obligations.test.js

@@ -47,6 +47,7 @@ let workflow = readJson(workflowFile);
 let obligations = readJson(obligationFile);
 check(workflow.tier === 'tier2' && workflow.strategy === 'iterative-single', 'Tier 2 receives a preliminary iterative-single route');
 check(workflow.state === 'pending', 'selected Tier 2 workflow begins pending');
+check(workflow.guidance?.mode === 'semantic-contract', 'persisted workflow records semantic-contract mode rather than advisory-workflow');
 check(obligations.phase === 'planning', 'Tier 2 immediately materializes a planning contract');
 check(obligations.obligations.map(item => item.id).join(',') === 'decompose,compose', 'planning starts with decompose then compose');
 check(obligations.requirements.length === 0, 'requirements begin empty instead of being invented by the router');

package/ci/mechanism-33-issues-205-207.test.js

@@ -28,8 +28,8 @@ check((dockerVerify.match(/\$STATE_DIR\//g) || []).length >= 10,
   '#205 docker verifier routes all state checks through STATE_DIR');
 
 const architecture = fs.readFileSync(path.join(ROOT, 'docs/architecture.md'), 'utf8');
-check(architecture.includes('advisory loop-awareness reminders'),
-  '#206 architecture names loop-awareness as advisory');
+check(architecture.includes('MAY-level loop-awareness planning hints'),
+  '#206 architecture keeps loop-awareness numeric guidance explicitly non-mandatory');
 check(!/\bloop budgets\b/.test(architecture),
   '#206 architecture does not describe retired loop budgets as enforcement');
 

package/ci/openai-plugin-package.test.js

@@ -162,7 +162,7 @@ assert.ok(hooks.hooks.Stop?.length, 'Stop hook missing');
 const hookText = JSON.stringify(hooks);
 assert.match(hookText, /PLUGIN_ROOT/, 'plugin hooks must resolve from PLUGIN_ROOT');
 assert.match(hookText, /commandWindows/, 'plugin hooks need a Windows command override');
-assert.match(hookText, /workflow-gate\.js/, 'plugin hooks must package workflow guidance');
+assert.match(hookText, /workflow-gate\.js/, 'plugin hooks must package workflow contract observation');
 assert.match(hookText, /workflow-stop-gate\.js/, 'plugin hooks must package workflow completion reminders');
 
 const session = spawnSync(process.execPath, [path.join(PLUGIN, 'hooks', 'session-start.js')], { encoding: 'utf8' });
@@ -190,14 +190,14 @@ assert.strictEqual(second.status, 0, second.stderr);
 assert.strictEqual(first.stdout, second.stdout, 'identical routing input must produce identical output');
 assert.match(first.stdout, /RECOMMENDED TIER:\s*Tier 2/i);
 assert.match(first.stdout, /REQUIRED HARNESS INVARIANTS/);
-assert.match(first.stdout, /WORKFLOW SKILLS \(EVALUATE APPLICABILITY .*SELECTED WORKFLOW IS GUIDANCE\)/);
+assert.match(first.stdout, /WORKFLOW SKILLS \(APPLICABILITY MUST BE RESOLVED\)/);
 assert.match(first.stdout, /evaluate-suggestions-before-skip/);
 assert.match(first.stdout, /read its complete SKILL\.md entry/);
 assert.doesNotMatch(first.stdout, /BASE EXECUTION LOOP/);
-assert.match(first.stdout, /ORCHESTRATION POLICY: Selected topology is planning guidance/);
-assert.match(first.stdout, /WORKFLOW GUIDANCE \(ADVISORY WHEN SELECTED\)/);
+assert.match(first.stdout, /ORCHESTRATION POLICY: Selected-topology required obligations and applicable skill core contracts are semantic MUSTs/);
+assert.match(first.stdout, /WORKFLOW SEMANTIC CONTRACT \(NON-BLOCKING OBSERVATION\)/);
 assert.match(first.stdout, /Selected workflow: iterative-single/);
-assert.match(first.stdout, /Before claiming completion, review unresolved workflow evidence and objective verification/);
+assert.match(first.stdout, /Before claiming completion, MUST resolve required workflow evidence and objective verification/);
 assert.doesNotMatch(first.stdout, /budget-exhausted|reset-budget/);
 
 const trivial = route('Update one README typo');
@@ -213,4 +213,4 @@ assert.match(unmatched.stdout, /RECOMMENDED TIER:\s*Unclassified/i);
 assert.match(unmatched.stdout, /"tier":"unclassified"/i);
 assert.doesNotMatch(unmatched.stdout, /RECOMMENDED TIER:\s*Tier 1/i);
 
-console.log(`OpenAI plugin package verified: ${skillNames.length} skills, publication metadata, hooks, marketplace, deterministic guidance-first routing.`);
+console.log(`OpenAI plugin package verified: ${skillNames.length} skills, publication metadata, hooks, marketplace, deterministic semantic-contract routing.`);

package/ci/router-workflow-plan.test.js

@@ -67,6 +67,7 @@ if (validContract(direct, 'direct-single')) {
   check(plan.strategy === 'direct-single', 'one-file trivial task selects direct-single');
   check(plan.strategySelection === 'selected', 'direct-single is a selected strategy');
   check(plan.requiredInvariants.includes('visible-status-updates'), 'every selected workflow carries the user-visible status invariant');
+  check(plan.requiredInvariants.includes('environment-alignment'), 'every selected workflow carries conditional environment-alignment MUST');
   check(plan.workspace.required === false, 'direct-single does not require a workspace');
   check(plan.parallelism.allowed === false, 'direct-single does not parallelize');
 }
@@ -76,15 +77,15 @@ if (validContract(iterative, 'iterative-single')) {
   const plan = iterative.contract.workflowPlan;
   check(plan.tier === 'tier2', 'ordinary test-first bug fix is tier2');
   check(plan.strategy === 'iterative-single', 'ordinary bug fix selects iterative-single');
-  check(plan.limits.maxIterations === ITERATIVE_MAX_ITERATIONS, 'iterative-single retains an advisory iteration guidance value');
-  check(plan.limits.maxRevisionRounds === WORKFLOW_MAX_REVISION_ROUNDS, 'workflow exposes an advisory revision guidance value');
-  check(plan.limits.maxReplans === FABLE_MAX_REPLANS, 'workflow exposes an advisory replan guidance value');
-  check(plan.limits.maxWorkers === FABLE_MAX_WORKERS, 'workflow exposes an advisory worker guidance value');
+  check(plan.limits.maxIterations === ITERATIVE_MAX_ITERATIONS, 'iterative-single retains a MAY iteration planning value');
+  check(plan.limits.maxRevisionRounds === WORKFLOW_MAX_REVISION_ROUNDS, 'workflow exposes a MAY revision planning value');
+  check(plan.limits.maxReplans === FABLE_MAX_REPLANS, 'workflow exposes a MAY replan planning value');
+  check(plan.limits.maxWorkers === FABLE_MAX_WORKERS, 'workflow exposes a MAY worker planning value');
   check(plan.requiredInvariants.includes('objective-verification'), 'iterative-single carries objective verification invariant');
-  check(plan.requiredInvariants.includes('loop-awareness'), 'iterative-single carries loop-awareness guidance');
-  check(plan.suggestedSkills.includes('tdd'), 'TDD stays advisory rather than an invariant');
+  check(plan.requiredInvariants.includes('loop-awareness'), 'iterative-single carries semantic loop-awareness obligation while numeric counts remain MAY');
+  check(plan.suggestedSkills.includes('tdd'), 'TDD remains applicability-conditional rather than a universal invariant');
   check(plan.memory.write === 'none', 'ordinary iterative work cannot write durable memory');
-  check(!plan.requiredInvariants.includes('tdd'), 'suggested skills are separated from mandatory invariants');
+  check(!plan.requiredInvariants.includes('tdd'), 'suggested skill names remain separate from plan invariants until applicability is resolved');
 }
 
 const memoryPersist = runTier('Persist this lesson as memory after resolving the checkout regression.');
@@ -110,6 +111,8 @@ if (validContract(staged, 'fable-staged')) {
   check(plan.strategy === 'fable-staged', 'dependent multi-stage work selects fable-staged');
   check(plan.parallelism.allowed === false, 'dependent stages remain sequential');
   check(plan.verification.mode === 'cold-verifier', 'fable-staged requires cold verification');
+  check(plan.requiredInvariants.includes('isolated-worktree-before-mutation'), 'fable-staged carries mandatory isolation disposition');
+  check(plan.suggestedSkills.includes('using-git-worktrees'), 'fable-staged surfaces worktree resolution skill');
 }
 
 const parallelPrompt = 'Audit the entire repository with independent read-only security, architecture, and documentation workstreams.';
@@ -287,10 +290,10 @@ const kernelIterative = spawnSync(process.execPath, [kernelRouter, 'Fix this che
   encoding: 'utf8',
 });
 check(kernelIterative.stdout.includes('"strategy":"iterative-single"'), 'kernel consumes strategy from structured plan');
-check(kernelIterative.stdout.includes('loop-awareness:'), 'kernel prints dynamic plan guidance');
+check(kernelIterative.stdout.includes('loop-awareness:'), 'kernel prints dynamic semantic plan obligations');
 check(kernelIterative.stdout.includes('visible-status-updates:'), 'kernel prints the user-visible status invariant');
 check(kernelIterative.stdout.includes('USER-VISIBLE HARNESS STATUS CONTRACT (MUST)'), 'kernel prints the canonical mandatory user-visible status contract');
-check(kernelIterative.stdout.includes('   - tdd'), 'kernel prints advisory skills separately');
+check(kernelIterative.stdout.includes('   - tdd'), 'kernel prints suggested skills separately from required invariants');
 
 for (const schemaPath of [
   'harness-everything/schemas/router-task-shape.schema.json',

package/ci/workflow-execution-contract.test.js

@@ -9,7 +9,7 @@ function runNode(args){return spawnSync(process.execPath,args,{cwd:ROOT,encoding
 console.log('=== Workflow Guidance Contract ===');
 for(const rel of ['harness-everything/scripts/kernel-router.js','hooks/scripts/workflow-gate.js','hooks/scripts/workflow-stop-gate.js','hooks/scripts/workflow-disposition.js','hooks/scripts/state-persist.js','hooks/scripts/rule-of-3.js','hooks/scripts/rule-of-3-tracker.js'])check(runNode(['--check',path.join(ROOT,rel)]).status===0,rel+' parses as valid JavaScript');
 const ctx={workflow:{workflowPlan:{limits:{maxIterations:8,maxRevisionRounds:2,maxReplans:2,maxWorkers:4}}}};
-for(const type of ['iteration','revision','replan','worker-acquire'])check(runtime.recordBudgetEvent(ctx,type,{evidence:'fixture'}).advisory===true,type+' is advisory rather than blocking');
+for(const type of ['iteration','revision','replan','worker-acquire'])check(runtime.recordBudgetEvent(ctx,type,{evidence:'fixture'}).advisory===true,type+' remains a MAY planning hint rather than blocking');
 check(runtime.mutationProbeReservations(ctx)===0,'mutation probes reserve no capacity');
 check(runtime.registerMutationProbe(ctx,'x','y')===null,'mutation probe registration is a no-op');
 check(runtime.resetWorkflowBudget(ctx,'legacy').retired===true,'reset-budget API is retired compatibility only');
@@ -51,5 +51,5 @@ try{
   check(stale.includes('independent-verifier-missing'),'Fable independent verifier is invalidated by newer handoff shell-edit evidence');
 }finally{fs.rmSync(freshnessRoot,{recursive:true,force:true});}
 
-console.log('\n'+(failed===0?'PASS':'FAIL')+': workflow guidance contract ('+failed+' failures)');
+console.log('\n'+(failed===0?'PASS':'FAIL')+': workflow semantic contract mechanics ('+failed+' failures)');
 process.exit(failed===0?0:1);

package/docs/architecture.md

@@ -9,16 +9,16 @@ Harness is a **behavior and workflow observer/router**, not a universal fixed wo
 The minimal kernel establishes:
 
 - scope/tier before mutation,
-- a selected workflow topology as planning guidance when task evidence supports one,
+- a selected workflow topology as a semantic execution contract when task evidence supports one,
 - applicability evaluation for every suggested skill before omission,
 - objective evidence before completion,
 - bounded re-plan/recovery after repeated failure,
 - explicit warnings/degraded/escape evidence instead of silent workflow deletion;
 - one mandatory user-visible Harness Status protocol for non-trivial work, independent of execution topology.
 
-> **Guidance-first workflow; flexible reasoning/implementation and execution.**
+> **Contract-first lifecycle; flexible reasoning/implementation and execution.**
 >
-> Suggested skills and topology are evaluated from their real flows. Missing or skipped cognitive workflow steps produce evidence/reminders rather than persistent Harness locks.
+> Suggested skills MUST be evaluated from their real flows. Applicable skill core contracts and selected-topology obligations are semantic MUSTs; missing evidence produces reminders rather than persistent Harness locks.
 
 This avoids both extremes: no universal Tier-2/Tier-3 pipeline and no maze of self-deadlocking cognitive gates.
 
@@ -50,8 +50,8 @@ flowchart TD
 - selected/deferred execution strategy,
 - required invariants,
 - suggested skills that require applicability evaluation,
-- the visible routing checkpoint,
-- a workflow guidance.
+- the internal routing checkpoint,
+- the semantic workflow contract.
 
 The router does not tell the model *how* to solve each stage. It decides what lifecycle shape is required. `direct-single`, `iterative-single`, `fable-staged`, `fable-parallel`, and `fable-multi-agent-workspace` remain deliberately small, non-overlapping topology choices.
 
@@ -78,7 +78,7 @@ This is a semantic contract, not another cognitive lock. Hook-capable hosts may
 
 Router suggestions remain useful domain/workflow knowledge, not a universal sequence. Before omission, the agent reads the complete `SKILL.md` entry and evaluates `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules. Name/description/router-summary or “routine task” is insufficient evidence.
 
-The selected topology is a structured planning aid; it does not become a persistent execution lock.
+The selected topology is a semantic lifecycle contract, not a persistent execution lock. Required obligations MUST resolve; implementation tactics MAY adapt.
 
 ### Runtime workflow state
 
@@ -91,13 +91,13 @@ For selected Fable topologies on Claude:
 - `workflow-stop-gate.js` reports unresolved stage/verification evidence without rejecting Stop;
 - `workflow-disposition.js` records explicit lifecycle/audit decisions; numeric budgets are no longer authoritative control state.
 
-Other topologies use their own applicable mechanisms: advisory loop-awareness reminders, regular verification stop-gates, action gates, and task-specific skills. Mechanism coverage is not assumed identical across hosts.
+Other topologies use their own applicable mechanisms: MAY-level loop-awareness planning hints, regular verification stop-gates, action gates, and task-specific skills. Mechanism coverage is not assumed identical across hosts.
 
 ### Scoped runtime advisories and capabilities
 
 Two kernel mechanisms annotate plans without creating hard workflow enforcement:
 
-- **Ensemble policy (`harness-everything/scripts/ensemble-policy.js`):** an advisory plan annotation, not a separate topology. It is selected only when uncertainty is high (or stakes are high) **and** the task asks for comparable outputs or preserves explicit disagreement **and** the selected strategy is already `fable-*`. Creative generation, mechanical bulk work, an explicit user prohibition, unavailable subagents, or a blocked base plan force exclusion. When selected, the plan caps at 3 candidates with `preserve-disagreement` synthesis, an independent verifier, and `parallel-self-consistency` pattern invariants. Covered by deterministic mechanism tests; no live-host effectiveness claim follows from the annotation alone.
+- **Ensemble policy (`harness-everything/scripts/ensemble-policy.js`):** optional selection is a **MAY** capability, not a separate topology. It is selected only when uncertainty is high (or stakes are high) **and** the task asks for comparable outputs or preserves explicit disagreement **and** the selected strategy is already `fable-*`. Creative generation, mechanical bulk work, an explicit user prohibition, unavailable subagents, or a blocked base plan force exclusion. Once selected, preserving disagreement, using an independent verifier, and honoring the plan's ensemble invariants are **MUST** obligations. Covered by deterministic mechanism tests; no live-host effectiveness claim follows from the annotation alone.
 - **Single-use memory capability (`kernel-router.js#issueMemoryCapability`):** when the selected plan permits memory writes, the router issues one capability token bound to `sessionId`/`workflowId` with a stored SHA-256 hash (`memoryAuthorization`, coordinator-only writer role, `usedAt` tracking). Plans with `memory.write === 'none'` receive no capability. This binds a memory write to the workflow that authorized it; it is not a general credential and proves nothing about a live host honoring the binding.
 
 ### PreToolUse guard trio and denied-mutation probes
@@ -105,7 +105,7 @@ Two kernel mechanisms annotate plans without creating hard workflow enforcement:
 On the Claude hook path, three narrowly scoped `PreToolUse` guards sit alongside the workflow/action gates:
 
 - `boundary-guard.js` (Grep/Glob/Read): warns about very large reads and noisy search roots; it fails open.
-- `depth-guard.js` (Write): blocks overwriting an existing file that was never Read earlier in the session transcript. New files are unaffected. Fails open on parse/lookup errors.
+- `depth-guard.js` (Write): reminds when an existing file would be overwritten without prior inspection. The semantic obligation to establish current target state before destructive overwrite is a **MUST**; the hook itself stays fail-open. New files are unaffected.
 - `context-compact.js`: estimates working-tree context pressure from `git status`/`git diff --numstat` so later stages can compact or halt before lost-in-the-middle degradation.
 
 Shell mutation observation is best-effort evidence for reminders. The old mutation-probe reservation/lock subsystem was retired by #190.
@@ -118,23 +118,23 @@ Harness aligns to each host's actual lifecycle/tool APIs. Shared skill text defi
 
 Runtime state includes hook metadata, workflow lifecycle, circuit-breaker counters, handoff/verification evidence, and WAL-style session state. Skill content is independently discoverable and remains useful on instruction-only surfaces.
 
-### Claude Code — hook guidance plus explicit safety boundaries
+### Claude Code — hook observation plus explicit safety boundaries
 
 The installer configures native lifecycle hooks and project skills.
 
 - `SessionStart`: bootstrap/restoration.
-- `UserPromptSubmit`: kernel routing + workflow guidance.
+- `UserPromptSubmit`: kernel routing + semantic workflow contract.
 - `PreToolUse`: workflow/boundary/depth/scope reminders, plus separate action permission and Rule-of-3 boundaries.
 - `PostToolUse`: outcomes, state, repeated-failure evidence, stage checks.
 - `Stop`: action-gate audit plus non-blocking workflow/verification reminders.
 
-These hooks make reminders observable; they do not promote cognitive workflow guidance into hard enforcement.
+These hooks make semantic obligations observable; they do not promote cognitive workflow contracts into hard enforcement.
 
 ### OpenCode — plugin enforcement, scoped live verification
 
 The retained [OpenCode evidence](../benchmarks/results/live-host/opencode-2026-09-16/README.md) supports **project-scope `.js` loading and edit/verification state on OpenCode 1.18.31 (macOS)**. The final snapshot is **post-reset**. Hard-lock is an **interactive observation** with **no retained blocked-tool trace**; reflection was **operator-seeded** and then agent-rewritten. Global scope, npm-package installation, and other OpenCode versions remain unverified.
 
-This evidence predates #190 and does not establish behavioral effectiveness of the current guidance-first lifecycle.
+This evidence predates #190 and does not establish behavioral effectiveness of the current contract-first lifecycle.
 
 ### Cursor — skills plus advisory rules
 
@@ -148,7 +148,7 @@ Copilot receives Agent Skills/repository instructions. No Harness-specific live
 
 Codex has multiple distinct Harness surfaces:
 
-- The general `--codex` installer writes repo-scoped `.agents/skills/` plus `AGENTS.md`; when consumed only as instructions, workflow enforcement is advisory/instruction-governed.
+- The general `--codex` installer writes repo-scoped `.agents/skills/` plus `AGENTS.md`; when consumed only as instructions, the same semantic contract is instruction-delivered without a hard-enforcement claim.
 - The **Codex / local OpenAI plugin** under `plugins/harness-everything/` packages canonical skills plus session/prompt/supported-tool/subagent/stop hooks. The package includes workflow-gate adapters, but this is mechanism/package evidence until a live Codex session proves loading/firing.
 - The public OpenAI **Skills-only** artifact excludes local `.codex-plugin` lifecycle hooks; it carries reusable workflow knowledge, not local hard gates.
 
@@ -204,7 +204,7 @@ A domain skill may define RED/GREEN/REFACTOR or another local lifecycle. The sel
 
 1. **No Harness telemetry service:** project code/state is not uploaded by Harness runtime scripts.
 2. **Credential protection:** credentials remain human/host controlled.
-3. **Small mechanism surface:** hooks should remain fast and auditable.
+3. **Small mechanism surface:** hooks **SHOULD** remain fast and auditable.
 4. **Explicit enforcement labels:** instruction, mechanism, and live evidence are distinct.
 5. **Deterministic regression:** workflow/routing/hook contracts are executable CI gates.
 6. **No silent widening:** workflow escape cannot widen authorization, permissions, or external side effects.