harness-everything 0.18.1 → 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.18.1",
+      "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.18.1",
+  "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,14 @@
 
 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
+
+* **distribution:** add cross-platform plugin install/update command ([0566bf3](https://github.com/dyphn1/Harness-everything/commit/0566bf347feab785af829e0f257fa22899f5c259))
+
 ## [0.18.1](https://github.com/dyphn1/Harness-everything/compare/v0.18.0...v0.18.1) (2026-09-21)
 
 ### Bug Fixes

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)
@@ -58,6 +58,11 @@ Harness integrates directly into your workspace. There is no heavy daemon, no pa
 # Option B: install Harness hooks/skills/advisory integrations into your workspace
 npx github:dyphn1/Harness-everything install
 
+# Option C: install or update the native Claude Code/Codex plugin
+#   npx github:dyphn1/Harness-everything plugin-sync
+#   ./scripts/plugin-sync.sh              # POSIX shells / Git Bash
+#   powershell -File scripts/plugin-sync.ps1  # Windows PowerShell
+
 # OpenAI/Codex local plugin packaging is repository-owned under:
 #   .agents/plugins/marketplace.json
 #   plugins/harness-everything/.codex-plugin/plugin.json
@@ -68,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)
@@ -90,6 +95,8 @@ For `--global`, the installer uses each host's supported user-level skill locati
 
 The repository also ships a separate local OpenAI/Codex plugin package under `plugins/harness-everything/` with marketplace metadata in `.agents/plugins/marketplace.json`. That package is not the same thing as the `--codex` advisory installer path. The public OpenAI Skills-only upload is narrower again; see [docs/openai-plugin.md](docs/openai-plugin.md).
 
