harness-everything 0.18.1 → 0.19.1

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.

package/docs/enforcement-locks.md

@@ -1,21 +1,23 @@
-# Guidance and Safety Boundary Diagnostic Flows
+# Semantic Contracts and Safety Boundary Diagnostic Flows
 
-Harness deliberately separates **cognitive guidance** from **authorization/safety boundaries**.
+Harness deliberately separates **semantic obligation strength** from **mechanical enforcement** and from **authorization/safety boundaries**. Canonical MUST/SHOULD/MAY definitions live in [philosophy.md](philosophy.md#contract-strength-must--should--may).
 
 ## Classification
 
-| Mechanism | Behavior | Hard block? |
-|---|---|---|
-| Workflow routing/state | Remind about selected topology, stale/blocked descriptive state, missing Fable correlation, or safer worktree usage | No |
-| Iteration/revision/replan/worker guidance | Planning hints only | No |
-| Verification / Stop | Remind when no successful verification is observed after an edit | No |
-| Boundary guard | Warn about very large reads or noisy search roots | No |
-| Depth guard | Remind when editing a file that has not been inspected | No |
-| Subagent scope guard | Report ambiguous/out-of-scope changes for review | No |
-| Atomic commit check | Warn when changes look broader than one atomic concern | No |
-| Fable contract test | Record pass/fail/ambiguity/dependency evidence and warn | No |
-| Rule of 3 | Third matching failure requires a zoom-out reflection before more mutation | **Yes — intentional cognitive boundary** |
-| Action/permission gate | User/host authorization for destructive or external side effects | **Yes — trust boundary** |
+| Mechanism / obligation | Semantic strength | Runtime behavior | Hard block? |
+|---|---|---|---|
+| Workflow routing / selected topology | **MUST** resolve required obligations | Observe/remind about unresolved lifecycle evidence | No |
+| Suggested skill applicability | **MUST** evaluate; applicable core contract **MUST** run | Kernel/instructions expose dispositions | No |
+| Iteration/revision/replan/worker numbers | **MAY** guide planning | Planning hints only | No |
+| Verification before claim | **MUST** | Stop/hooks remind when evidence is missing | No |
+| Boundary guard / huge-noisy context | **SHOULD** narrow reads/searches | Warn | No |
+| Destructive overwrite target inspection | **MUST** establish current state | Depth guard reminds/fails open on mechanism errors | No |
+| Tier-3/Fable isolation disposition | **MUST** resolve worktree or degraded fallback | Warn when unresolved | No |
+| Subagent declared scope / unexpected writes | **MUST** respect and reconcile | Report ambiguous/out-of-scope changes | No |
+| Commit scope | Staged diff review **MUST**; split unrelated concerns **SHOULD** | Atomic-commit reminder | No |
+| Fable stage/check/synthesis/verifier | **MUST** when selected | Record pass/fail/ambiguity/dependency evidence and remind | No |
+| Rule of 3 | Third matching failure **MUST** trigger zoom-out | Pause mutation until reflection | **Yes — intentional cognitive boundary** |
+| Action/permission gate | Approval **MUST** precede governed side effects | Host/user authorization | **Yes — trust boundary** |
 
 ## Rule of 3
 
@@ -41,7 +43,7 @@ The previous numeric enforcement required mutation probes, stale-probe recovery,
 
 The design test is simple:
 
-> If better cognitive guidance requires another lock, lease, heartbeat, counter-recovery protocol, or parser exception, prefer a reminder.
+> If observing a semantic obligation would require another lock, lease, heartbeat, counter-recovery protocol, or parser exception, use a reminder instead. The reminder changes the **mechanism**, not the obligation's MUST/SHOULD/MAY strength.
 
 ## Troubleshooting
 

package/docs/philosophy.md

@@ -9,17 +9,52 @@ The mechanism/enforcement boundary remains platform-specific; see [Platform Capa
 ## Core Philosophy: Constrain Lifecycle, Not Reasoning
 
 1. **Reasoning autonomy remains high.** The model chooses implementation technique, tools, decomposition details, and tactics inside the selected workflow.
-2. **Applicable workflow is guidance: routing should make useful structure visible without taking execution agency away from the model/user.
-3. **Skill applicability is explicit.** Router-suggested skills are read/evaluated before omission. A suggestion can be `not-applicable` when its actual flow does not match; a selected topology is stronger and cannot simply be skipped.
+2. **Selected lifecycle obligations are contracts, not advice.** Once a topology is selected, its required invariants, stages, checks, synthesis barriers, and verification obligations are semantic MUSTs. The model remains free to decide how to satisfy them.
+3. **Skill applicability is explicit.** Every router-suggested skill MUST be read/evaluated before omission. If its real flow is applicable, its core contract MUST be followed; if it is not applicable, the agent MUST keep a flow-grounded reason.
 4. **Escape is conditional, not default.** If the selected workflow genuinely cannot represent part of the task, record the uncovered scope and evidence, then allow model-defined handling only for that uncovered portion.
-5. **Mechanisms beat stronger wording.** Important lifecycle transitions should use structured state, objective evidence, hooks/plugins, exit codes, and completion gates where the host supports them rather than escalating `MUST`/`CRITICAL` prose.
+5. **Mechanisms do not define obligation strength.** Hooks/plugins may observe, remind, or mechanically block where the host supports them, but a missing blocking mechanism does not downgrade a semantic MUST to optional advice.
 
 This principle can be summarized as:
 
-> **guidance-first applicable workflow; flexible reasoning/implementation inside it; evidence-backed escape only where the workflow does not cover the task.**
+> **contract-first lifecycle; flexible reasoning/implementation inside it; evidence-backed escape only where the workflow does not cover the task.**
 
 The goal is not to make the model less capable. It is to prevent capability/confidence from silently deleting engineering obligations such as verification, bounded re-planning, stage checks, documentation checks, or safety gates when those obligations are applicable.
 
+## Contract Strength: MUST / SHOULD / MAY
+
+Harness uses three semantic strengths. Recommendation-style language is the last choice, not the default for important behavior.
+
+| Strength | Meaning | Typical use |
+|---|---|---|
+| **MUST** | Skipping the obligation violates the Harness semantic contract. Host enforcement may still be reminder-only. | routing, applicability resolution, applicable skill core contracts, selected-topology obligations, verification-before-claim, status, scope/safety/authorization evidence |
+| **SHOULD** | The default is expected, but a concrete evidence-based exception is legitimate. | ordinary isolation, targeted editing, splitting mixed commit concerns, context-size/noisy-search discipline |
+| **MAY** | Optional optimization/capability. Omitting it needs no exception unless another contract selected it. | numeric planning hints, optional ensemble selection, extra deep references, opportunistic parallelism |
+
+Do not use `recommend`, `prefer`, `advisory`, or `guidance` to weaken a MUST. Those words are reserved for actual SHOULD/MAY behavior or for describing the host's **mechanical delivery mode** (for example, an instruction-only surface).
+
+The repository-wide classification for #217 is:
+
+| Obligation | Strength |
+|---|---|
+| Route before software/project execution | **MUST** |
+| Read/evaluate every suggested skill before omission | **MUST** |
+| Follow an applicable suggested skill's core contract; otherwise keep a flow-grounded not-applicable reason | **MUST** |
+| Resolve selected-topology invariants/stages/checks/synthesis/verification | **MUST** |
+| Choose tools, implementation technique, decomposition details, and local tactics | **MAY** within the MUST contract |
+| Verify before claiming completion | **MUST** |
+| Emit the unified Harness Status for non-trivial work | **MUST** |
+| Discover relevant environment/host facts before relying on environment-sensitive behavior | **MUST** |
+| Establish current target state before destructive overwrite/rewrite | **MUST** |
+| Resolve Tier-3/Fable isolation before broad mutation: linked worktree or explicit degraded fallback | **MUST** |
+| Use isolation for ordinary work when it materially reduces collision/risk | **SHOULD** |
+| Honor Fable stage contracts, checks, synthesis barrier, and cold verifier when selected | **MUST** |
+| Keep delegated agents inside declared scope and reconcile unexpected writes | **MUST** |
+| Inspect the staged diff/commit scope before committing | **MUST**; split unrelated concerns **SHOULD** |
+| Avoid huge/noisy reads/searches when a narrower query is sufficient | **SHOULD** |
+| Numeric iteration/revision/replan/worker values | **MAY** guide planning; never hard-block |
+| Select ensemble review | **MAY** when task shape warrants it; once selected, disagreement preservation and independent verification are **MUST** |
+| Durable memory writes | **MUST** be authorized by the active workflow/session contract |
+
 ## Why This Is Not a Rigid Global Pipeline
 
 Harness still rejects a universal `TODO → TDD → Fable → verification` sequence.
@@ -38,19 +73,19 @@ Domain skills remain conditional on applicability. The contract says “execute
 
 ### 1. Environment Alignment — Discovery over Assumption
 
-Discover OS, shell, package/runtime context, repository boundaries, and available host capabilities before relying on them. On surfaces that package preflight/session hooks this can be injected automatically; instruction-only hosts must do it explicitly.
+Relevant environment discovery is a conditional **MUST**: establish OS, shell, package/runtime context, repository boundaries, and host capabilities before relying on environment-sensitive behavior. On surfaces that package preflight/session hooks this may be injected automatically; instruction-only hosts MUST do it explicitly when needed.
 
 ### 2. Guardrails — Lifecycle Boundaries
 
-Circuit breakers, action gates, workflow gates, scope guards, and completion gates protect specific transitions. They should remain narrow and evidence-driven. On integration surfaces that expose the required lifecycle/tool hooks, Harness can mechanically block supported violations; elsewhere the same contract is instruction-governed and must not be mislabeled hard enforcement.
+Circuit breakers, action gates, workflow gates, scope guards, and completion gates protect specific transitions. They **SHOULD** remain narrow and evidence-driven. On integration surfaces that expose the required lifecycle/tool hooks, Harness can mechanically block supported violations; elsewhere the same contract is instruction-governed and must not be mislabeled hard enforcement.
 
 ### 3. Context Preservation — Progressive Disclosure
 
-Load the smallest useful context. Read a suggested skill's complete entry before deciding applicability, but do not load the entire skill tree or every optional deep reference. Machine-visible workflow state should carry lifecycle facts instead of repeating large prompt blocks.
+**SHOULD** load the smallest useful context. A suggested skill's complete entry **MUST** be read before deciding applicability; optional deep references **MAY** remain unloaded unless needed. Machine-visible workflow state SHOULD carry lifecycle facts instead of repeating large prompt blocks.
 
 ### 4. Self-Evolution — Learn from Workflow Evidence
 
-`self-evolve` should learn from verified recovery and workflow gaps: escape events, repeated replans, verifier fail→pass transitions, and recurrence outcomes. It should improve future coverage rather than granting a shortcut around the current workflow. Durable learning remains distinct from runtime session state.
+`self-evolve` **MUST** ground durable learning in verified recovery/workflow evidence. Escape events, repeated replans, verifier fail→pass transitions, and recurrence outcomes **MAY** provide that evidence. Durable learning MUST improve future coverage rather than grant a shortcut around the current workflow, and remains distinct from runtime session state.
 
 ## Mechanism-First Cooperation
 

package/docs/platform-capabilities.md

@@ -27,9 +27,9 @@ This is a **repository/agent contract**, not an automatic upgrade to any platfor
 
 | Platform surface | Standalone skills | Plugin support | Hooks/lifecycle | Project scope | Global scope | Current evidence boundary |
 | --- | --- | --- | --- | --- | --- | --- |
-| Codex | `Supported` | `Mechanism verified` | `Mechanism verified` for the local OpenAI package, including session, prompt, supported-tool, subagent, and stop hooks | `.agents/skills/`, `AGENTS.md` | `~/.agents/skills/` | Local package hooks are mechanically checked; live loading and marketplace refresh remain `Unknown`. |
+| Codex | `Supported` | `Mechanism verified` | `Mechanism verified` for the local OpenAI package, including session, prompt, supported-tool, subagent, and stop hooks | `.agents/skills/`, `AGENTS.md` | `~/.agents/skills/` | Local package hooks and the state-specific marketplace sync command are mechanically checked; live loading and marketplace refresh remain unverified. |
 | ChatGPT / OpenAI Plugin | `Unknown` for a repository-local standalone path | `Mechanism verified` | `Partial`: local Work/Codex hooks are separate from ordinary Chat | Managed workspace marketplace | Not established | The public Skills-only bundle is mechanically reproducible; import, approval, and live behavior remain `Unknown`. |
-| Claude Code | `Supported` | `Supported` | `Mechanism verified` for Harness configuration | `.claude/skills/` | `~/.claude/skills/` | Native Claude surfaces are documented and package/installer checks pass; fresh-host execution is not preserved here. |
+| Claude Code | `Supported` | `Supported` | `Mechanism verified` for Harness configuration | `.claude/skills/` | `~/.claude/skills/` | Native Claude surfaces and the state-specific plugin sync command are mechanically checked; fresh-host execution is not preserved here. |
 | OpenCode | `Supported` | `Partial` live-host loading for the project-scope, `.js`-filename install path on OpenCode 1.18.31 (macOS); other install paths remain `Mechanism verified` | `Partial` live-host evidence for project-scope `.js` loading and edit/verification state; hard lock reported only, with no retained blocked-tool trace and a post-reset final snapshot | `.opencode/skills/`, `.agents/skills/`, `.opencode/plugins/` | `~/.config/opencode/skills/`, `~/.agents/skills/`, `~/.config/opencode/plugins/` | [Retained evidence](../benchmarks/results/live-host/opencode-2026-09-16/README.md): loading and state effects verified in one host session; final snapshot post-reset; hard lock only an interactive observation; reflection operator-seeded, then agent-rewritten; no raw transcript or behavioral-effectiveness claim. `.mjs` auto-discovery broken (issue #127); global scope, npm-package installation, and other host versions remain unverified. |
 | GitHub Copilot agent surfaces | `Supported` | `Unknown` for a Harness-specific plugin install | `Unknown` | `.github/skills/`, `.agents/skills/`, repository instructions | `~/.copilot/skills/`, `~/.agents/skills/` | GitHub Agent Skills paths and installer behavior are checked; no live Copilot session or plugin install is preserved. |
 | Cursor | `Supported` | `Mechanism verified` for the portable package shape | `Unknown` for Harness | `.cursor/skills/`, `.agents/skills/` | `~/.cursor/skills/`, `~/.agents/skills/` | Official paths and package shape are checked; Cursor plugin loading and hooks remain unverified. |
@@ -64,6 +64,26 @@ Codex has two paths that must not be collapsed:
 
 The package is tested at the mechanism layer and remains subject to the host’s hook review/trust flow. A fresh host session is still required before claiming that a particular ChatGPT/Codex installation loaded and fired the hooks or that the model followed read-before-skip.
 
+### Native plugin install/update synchronization
+
+The repository also ships a host-facing synchronization command for the native marketplace/plugin surfaces:
+
+```bash
+npx github:dyphn1/Harness-everything plugin-sync
+# or, from a checkout:
+./scripts/plugin-sync.sh
+powershell -File scripts/plugin-sync.ps1
+```
+
+The command detects Claude Code and Codex independently, ensures the Harness marketplace is configured, reads the installed-plugin state, then refreshes that marketplace before choosing the operation:
+
+- absent plugin → install;
+- existing Claude Code plugin → `claude plugin update harness-everything@harness-everything`;
+- existing Codex plugin → `codex plugin marketplace upgrade harness-everything`;
+- unknown plugin state → fail closed, with no blind install/re-add.
+
+The installed branch is intentionally an update branch even when the current release is already the newest version; the host command may report “already latest.” Codex marketplace upgrade is the current native refresh operation; the command does not edit private cache paths or `config.toml`. These are deterministic command/state tests, not live-host evidence, so `liveHostVerification` remains `Unknown` in the matrix.
+
 ### Explicit Codex user-hook compatibility fallback
 
 Current Codex documentation supports plugin-bundled hooks, so native plugin mounting remains the preferred path. Some host/source combinations have nevertheless failed to expose enabled plugin hooks for review/entry attribution (#122 and upstream Codex reports). Harness therefore provides an **explicit compatibility fallback**, not an automatic replacement for native plugin hooks:

package/docs/platform-compatibility.json

@@ -1,6 +1,6 @@
 {
   "format": "harness-platform-compatibility-v1",
-  "last_reviewed": "2026-09-19",
+  "last_reviewed": "2026-09-21",
   "status_vocabulary": {
     "Supported": "An official or native mechanism exists and the Harness behavior is verified.",
     "Mechanism verified": "Harness package, adapter, or installer checks pass, but a real host run is not confirmed.",
@@ -114,7 +114,7 @@
         "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.agents/skills"]}},
         "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "General Harness installer ownership is mechanism-tested. The optional codex-hooks compatibility fallback separately has exact-entry update/uninstall ownership tests and preserves unrelated user hooks; live Codex trust/dispatch still requires host evidence."},
         "assetsReferences": {"status": "Mechanism verified", "notes": "Packaged skill references are checked and remain inside the package."},
-        "updateSync": {"status": "Unknown", "notes": "A real marketplace refresh has not been run in a Codex host."},
+        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses marketplace upgrade for an installed Codex plugin; no live Codex host refresh is preserved."},
         "liveHostVerification": {"status": "Unknown", "notes": "No preserved Codex plugin/session artifact proves current bundled-hook entry. Native plugin mounting is preferred; the explicit user-hook fallback is mechanism-verified only and does not solve host carriers that bypass hook dispatch."}
       }
     },
@@ -159,7 +159,7 @@
         "globalScope": {"status": "Mechanism verified", "paths": {"skills": ["~/.claude/skills"], "hooks": ["~/.claude/settings.json"]}},
         "installUninstallSymmetry": {"status": "Mechanism verified", "notes": "Owned settings, skills, agents, and user files are covered by round-trip tests."},
         "assetsReferences": {"status": "Mechanism verified", "notes": "Skill-local references, scripts, and templates are checked."},
-        "updateSync": {"status": "Unknown", "notes": "A live marketplace update has not been run in Claude Code."},
+        "updateSync": {"status": "Mechanism verified", "notes": "scripts/plugin-sync.js detects installed state and uses the explicit Claude plugin update command for an installed plugin; no live Claude host refresh is preserved."},
         "liveHostVerification": {"status": "Unknown", "notes": "No fresh Claude Code plugin session artifact is committed for this revision."}
       }
     },
