harness-everything 0.11.5 → 0.11.7

package/docs/workflows/git-commit.md

@@ -1,71 +1,79 @@
 # Workflow: Git Commit
 
-> Generates semantic, Angular-style conventional commits after verifying the workspace, staged files, and active language contexts.
+> Create clean Angular-style commit messages for an explicit commit request or a finished task phase, after checking repo state, submodules, and staged changes.
 
----
+Source of truth: `git-commit/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `git-commit` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Trigger Commit Request / Task Complete]) --> CheckGit{Is Git Repo Initialized?}
-  CheckGit -->|No| OfferInit["Prompt User: Run git init or Skip Commit"]
-  CheckGit -->|Yes| CheckSubmodules{Has Submodule Changes?}
-  
-  CheckSubmodules -->|Yes| CommitSubmodules["Commit Submodules First (Bottom-Up)"] --> CheckStatus
-  CheckSubmodules -->|No| CheckStatus["Run git status & git diff --cached"]
-  
-  CheckStatus --> StageCheck{Are Files Staged?}
-  StageCheck -->|No| AskStage["Prompt User / Stage Targeted Files"] --> FormatMessage
-  StageCheck -->|Yes| FormatMessage["Format Angular Commit Message"]
-  
-  FormatMessage --> CheckShell{Shell / Multiline Escaping Check?}
-  CheckShell -->|Simple Single Line| DirectCommit["Run git commit -m 'type(scope): subject'"]
-  CheckShell -->|Multiline / Windows| TempFileCommit["Write .git-commit-msg.txt -> Run git commit -F -> Cleanup"]
-  
-  DirectCommit --> VerifyCommit["Run git log -1 to Verify"]
-  TempFileCommit --> VerifyCommit
-  VerifyCommit --> End([Staging Clean and Committed])
+  CommitTrig([Commit requested or phase concluded]) --> StatusCheck[Run git status]
+  StatusCheck --> RepoOk{Git repo present?}
+  RepoOk -->|no| InitOffer[Offer git init or skip]
+  RepoOk -->|yes| SubCheck[Check submodule changes per SUBMODULES guide]
+  SubCheck --> SubDirty{Submodules changed?}
+  SubDirty -->|yes| SubFirst[Commit submodules first]
+  SubDirty -->|no| DiffCheck[Run git diff-cached]
+  SubFirst --> DiffCheck
+  DiffCheck --> StagedOk{Anything staged?}
+  StagedOk -->|no| PromptStage[Prompt user and stage targeted files]
+  StagedOk -->|yes| FormatMsg[Format type-scope-subject message]
+  PromptStage --> FormatMsg
+  FormatMsg --> VerifyLog[Commit then verify with git log -1]
+  VerifyLog --> DoneClean([Tree updated and clean])
 ```
 
----
+```mermaid
+graph TD
+  FormatSimple[Formatted Angular message] --> EscCheck{Simple single line?}
+  EscCheck -->|yes| DirectM[git commit -m]
+  EscCheck -->|no multiline or Windows| TempF[Write commit-msg file then git commit -F and cleanup]
+  DirectM --> LogOne[git log -1 verifies commit]
+  TempF --> LogOne
+  LogOne --> CleanTree([Working tree clean])
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `git-commit` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
 graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: commit / git / save| GitCommit["git-commit / SKILL.md"]
-  GitCommit -->|Formats according to| Guide["git-commit / guides / ANGULAR_STYLE.md"]
-  GitCommit -->|Integrates with pre-commit gates| VerLoop["verification-loop / SKILL.md"]
-  GitCommit -->|Composed after history squashes| Rewrite["rewrite-commits / SKILL.md"]
+  UserReq[User requests commit] --> GitSkill[git-commit SKILL]
+  PhaseDone[Task phase concludes with staged diff] --> GitSkill
+  GitSkill --> StatusGate[git status gate]
+  StatusGate --> SubGuide[guides SUBMODULES.md if needed]
+  SubGuide --> StyleGuide[guides ANGULAR_STYLE.md formatting]
+  StyleGuide --> CommitVerify[Commit and git log -1 check]
 ```
 
----
+## 3. Real-World Use Case
 