+The native `plugin-sync` command detects the installed host CLIs and applies the state-specific operation: an absent plugin is installed, while an already-installed plugin is explicitly updated (Claude Code) or its configured marketplace is upgraded (Codex). If a host cannot report plugin state, the command fails closed without installing or updating blindly.
+
 The installer records its state directories in `.git/info/exclude` — a local-only git ignore file — so Harness state never lands in a commit and your working tree (including `.gitignore`) is never modified. Everything owned by the general installer is removed with the built-in uninstaller:
 
 ```bash
@@ -120,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]
@@ -140,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.
 
 ---
 
@@ -148,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.
@@ -165,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 |
@@ -239,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 |
@@ -256,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.
@@ -266,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/bin/cli.js

@@ -40,6 +40,9 @@ switch (command) {
   case 'codex-hooks':
     runCodexHooksCompat(args.slice(1));
     break;
+  case 'plugin-sync':
+    runPluginSync(args.slice(1));
+    break;
   default:
     console.error(`[Error] Unknown command: "${command}"`);
     showHelp();
@@ -104,6 +107,9 @@ Commands:
                      that fail to mount enabled plugin-bundled hooks.
                      Usage: harness codex-hooks <install|status|uninstall>
                      Does not trust hooks or modify Codex config.toml.
+  plugin-sync        Install or update the native Harness plugin on Claude Code
+                     and Codex. Existing installations always take the update
+                     path. Supports --host, --dry-run, and --json.
   verify             Run the pre-delivery verification gate (lint/test from the
                      nearest package.json). Exits non-zero if checks fail. This is
                      the explicit stand-in for a hard stop gate on platforms where
@@ -179,3 +185,13 @@ function runCodexHooksCompat(compatArgs) {
   const result = spawnSync('node', [script, ...compatArgs], { stdio: 'inherit' });
   process.exit(result.status === null ? 1 : result.status);
 }
+
+function runPluginSync(pluginArgs) {
+  const script = path.resolve(__dirname, '..', 'scripts', 'plugin-sync.js');
+  if (!fs.existsSync(script)) {
+    console.error('[Error] Native plugin synchronization script not found.');
+    process.exit(1);
+  }
+  const result = spawnSync('node', [script, ...pluginArgs], { stdio: 'inherit' });
+  process.exit(result.status === null ? 1 : result.status);
+}

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-2ao-plugin-sync.test.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+const {
+  findMarketplace,
+  findPlugin,
+  parseJsonOutput,
+  sync
+} = require('../scripts/plugin-sync');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function fakeHost({ claudeInstalled = false, codexInstalled = false, claudeMarketplace = true, codexMarketplace = true, unknownClaudePluginState = false } = {}) {
+  const calls = [];
+  const state = {
+    claudeInstalled,
+    codexInstalled,
+    claudeMarketplace,
+    codexMarketplace
+  };
+  const runner = (command, args) => {
+    calls.push({ command, args: [...args] });
+    const joined = args.join(' ');
+
+    if (command === 'claude') {
+      if (joined.includes('marketplace list --json')) {
+        return { status: 0, stdout: JSON.stringify({ marketplaces: state.claudeMarketplace ? [{ name: 'harness-everything' }] : [] }), stderr: '' };
+      }
+      if (joined === 'plugin marketplace list') {
+        return { status: 0, stdout: state.claudeMarketplace ? 'harness-everything\n' : '', stderr: '' };
+      }
+      if (joined.startsWith('plugin marketplace add')) {
+        state.claudeMarketplace = true;
+        return { status: 0, stdout: '', stderr: '' };
+      }
+      if (joined.startsWith('plugin marketplace update')) return { status: 0, stdout: '', stderr: '' };
+      if (joined.includes('plugin list --json')) {
+        if (unknownClaudePluginState) return { status: 1, stdout: '', stderr: 'unsupported --json' };
+        return { status: 0, stdout: JSON.stringify({ plugins: state.claudeInstalled ? [{ id: 'harness-everything@harness-everything' }] : [] }), stderr: '' };
+      }
+      if (joined === 'plugin list') {
+        if (unknownClaudePluginState) return { status: 1, stdout: '', stderr: 'unsupported list' };
+        return { status: 0, stdout: state.claudeInstalled ? 'harness-everything@harness-everything\n' : '', stderr: '' };
+      }
+      if (joined.startsWith('plugin install') || joined.startsWith('plugin update')) {
+        state.claudeInstalled = true;
+        return { status: 0, stdout: '{}', stderr: '' };
+      }
+    }
+
+    if (command === 'codex') {
+      if (joined.includes('marketplace list --json')) {
+        return { status: 0, stdout: JSON.stringify({ marketplaces: state.codexMarketplace ? [{ name: 'harness-everything' }] : [] }), stderr: '' };
+      }
+      if (joined === 'plugin marketplace list') {
+        return { status: 0, stdout: state.codexMarketplace ? 'harness-everything\n' : '', stderr: '' };
+      }
+      if (joined.startsWith('plugin marketplace add')) {
+        state.codexMarketplace = true;
+        return { status: 0, stdout: '{}', stderr: '' };
+      }
+      if (joined.startsWith('plugin marketplace upgrade')) return { status: 0, stdout: '{}', stderr: '' };
+      if (joined.includes('plugin list --marketplace harness-everything --json') || joined === 'plugin list --json') {
+        return { status: 0, stdout: JSON.stringify({ plugins: state.codexInstalled ? [{ name: 'harness-everything', marketplace: 'harness-everything' }] : [] }), stderr: '' };
+      }
+      if (joined === 'plugin list --marketplace harness-everything' || joined === 'plugin list') {
+        return { status: 0, stdout: state.codexInstalled ? 'harness-everything@harness-everything\n' : '', stderr: '' };
+      }
+      if (joined.startsWith('plugin add')) {
+        state.codexInstalled = true;
+        return { status: 0, stdout: '{}', stderr: '' };
+      }
+    }
+
+    return { status: 0, stdout: '', stderr: '' };
+  };
+
+  return {
+    calls,
+    runner,
+    commandAvailable: () => true
+  };
+}
+
+function callsFor(calls, command, prefix) {
+  return calls.filter(call => call.command === command && call.args.join(' ').startsWith(prefix));
+}
+
+function runHost(host, fake) {
+  return sync({ host, repository: 'dyphn1/Harness-everything', ref: 'main' }, {
+    ...fake,
+    log: () => {},
+    warn: () => {}
+  });
+}
+
+assert.strictEqual(parseJsonOutput('status\n{"ok":true}\n').ok, true);
+assert.strictEqual(findMarketplace({ marketplaces: [{ name: 'harness-everything' }] }, 'harness-everything'), true);
+assert.strictEqual(findPlugin({ plugins: [{ id: 'harness-everything@harness-everything' }] }, 'harness-everything', 'harness-everything'), true);
+
+{
+  const fake = fakeHost({ claudeInstalled: false });
+  const result = runHost('claude', fake);
+  assert.strictEqual(result.failed, 0);
+  assert.strictEqual(result.results[0].action, 'install');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin install').length, 1, 'absent Claude plugin must install');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin update').length, 0, 'absent Claude plugin must not update');
+}
+
+{
+  const fake = fakeHost({ claudeInstalled: true });
+  const result = runHost('claude', fake);
+  assert.strictEqual(result.failed, 0);
+  assert.strictEqual(result.results[0].action, 'update');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin update').length, 1, 'installed Claude plugin must update');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin install').length, 0, 'installed Claude plugin must not reinstall');
+}
+
+{
+  const fake = fakeHost({ codexInstalled: false });
+  const result = runHost('codex', fake);
+  assert.strictEqual(result.failed, 0);
+  assert.strictEqual(result.results[0].action, 'install');
+  assert.strictEqual(callsFor(fake.calls, 'codex', 'plugin add').length, 1, 'absent Codex plugin must install');
+}
+
+{
+  const fake = fakeHost({ codexInstalled: true });
+  const result = runHost('codex', fake);
+  assert.strictEqual(result.failed, 0);
+  assert.strictEqual(result.results[0].action, 'update');
+  assert.strictEqual(callsFor(fake.calls, 'codex', 'plugin marketplace upgrade').length, 1, 'installed Codex plugin must upgrade its marketplace');
+  assert.strictEqual(callsFor(fake.calls, 'codex', 'plugin add').length, 0, 'installed Codex plugin must not be re-added');
+}
+
+{
+  const fake = fakeHost({ unknownClaudePluginState: true });
+  const result = runHost('claude', fake);
+  assert.strictEqual(result.failed, 1, 'unknown installed state must fail closed');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin install').length, 0, 'unknown state must not install');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin update').length, 0, 'unknown state must not update blindly');
+  assert.strictEqual(callsFor(fake.calls, 'claude', 'plugin marketplace update').length, 0, 'unknown state must not refresh the marketplace blindly');
+}
+
+{
+  const result = sync({ host: 'all' }, { commandAvailable: () => false, log: () => {}, warn: () => {} });
+  assert.strictEqual(result.skipped, 2);
+  assert.strictEqual(result.failed, 0);
+}
+
+for (const wrapper of ['scripts/plugin-sync.sh', 'scripts/plugin-sync.ps1']) {
+  const text = fs.readFileSync(path.join(ROOT, wrapper), 'utf8');
+  assert.match(text, /plugin-sync\.js/);
+  assert.doesNotMatch(text, /\.codex\/plugins\/cache|config\.toml/);
+}
+
+const cli = fs.readFileSync(path.join(ROOT, 'bin', 'cli.js'), 'utf8');
+assert.match(cli, /case 'plugin-sync'/);
+assert.match(cli, /Existing installations always take the update/);
+
+console.log('Native plugin sync verified: absent plugins install, installed plugins update, and unknown state fails closed.');

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.`);