@@ -267,4 +267,4 @@
       }
     }
   ]
-}
+}

package/docs/routing.md

@@ -4,9 +4,9 @@ Harness classifies software work and selects the smallest sufficient execution t
 
 The current architecture follows two coupled rules:
 
-> **Guidance-first workflow; flexible reasoning/implementation and execution.**
+> **Contract-first lifecycle; flexible reasoning/implementation and execution.**
 >
-> **Skill applicability is evaluated explicitly; skipped guidance should have a concise evidence-based reason.**
+> **Skill applicability is explicit: evaluation is mandatory, applicable core contracts are mandatory, and not-applicable dispositions require evidence.**
 
 A strong model remains free to decide *how* to perform the work. It may not decide that an applicable selected lifecycle can be skipped because the task feels simple or already understood.
 
@@ -18,7 +18,7 @@ For software/project work, Harness establishes routing context and lightweight r
 2. **Verify before claim** — completion requires objective evidence appropriate to the change.
 3. **Re-plan after repeated failure** — after three same-signature failures, stop micro-retrying and use a fresh diagnosis / `zoom-out`.
 4. **Evaluate before omission** — read every suggested skill's complete `SKILL.md` entry before deciding applicability.
-5. **Review selected workflow** — use it as planning guidance and surface unresolved evidence before claiming completion.
+5. **Resolve selected workflow** — satisfy the selected topology's required obligations before completion; tactics MAY adapt, but required lifecycle evidence cannot be silently skipped.
 6. **Surface status** — non-trivial work MUST keep the user informed through the single Harness Status format at required phase boundaries.
 
 The model owns tools, implementation technique, reasoning, and decomposition details inside those rails.