-## 3. Real-World Use Case Flowchart
+Developer finishes an auth fix and asks for a commit.
 
-Here we model concrete real-world scenarios and use cases of the `git-commit` skill, illustrating standard success paths, error handling, or recovery loops.
+1. Run `git status`; if not a repo, offer `git init` or skip.
+2. If submodules changed, commit those first per `git-commit/guides/SUBMODULES.md`.
+3. Run `git diff --cached`; if nothing staged, prompt before staging targeted files.
+4. Format `<type>(<scope>): <subject>` per `git-commit/guides/ANGULAR_STYLE.md`.
+5. Use `git commit -m` for a simple line, or `.git-commit-msg.txt` + `git commit -F` with cleanup for multiline/Windows, then verify with `git log -1`.
 
 ```mermaid
 graph TD
-  Start["Developer completes feature & runs 'git add .'"] --> Trigger["Invoke git-commit skill"]
-  Trigger --> Analyze["Skill parses staged diff: 'src/auth.js (+15,-2)'"]
-  Analyze --> DetectScope["Deduce scope: 'auth' and type: 'feat'"]
-  DetectScope --> BuildMessage["Build message: 'feat(auth): add JWT token expiration check'"]
-  BuildMessage --> Commit["Execute git commit -m 'feat(auth): add JWT token expiration check'"]
-  Commit --> Done(["Repository index updated cleanly"])
+  DevDone[Auth fix finished and staged] --> CheckStatus[Run git status and cached diff]
+  CheckStatus --> FmtMsg[Format feat-auth style message]
+  FmtMsg --> PickMethod{Multiline or Windows?}
+  PickMethod -->|no| CommitM[git commit -m]
+  PickMethod -->|yes| CommitF[git commit -F with temp file]
+  CommitM --> VerifyOne[git log -1]
+  CommitF --> VerifyOne
+  VerifyOne --> CleanDone([Committed and verified])
 ```
 
----
-
 ## 4. Verification Check
 
-To ensure that the `git-commit` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] `git status` ran first; non-repo offered `git init` or skip, and empty staging prompted the user instead of committing nothing
+- [ ] Submodule changes were handled first per `git-commit/guides/SUBMODULES.md`
+- [ ] Staged diff was reviewed with `git diff --cached`, with targeted staging only after confirmation
+- [ ] Message followed `<type>(<scope>): <subject>` per `git-commit/guides/ANGULAR_STYLE.md`
+- [ ] Multiline/Windows path used `.git-commit-msg.txt` + `git commit -F` with cleanup; simple path used `git commit -m`; result verified with `git log -1`
+- [ ] No branch, rebase, merge, or push was performed, and no staging happened without confirmation
+- [ ] Detail followed `git-commit/references/commit-flow.md` where needed

package/docs/workflows/grill-me.md

@@ -1,62 +1,60 @@
 # Workflow: Grill Me
 
-> Relentless Challenger interview process that stress-tests architectural plans, highlights hidden assumptions, and demands explicit edge-case handling.
+> A demanding challenger that pressure-tests vague plans and architectures one question at a time, exposes loopholes and undefined boundaries, counters sycophantic agreement, keeps the CONTEXT.md glossary current, and passes settled decisions to to-spec for formal specs and ADRs.
 
