harness-everything 0.19.0 → 0.20.0

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/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/workflow-runtime.md

@@ -1,19 +1,20 @@
 # Workflow Runtime
 
-Harness uses workflow state to **observe, explain, and remind**. It is not a numeric-budget scheduler.
+Harness uses workflow state to **observe, explain, and remind about semantic contracts**. It is not a numeric-budget scheduler, and reminder-only mechanics do not make MUST obligations optional.
 
 ## Product rule
 
 The runtime follows **minimal rails, maximum freedom**:
 
-- routing selects a useful topology and suggested skills;
-- workflow state records useful evidence and unresolved obligations;
-- the agent MUST use the single user-visible Harness Status format at required phase boundaries for non-trivial work;
-- verification hooks remind when evidence is missing;
-- worktree/isolation checks warn when a safer execution shape is available;
-- iteration, revision, replan, and worker counts are planning hints only.
+- routing **MUST** establish the selected/deferred topology and suggested-skill applicability set;
+- workflow state records useful evidence and unresolved obligations without becoming a cognitive lock;
+- selected-topology required obligations and applicable skill core contracts are semantic **MUSTs**;
+- the agent **MUST** verify before claiming completion and use the single user-visible Harness Status at required phase boundaries for non-trivial work;
+- verification hooks may only remind when evidence is missing, but the semantic verification obligation remains **MUST**;
+- Tier-3/Fable broad mutation **MUST** resolve isolation disposition: verified linked worktree or explicit degraded fallback;
+- iteration, revision, replan, and worker counts are **MAY** planning hints only.
 
-None of those cognitive workflow conditions should trap a session or require a reset command.
+Those cognitive workflow conditions **MUST NOT** trap a session or require a reset command.
 
 A semantic MUST is not the same thing as a hard runtime lock. User-visible status, routing/applicability obligations, and verification-before-claim can remain mandatory agent contracts while host hooks observe or remind on a best-effort basis. Do not downgrade a semantic obligation to optional advice merely because the host cannot block it.
 