@@ -28,10 +28,10 @@ The model owns tools, implementation technique, reasoning, and decomposition det
 ```text
 kernel-router.js
   ├─ delegates classification / guide discovery → tier-router.js
-  ├─ preserves tier + rationale + dynamic-skill recommendations
+  ├─ preserves tier + rationale + dynamic-skill suggestions
   ├─ emits required invariants + structured workflow plan
   ├─ requires applicability evaluation for suggested skills
-  ├─ records the selected workflow guidance
+  ├─ records the selected workflow contract
   └─ exposes warnings/degraded/escape evidence instead of silently hiding limitations
 ```
 
@@ -70,10 +70,11 @@ These are intentionally different concepts.
 
 For **every suggested skill**:
 
-1. Resolve/read the complete `SKILL.md` entry.
-2. Evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules.
+1. **MUST** resolve/read the complete `SKILL.md` entry.
+2. **MUST** evaluate `USE FOR`, `DO NOT USE FOR`, workflow/basic flow, and hard rules.
 3. Read extra material only when the entry explicitly requires it for applicability.
-4. Resolve the suggestion as `use`, `not-applicable`, or `unresolved/unavailable`.
+4. **MUST** resolve the suggestion as `use`, `not-applicable`, or `unresolved/unavailable`.
+5. If disposition is `use`, the skill's core contract **MUST** be followed. If it is `not-applicable`, a concise flow-grounded reason **MUST** be retained.
 
 A name, description, router summary, tier label, or generic “routine/common task” judgement is not sufficient evidence for `not-applicable`.
 