----
+Source of truth: `grill-me/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `grill-me` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Developer Proposes Plan]) --> Discovery["Scan Related Code, CONTEXT.md & Existing ADRs"]
-  Discovery --> AskQuestion["Ask Exactly ONE Question at a Time (with AI Recommendation)"]
-  AskQuestion --> ReceiveAnswer["Receive Developer Answer & Resolve Branch"]
-  ReceiveAnswer --> UpdateGlossary["Update CONTEXT.md Glossary Inline"]
-  UpdateGlossary --> ValidateResilience{All Decision Tree Branches Resolved?}
-  ValidateResilience -->|No| AskQuestion
-  ValidateResilience -->|Yes| HandoffToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
-  HandoffToSpec --> End([Route to to-tickets / fable-mode / tdd])
+  Propose["Vague plan or architecture proposal received"] --> Discover["Scan plan code plus CONTEXT.md, README.md, docs/adr/"]
+  Discover --> DomainTerms["Grill using project domain model and terminology"]
+  DomainTerms --> AskOne["Ask exactly ONE question with attached insight"]
+  AskOne --> ResolveBranch["Resolve decision-tree branch before moving on"]
+  ResolveBranch --> UpdateGlossary["Update CONTEXT.md glossary inline"]
+  UpdateGlossary --> ConsensusCheck{"Consensus on all branches?"}
+  ConsensusCheck -->|No| AskOne
+  ConsensusCheck -->|Yes| HandoffSpec["Hand off to to-spec to preview outline and publish"]
+  HandoffSpec --> RouteExec["Route execution to to-tickets, fable-mode, or tdd"]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `grill-me` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
 graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: grill / debate / plan| GrillMe["grill-me / SKILL.md"]
-  GrillMe -->|Vague proposal or technical robustness needed| GrillMe
-  GrillMe -->|Needs glossary/ADR documentation alignment| GWD["grill-with-docs / SKILL.md"]
-  GWD -->|Directs macro execution strategies of| Fable["fable-mode / SKILL.md"]
+  VaguePlan["Input: vague plan proposal"] --> GrillMe["grill-me / SKILL.md"]
+  EvaluateArch["Input: evaluate architecture request"] --> GrillMe
+  ExplicitAsk["Input: explicit grill me request"] --> GrillMe
+  GrillMe --> ToSpec["to-spec: preview outline and publish PRD, CLI/API reference, Schema doc, or ADR"]
+  ToSpec --> ToTickets["to-tickets for execution"]
+  ToSpec --> FableMode["fable-mode for execution"]
+  ToSpec --> TDD["tdd for execution"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `grill-me` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Proposal: 'I will write a fast cron job to sync database tables directly'"] --> Trigger["grill-me skill activated"]
-  Trigger --> Challenger["Challenger SRE: 'What happens if the cron script fails mid-sync? Will there be database lock contention? How do we prevent partial/corrupt states?'"]
-  Challenger --> Answer1["Dev: 'I'll add database transaction wraps and skip locks'"]
-  Answer1 --> Challenger2["Challenger: 'How will we monitor and alert if locks are skipped repeatedly?'"]
-  Challenger2 --> Answer2["Dev: 'I'll add structured logging and trigger a standard Slack web-hook alerting'"]
-  Answer2 --> Approve["Challenger: 'Excellent. Let's record these lock-skip alerts as mandatory requirements.'"]
-  Approve --> Done([Plan hardened and logged])
+  CronProposal["Proposal: nightly cron syncs tables directly"] --> GrillStart["grill-me starts single-question loop"]
+  GrillStart --> Q1["Q1: What happens on mid-sync failure with locks held?"]
+  Q1 --> A1["Answer: wrap in transactions, define lock behavior"]
+  A1 --> Glossary1["Update CONTEXT.md glossary for sync and lock terms"]
+  Glossary1 --> Q2["Q2: What are boundary conditions for partial state?"]
+  Q2 --> Consensus["Consensus reached on failure and boundary handling"]
+  Consensus --> SpecHandoff["to-spec publishes ADR and spec"]
 ```
 
----
+Concrete example: a developer proposes a direct table-sync cron job. `grill-me` scans `CONTEXT.md` and related code, asks one question about mid-sync failure, resolves it, updates the glossary, asks the next question about monitoring and boundary conditions, then hands the hardened decisions to `to-spec` for a PRD or ADR. Execution follows via `to-tickets`, `fable-mode`, or `tdd`.
 
-## 4. Verification Check
+Deep detail: `grill-me/references/grilling-playbook.md`.
 
-To ensure that the `grill-me` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 4. Verification Check
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Exactly ONE question asked at a time; questionnaires prohibited
+- [ ] Each question carries the agent's insight and its branch is resolved before advancing
+- [ ] Questions use the project's domain model and terminology from `CONTEXT.md`, `README.md`, and `docs/adr/`
+- [ ] `CONTEXT.md` glossary updated inline as terms resolve; document creation left to `to-spec`
+- [ ] On consensus, `to-spec` invoked to preview outline and publish PRD, CLI/API reference, Schema doc, or ADR
+- [ ] No code implementation or ticket breakdown inside this skill; execution routed to `to-tickets`, `fable-mode`, or `tdd`
+- [ ] Not used for casual Q and A, direct spec writing, or ticket breakdown of an approved spec