@@ -41,11 +42,11 @@ The two intentionally separate hard boundaries are:
 
 ```text
 route
-  -> selected workflow guidance
-  -> execute freely
+  -> selected workflow semantic contract
+  -> execute with model-chosen tactics
   -> observe edits / verification / stage evidence
   -> emit reminders when evidence is weak
-  -> complete or continue
+  -> complete only when MUST obligations resolve
 
 same failure signature x3
   -> zoom-out reflection required
@@ -55,7 +56,7 @@ same failure signature x3
 
 There is no `budget-exhausted -> blocked -> reset-budget` lifecycle.
 
-## Numeric guidance
+## Numeric MAY hints
 
 Router plans may still expose values such as:
 
@@ -64,13 +65,13 @@ Router plans may still expose values such as:
 - `maxReplans`
 - `maxWorkers`
 
-These are **advisory defaults**, useful for prompts, diagnostics, or planning. Runtime hooks do not maintain authoritative counters, reserve mutation capacity, or reject the Nth event.
+These are **MAY planning hints**, useful for prompts, diagnostics, or planning. Runtime hooks do not maintain authoritative counters, reserve mutation capacity, or reject the Nth event.
 
-A long loop should produce a message such as:
+A long loop **SHOULD** produce a message such as:
 
 > Iterative work is getting long; verify assumptions or consider re-planning.
 
-It should not create a lock.
+It **MUST NOT** create a lock.
 
 ## Mutation observation
 
@@ -86,19 +87,19 @@ A workflow may retain `blocked` as a descriptive status recorded by the controll
 
 ## Fable and worktrees
 
-Fable stage graphs, dependencies, write sets, and objective checks remain useful planning/evidence structures. `maxWorkers` no longer chunks ready stages as a hard concurrency cap.
+When a Fable topology is selected, its stage graphs, dependencies, write sets, objective checks, synthesis barrier, and required verifier are semantic **MUSTs**. `maxWorkers` remains a **MAY** planning hint and no longer chunks ready stages as a hard concurrency cap.
 
-For major work, a linked worktree remains strongly recommended. Missing isolation is surfaced prominently, but Harness-owned cognitive workflow hooks do not turn it into a self-deadlocking runtime state.
+For Tier-3/Fable broad mutation, isolation disposition is a semantic **MUST**: use/reuse a verified linked worktree, or record an explicit degraded fallback when isolation is unavailable or the user explicitly chooses to stay in place. Missing isolation is surfaced prominently, but Harness-owned cognitive workflow hooks do not turn it into a self-deadlocking runtime state.
 
 ## Legacy state
 
-Existing sessions may contain `budget.state = "budget-exhausted"`, old counters, or mutation-probe files from earlier versions. Current runtime code treats the budget API as advisory compatibility only and creates no new mutation-probe state.
+Existing sessions may contain `budget.state = "budget-exhausted"`, old counters, or mutation-probe files from earlier versions. Current runtime code treats the budget API as MAY-planning compatibility only and creates no new mutation-probe state.
 
 Starting a fresh session remains the cleanest way to discard old evidence, but it is no longer required to recover from numeric budget exhaustion.
 
 ## Testing contract
 
-Regression tests should prove:
+Regression tests **MUST** prove:
 
 - reminders fire when relevant;
 - commands/Stop remain available;

package/environment-detection/SKILL.md

@@ -4,7 +4,7 @@ description: Use at session start (Discover phase) to detect and align with the
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.16.6
+  version: 0.19.1
 ---
 
 # Environment Detection & Shell Alignment
@@ -20,6 +20,8 @@ metadata:
 
 Boundary: stay inside `process.cwd()`. Detection never writes integrations or searches parent/cache paths for another runtime.
 
+**Strength:** before relying on environment-sensitive commands, paths, package managers, or host capabilities, relevant discovery is a semantic **MUST**. Hosts may satisfy it from trusted injected environment context instead of rerunning probes.
+
 ## Workflow
 
 1. Run `node "<this-skill-dir>/scripts/preflight.js"`; detect OS, shell, CLIs.

package/evals/harness-everything/tasks/positive-tier1.yaml

@@ -1,6 +1,6 @@
 id: positive-trivial-tier1-001
 name: Trivial edit routes to Tier 1
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through Harness: classify tier/topology, resolve suggested skills, apply semantic obligations, and keep tactics flexible. Use for software triage/routing/re-routing; not general Q&A or non-software writing."
 tags:
   - positive-trigger
   - tier-1

package/evals/harness-everything/tasks/positive-tier2.yaml

@@ -1,6 +1,6 @@
 id: positive-standard-tier2-001
 name: Standard bug fix routes to Tier 2
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through Harness: classify tier/topology, resolve suggested skills, apply semantic obligations, and keep tactics flexible. Use for software triage/routing/re-routing; not general Q&A or non-software writing."
 tags:
   - positive-trigger
   - tier-2

package/evals/harness-everything/tasks/positive-tier3.yaml

@@ -1,6 +1,6 @@
 id: positive-macro-tier3-001
 name: Architectural task routes to Tier 3
-description: "Route software/project work through the Harness kernel: classify Tier 1/2/3, surface planning guidance and applicable skills, then let the agent choose tactics. Use for software triage, routing, and re-routing; not general Q&A or non-software writing."
+description: "Route software/project work through Harness: classify tier/topology, resolve suggested skills, apply semantic obligations, and keep tactics flexible. Use for software triage/routing/re-routing; not general Q&A or non-software writing."
 tags:
   - positive-trigger
   - tier-3

package/evals/using-git-worktrees/tasks/positive-trigger.yaml

@@ -1,6 +1,6 @@
 id: positive-using-git-worktrees-001
 name: On-scope prompt triggers using-git-worktrees
-description: "Use when starting feature work needing isolation or before implementation plans - recommends an isolated workspace via native tools or git worktree fallback"
+description: "Use when work needs isolation or before major implementation plans - resolves workspace isolation via native tools or git worktree fallback, with an explicit degraded fallback when isolation is unavailable"
 tags:
   - positive-trigger
 inputs:

package/find-skills/SKILL.md

@@ -4,45 +4,36 @@ description: Search the agent-skills ecosystem (skills.sh / npx skills) when no
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.19.1
 ---
 
 # Find Skills
 
-## 📋 Skill Contract
+## Skill Contract
 
-| Component | Specification |
+| Component | Contract |
 | :--- | :--- |
-| **Trigger / Input** | Request to find an external skill. |
-| **Expected Output** | Skill pointer, applied skill, or fallback. |
-| **State Mutations** | Temp cache (default); native install opt-in. |
-| **Enforcement Gate** | Local first; explicit approval before applying third-party code; graceful npx failure. |
+| **Input** | No installed skill fits, or user asks to find one. |
+| **Output** | Vetted skill pointer, approved application, or fallback. |
+| **State** | Temp cache by default; permanent install is opt-in. |
+| **Gate** | Third-party fetch/apply/install requires explicit approval. |
 
 ## Workflow
 
-0. Check local coverage (router registry, `generated[]`) before live installs:
-```bash
-npx skills list --json          # project scope
-npx skills list -g --json       # global scope
-```
-1. Identify domain/task, check [skills.sh](https://skills.sh/), then search `npx skills find [query] [--owner <owner>]`.
-2. Verify: prefer 1K+ installs, official sources; read the unaudited SKILL.md.
-3. Present name/source/count; NEVER fetch/apply without explicit approval.
-4. Apply ephemerally (default, zero footprint):
-```bash
-node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>
-```
-Treat the printed output as binding for this request, like a loaded skill — not reference material. OS-temp cache (6h); nothing written to repo or manifest.json.
-5. Permanent install ONLY when the user says they will reuse it: `npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y`
-6. Nothing exists? Help directly; suggest `npx skills init <name>` if recurring.
-
-Deep dive: <this-skill-dir>/references/discovery-flow.md
+1. Check local coverage first: `npx skills list --json` and `npx skills list -g --json`.
+2. If uncovered, search skills.sh / `npx skills find [query] [--owner <owner>]`.
+3. Official/1K+ sources **SHOULD** rank first; **MUST** read the unaudited `SKILL.md`.
+4. Present name/source/count; **MUST** get explicit approval before fetching or applying third-party code.
+5. Ephemeral use is default: `node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>`. Treat its output as binding for this request.
+6. Permanent install **MUST** be explicitly requested: `npx skills add <owner/repo[@skill]> --agent <agent> [-g] -y`.
+7. No match: help directly; `npx skills init <name>` **MAY** be suggested for recurring needs.
 
 ## USE FOR:
-- finding an external skill when none installed fits
-- vetting third-party skills before applying them
-- ephemeral skill use without permanent installs
+- external skill discovery/vetting
+- approved ephemeral use
 
 ## DO NOT USE FOR:
-- authoring skills (`skill-creator`)
-- installing anything without explicit user approval
+- skill authoring (`skill-creator`)
+- unapproved third-party application/install
+
+Deep dive: <this-skill-dir>/references/discovery-flow.md

package/git-commit/SKILL.md

@@ -4,7 +4,7 @@ description: "Generate Angular-style commit messages after verifying the environ
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.19.1
 ---
 
 # Git Commit (Angular Style)
@@ -20,10 +20,10 @@ metadata:
 
 ## Quick Workflow
 
-1. `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
-2. `git diff --cached`; nothing staged → prompt user / stage targeted files.
+1. **MUST** run `git status`; no repo → offer `git init` or skip; submodules changed → commit first per `<this-skill-dir>/guides/SUBMODULES.md`.
+2. **MUST** inspect `git diff --cached` before committing. Nothing staged → prompt user / stage only user-authorized targeted files. Unrelated concerns **SHOULD** be split unless coupling or explicit user intent justifies one commit.
 3. Format `<type>(<scope>): <subject>` per `<this-skill-dir>/guides/ANGULAR_STYLE.md`. Multiline/Windows → `.git-commit-msg.txt` + `git commit -F`, clean up.
-4. `git commit -m "..."`, verify with `git log -1`.
+4. `git commit -m "..."`, then **MUST** verify the result with `git log -1`.
 
 ## USE FOR:
 - Commit request from the user