@@ -86,7 +87,7 @@ For the **selected workflow topology**:
 
 This prevents two opposite failures: forcing every task through one giant pipeline, and allowing a model to rationalize away the entire engineering lifecycle.
 
-## Three-tier recommendation model
+## Three-tier routing model
 
 ```mermaid
 flowchart TD
@@ -117,7 +118,7 @@ No universal `TODO → TDD → verification-loop` order is implied. But when a s
 
 Typical triggers: repository-wide refactors, architecture/migration work, broad synthesis, or bounded delegation. The router may select `fable-staged`, `fable-parallel`, or `fable-multi-agent-workspace`.
 
-A selected Fable topology is structured guidance for that run; dependency/write-set validation remains useful evidence, while missing workflow state does not hard-block execution.
+A selected Fable topology is a semantic execution contract for that run: required stage contracts, dependency/write-set validation, objective checks, synthesis, and cold verification **MUST** resolve. Host hooks may only remind when evidence is missing; that fail-open mechanism does not make the obligations optional.
 
 Tier 3 does **not** automatically mean multi-agent. The smallest sufficient topology still wins.
 
@@ -141,18 +142,24 @@ Direct/iterative verification milestones are checked, while semantic check quali
 
 ## Cognitive OS relationship
 
-`install-cognitive-os` remains the explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is a reasoning policy, not a peer skill that must be selected before domain work. The selected workflow guidance informs lifecycle choices; the model retains execution freedom.
+`install-cognitive-os` remains the explanatory/manual entry point for Discover → Think → Try → Summarize → Record. It is a reasoning policy, not a peer skill that must be selected before domain work. The selected workflow contract defines lifecycle obligations; the model retains freedom over reasoning and implementation tactics.
 
-## Guidance and enforcement strength
+## Contract and Enforcement Strength
 
-Workflow guidance is intentionally non-blocking across hosts. Keep that separate from Rule-of-3 and explicit permission enforcement.
+Canonical strength definitions live in [philosophy.md](philosophy.md#contract-strength-must--should--may):
 
-- **semantic contract:** what the agent MUST do, including the unified Harness Status where applicable;
+- **MUST:** skipping violates the semantic contract.
+- **SHOULD:** expected default with a concrete evidence-based exception.
+- **MAY:** optional optimization/capability.
+
+Keep semantic strength separate from runtime mechanics:
+
+- **semantic contract:** what the agent MUST/SHOULD/MAY do;
 - **mechanism:** which transitions a packaged hook/plugin can block, observe, or remind about;
 - **live evidence:** whether a real host actually loaded/fired that mechanism.
 
-Semantic MUST and mechanical blocking are intentionally separate. A required communication or engineering obligation does not need a persistent runtime lock to remain mandatory.
+A semantic MUST does not require a hard lock. Outside Rule-of-3 reflection and explicit permission/safety boundaries, lifecycle hooks stay fail-open/reminder-oriented.
 
-Instruction-only integrations receive the same workflow contract as guidance, but must not be labeled hard-enforced. Kernel emission alone does not prove model compliance. #82 owns host-specific retained evidence.
+Instruction-only integrations receive the same semantic contract through instructions, but must not be labeled hard-enforced. Kernel emission alone does not prove model compliance. #82 owns host-specific retained evidence.
 
 Do not infer cross-host parity from shared runtime code or passing package tests.

package/docs/troubleshooting.md

@@ -189,6 +189,14 @@ If those checks pass but the host still shows an older copy:
 
 The local plugin mechanically injects the session policy and invariant-first routing contract, and its package includes mechanism-tested supported-tool, subagent, and stop adapters. If those events do not appear in a live session, verify the host loaded the current package and that changed command hooks were reviewed/trusted; package tests alone cannot prove host loading.
 
+For the native host install/update path, run:
+
+```bash
+npx github:dyphn1/Harness-everything plugin-sync --json
+```
+
+The command installs only when the plugin is absent. An installed Claude plugin uses the explicit Claude update command; an installed Codex plugin uses marketplace upgrade. If plugin state cannot be read, synchronization stops without re-adding or overwriting the plugin.
+
 See [openai-plugin.md](openai-plugin.md) for installation and validation details.
 
 ### Public OpenAI Skills-only plugin behaves differently from local Codex plugin