package/docs/workflows/grill-with-docs.md

@@ -1,69 +1,59 @@
-# Workflow: Grill with Docs
+# Workflow: Grill With Docs
 
-> Decision tracking, Glossary alignment, and ADR-driven (Architecture Decision Record) grilling to eliminate technical drift between code and documentation.
+> Tests a plan against the recorded domain language and past decisions, tightens fuzzy terminology into canonical terms, and writes CONTEXT.md and ADR updates inline as choices settle.
 
----
+Source of truth: `grill-with-docs/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `grill-with-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Plan Proposed against Domain]) --> CheckCoreValidity{Plan vague or unverified?}
-  CheckCoreValidity -->|Yes| RecommendGrillMe["Recommend running grill-me first"]
-  CheckCoreValidity -->|No| ReadDomainModel["Read CONTEXT.md and existing ADRs"]
-  RecommendGrillMe --> EndVague([Postponed until plan is hardened])
-  ReadDomainModel --> ChallengeDrift["Examine plan for term drift or architectural violations"]
-  ChallengeDrift --> UpdateGlossary["Refine and match terminology with current Glossary"]
-  UpdateGlossary --> ResolveADRPath{Resolve ADR Storage Path}
-  
-  ResolveADRPath -->|docs/adr/ or CONTEXT-MAP.md Exists| WriteDocs["Write ADR to docs/adr/ or CONTEXT-MAP.md Location"]
-  ResolveADRPath -->|No Folder Found| WriteFallback["Write to committable docs/adr"]
-  
-  WriteDocs --> ToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
-  WriteFallback --> ToSpec
-  ToSpec --> End([Route to to-tickets / fable-mode / tdd])
+  PlanInput["Plan needing domain alignment"] --> ResolveStorage["Resolve storage with project-docs-resolver.js; CONTEXT-MAP.md root wins"]
+  ResolveStorage --> ChallengeTerms["Challenge glossary conflicts; sharpen fuzzy terms to canonical ones"]
+  ChallengeTerms --> ScenarioTest["Stress-test relationships with concrete scenarios; cross-check claims against code"]
+  ScenarioTest --> InlineUpdate["Update context glossary inline, never batched; zero implementation details"]
+  InlineUpdate --> ADRGate{"ADR warranted: hard to reverse plus surprising without context plus real trade-off?"}
+  ADRGate -->|Yes| WriteADR["Offer and write ADR at resolved location"]
+  ADRGate -->|No| SkipADR["Skip ADR; keep pure glossary"]
+  WriteADR --> Handoff["Hand off aligned design to to-spec"]
+  SkipADR --> Handoff
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `grill-with-docs` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
 graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: adr / decision / glossary| GWD["grill-with-docs / SKILL.md"]
-  GrillMe["grill-me / SKILL.md"] -->|Hardened plan ready for formalization| GWD
-  GWD -->|Aligns documentation during macro work in| Fable["fable-mode / SKILL.md"]
-  GWD -->|Triggers todo tasks tracked by| Todo["todo-driven-workflow / SKILL.md"]
-  GWD -->|Hands off to generate specifications| ToSpec["to-spec / SKILL.md"]
+  DomainStress["Input: stress-testing a plan against domain language and documented decisions"] --> GWD["grill-with-docs / SKILL.md"]
+  GWD --> GrillMe["grill-me for unverified design"]
+  GWD --> ToSpec["to-spec for aligned design"]
+  ToSpec --> ToTickets["to-tickets for execution"]
+  ToSpec --> FableMode["fable-mode for execution"]
+  ToSpec --> TDD["tdd for execution"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `grill-with-docs` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Requirement: Change notification retry rate limits"] --> Trigger["grill-with-docs skill invoked"]
-  Trigger --> ReadDocs["Analyzes docs/adr/003-rate-limiting.md"]
-  ReadDocs --> CheckDrift["Finds that proposed change violates the maximum overload protection limit"]
-  CheckDrift --> RefinePlan["Plan updated to stay within the 003-rate-limiting contract"]
-  RefinePlan --> CreateADR["Create docs/adr/008-notification-retries.md"]
-  CreateADR --> SyncCode["Modify code and inject aligned TODO tags directly in code to maintain truth"]
-  SyncCode --> Done([Zero architectural drift achieved])
+  RetryProposal["Proposal: change notification retry limits"] --> ResolveDocs["Resolve docs location; read CONTEXT.md and rate-limit ADR"]
+  ResolveDocs --> Conflict["Find glossary conflict: retry versus backoff"]
+  Conflict --> Scenario["Scenario test: burst retry against overload protection limit"]
+  Scenario --> GlossaryFix["Inline glossary fix to canonical terms"]
+  GlossaryFix --> ADRDecision["ADR offered because limit change is hard to reverse and involves trade-off"]
+  ADRDecision --> AlignedHandoff["Aligned design to to-spec; execution to to-tickets, fable-mode, or tdd"]
 ```
 
----
+Concrete example: a retry-limit change is checked against the existing rate-limiting ADR and code. Fuzzy retry language is sharpened, the glossary is fixed inline, and only because the decision is hard to reverse and surprising without context is an ADR written. An unverified design would go to `grill-me` first instead.
 
-## 4. Verification Check
+Deep detail: `grill-with-docs/references/session-playbook.md`. Formats: `grill-with-docs/ADR-FORMAT.md`, `grill-with-docs/CONTEXT-FORMAT.md`.
 
-To ensure that the `grill-with-docs` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 4. Verification Check
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Storage resolved with `multi-agent-workspace/scripts/project-docs-resolver.js`; `<workspace>/CONTEXT-MAP.md` root wins
+- [ ] Fuzzy terms sharpened to canonical ones; glossary stays pure with zero implementation details
+- [ ] Relationships tested with concrete scenarios and claims cross-checked against code
+- [ ] Context glossary updated inline, never batched
+- [ ] ADR offered only when hard to reverse plus surprising without context plus a real trade-off
+- [ ] ADRs meet the 3-part bar; handoff to `to-spec` after alignment
+- [ ] Routing respected: unverified design to `grill-me`; aligned design to `to-spec`; execution to `to-tickets`, `fable-mode`, or `tdd`
+- [ ] Not used for verifying unstable designs without a grilling pass, and not used for spec publishing without grilling

package/docs/workflows/harness-everything.md

@@ -1,95 +1,97 @@
 # Workflow: Harness Everything
 
-> The single entry point and dynamic router of Harness OS, triaging tasks into appropriate tiers and auto-loading synergistic knowledge guides.
+> Route software/project work through the Harness kernel: classify Tier 1/2/3, establish mandatory invariants, then let the agent choose tactics and domain skills. Not general Q&A or non-software writing.
+
+Source of truth: `harness-everything/SKILL.md`. Deep dive: `harness-everything/references/triage-and-tiers.md`.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `harness-everything` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+The kernel establishes the smallest applicable workflow before mutation. Suggested skills are mandatory to evaluate and advisory to execute; the selected topology is mandatory to resolve.
 
 ```mermaid
 graph TD
   Start([User Prompt Received]) --> CheckSoftware{Software / Engineering Task?}
-  CheckSoftware -->|No: Pure Chat / Translation / Web Search| BypassHarness["Bypass Harness OS Completely - Reply Directly"]
-  CheckSoftware -->|Yes: Code / Architecture / Project| ExecuteRouter["Execute tier-router.js OR check UserPromptSubmit hook output"]
-  ExecuteRouter --> DetectNewFeature{Contains new logic/files?}
-  DetectNewFeature -->|Yes, enforce Tier 2+| PreventDegrade["Prevent Silent Degrade to Tier 1"]
-  PreventDegrade --> TriageTier
-  DetectNewFeature -->|No| TriageTier{Triage Tier}
-  
-  TriageTier -->|Tier 1: Trivial| Tier1Route["Tier 1: Direct Edit No Checklist"]
-  TriageTier -->|Tier 2: Standard| Tier2Route["Tier 2: TDD & Todo-driven work"]
-  TriageTier -->|Tier 3: Macro| Tier3Route["Tier 3: Fable Planning & Agent Scaffolding"]
-  
-  Tier1Route --> LoadGuides["Auto-load & output Synergistic Guides"]
-  Tier2Route --> LoadGuides
-  Tier3Route --> LoadGuides
-  
-  LoadGuides --> FactCheck{External Claims / Estimates?}
-  FactCheck -->|Yes| FactReminder["Append Fact-Audit Reminder"]
-  FactCheck -->|No| FinalizeOutput["Finalize Routing Checkpoint Output"]
-  FactReminder --> FinalizeOutput
-  FinalizeOutput --> Normalization["Apply Always-On ADHD-Friendly Output Shaping (Global Normalization)"]
-  Normalization --> End([Developer receives highly focused, concise response])
-  BypassHarness --> End
+  CheckSoftware -->|No: Pure Chat / Translation / Web Search| BypassHarness["Bypass Harness Completely - Reply Directly"]
+  CheckSoftware -->|Yes: Code / Architecture / Project| ExecuteRouter["Run kernel-router.js OR reuse UserPromptSubmit hook output"]
+  ExecuteRouter --> TriageTier{Triage Tier}
+  TriageTier -->|Tier 1: Trivial| Tier1Route["direct-single: smallest sufficient tactic"]
+  TriageTier -->|Tier 2: Standard| Tier2Route["iterative-single: verify each increment"]
+  TriageTier -->|Tier 3: Macro| Tier3Route["fable-staged / fable-parallel / fable-multi-agent-workspace"]
+  Tier1Route --> Checkpoint["Surface Harness Routing Checkpoint"]
+  Tier2Route --> Checkpoint
+  Tier3Route --> Checkpoint
+  Checkpoint --> Evaluate["Read each suggested SKILL.md: USE FOR, DO NOT USE FOR, flow, hard rules"]
+  Evaluate --> Execute["Execute selected topology to resolution"]
+  Execute --> VerifyGate{Objective evidence supports completion?}
+  VerifyGate -->|Yes| Done([Evidence-backed completion])
+  VerifyGate -->|No| Diagnose["Diagnose / bounded re-plan"]
+  Diagnose --> RetryCheck{Same-signature failure x3?}
+  RetryCheck -->|No| Execute
+  RetryCheck -->|Yes| ZoomOut["zoom-out: stop edits, rebuild facts read-only, report RESUME or ESCALATE"]
+  ZoomOut --> Execute
 ```
 
 ---
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `harness-everything` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+This diagram shows how the `harness-everything` skill is triggered and how it chains with companion skills. Routing suggestions are conditional on applicability; the selected topology is not advisory.
 
 ```mermaid
 graph LR
-  UserPrompt([User Input]) --> Router["harness-everything / tier-router.js"]
-  
-  Router -->|Keyword Matches| Guides["Synergistic Workflow Guides"]
-  
-  Guides -->|TDD/Test/Bug| Ch1["tdd + environment-detection + verify-before-claim + verification-loop"]
-  Guides -->|Git/Commit/PR| Ch2["git-commit + rewrite-commits + using-git-worktrees + verification-loop"]
-  Guides -->|Agent/Fable/Macro| Ch3["fable-mode + fable-discipline + multi-agent-workspace"]
-  Guides -->|Refactor/Architecture| Ch4["improve-codebase-architecture + grill-with-docs + grill-me + fable-mode"]
-  
-  Ch1 --> ADHD["Always-On ADHD-Friendly Output Shaping (Global Normalization)"]
-  Ch2 --> ADHD
-  Ch3 --> ADHD
-  Ch4 --> ADHD
-  
+  UserPrompt([User Input]) --> Router["harness-everything / kernel-router.js + tier-router.js"]
+
+  Router -->|Bug / Feature / Refactor| Ch1["tdd + todo-driven-workflow + verification-loop + verify-before-claim"]
+  Router -->|Commit / History / Isolation| Ch2["git-commit + rewrite-commits + using-git-worktrees + verification-loop"]
+  Router -->|Large / Multi-source / Multi-session| Ch3["fable-mode + fable-discipline + multi-agent-workspace + using-git-worktrees"]
+  Router -->|Architecture / Plan review| Ch4["improve-codebase-architecture + grill-me + grill-with-docs + to-spec + to-tickets"]
+
+  Ch1 --> Invariants["Invariants: route-before-execution, verify-before-claim, re-plan-after-x3, evaluate-before-skip, resolve-selected-workflow"]
+  Ch2 --> Invariants
+  Ch3 --> Invariants
+  Ch4 --> Invariants
+
   style Router fill:#d35400,stroke:#e67e22,stroke-width:2px,color:#ffffff
-  style ADHD fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#ffffff
+  style Invariants fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#ffffff
 ```
 
 ---
 
 ## 3. Real-World Use Case Flowchart
 
-Here we model concrete real-world scenarios and use cases of the `harness-everything` skill, illustrating standard success paths, error handling, or recovery loops.
-
 ```mermaid
 graph TD
-  Input1["User: 'Add a new settings page'"] --> Router1["tier-router.js executes"]
-  Router1 --> TrapCheck["Trap Avoided: Feature request correctly blocked from Tier 1 degrade"]
-  TrapCheck --> Triage2["Triaged as Tier 2: Standard Task"]
-  Triage2 --> DomainSummon["Load 'tdd' & frontend Domain Experts"]
-  DomainSummon --> BaseLoop["Initialize 'todo-driven-workflow' checklist"]
-  BaseLoop --> VerifyGate["Complete feature & run 'verification-loop' pre-delivery gate"]
-  VerifyGate --> Done1([Feature delivered safely with proof])
-  
-  Input2["User: 'Refactor DB architecture and grill my plan'"] --> Router2["tier-router.js executes"]
+  Input1["User: 'Add a new settings page'"] --> Router1["kernel-router.js executes"]
+  Router1 --> Triage2["Triaged as Tier 2: Standard Task"]
+  Triage2 --> Checkpoint1["Routing Checkpoint: tdd, todo-driven-workflow, verification-loop suggested"]
+  Checkpoint1 --> Eval1["Read each suggested SKILL.md; keep applicable, mark not-applicable with flow-grounded reason"]
+  Eval1 --> Exec1["Execute iterative-single to resolution; verify with tests before claiming done"]
+  Exec1 --> Done1([Feature delivered with objective evidence])
+
+  Input2["User: 'Refactor DB architecture across services'"] --> Router2["kernel-router.js executes"]
   Router2 --> Triage3["Triaged as Tier 3: Macro Task"]
-  Triage3 --> RecGuides["Auto-load: improve-codebase-architecture, grill-with-docs, fable-mode"]
-  RecGuides --> Process["Developer completes Grilling session to finalize ADRs"]
-  Process --> Execute["fable-mode generates execution checklist & spawns sub-agents"]
+  Triage3 --> Iso["Verify linked Git worktree isolation before source mutation"]
+  Iso --> Exec2["fable-mode stage map + per-stage checks + cold verification"]
+  Exec2 --> Done2([Staged delivery with per-stage evidence])
+
+  Input3["User: 'Just fix this typo'"] --> Router3["kernel-router.js executes"]
+  Router3 --> Triage1["Triaged as Tier 1: Trivial Task"]
+  Triage1 --> Exec3["direct-single: smallest sufficient edit, then verify"]
+  Exec3 --> Done3([Typo fixed, no ceremony added])
 ```
 
+Escape applies only to genuinely uncovered workflow scope with explicit scope + evidence; covered obligations, isolation, and independent verification survive escape. Model confidence alone never justifies skipping the selected topology.
+
 ---
 
 ## 4. Verification Check
 
 To ensure that the `harness-everything` skill is operating in strict compliance with Harness OS design laws, verify the following:
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] **Route before execution**: scope/tier and smallest applicable workflow established before mutation.
+- [ ] **Evaluate before omission**: each suggested skill's complete `SKILL.md` flow evaluated before deciding applicability.
+- [ ] **Resolve selected workflow**: the selected topology executed to resolution; escape only for uncovered scope with evidence.
+- [ ] **Verify before claim**: objective evidence (tests, checks, quoted tool output) supports completion.
+- [ ] **Re-plan on repetition**: after 3 same-signature failures, `zoom-out` reflection completed before resuming.