harness-everything 0.11.6 → 0.11.7

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.

package/docs/workflows/improve-codebase-architecture.md

@@ -1,68 +1,60 @@
 # Workflow: Improve Codebase Architecture
 
-> Finds deepening opportunities in the codebase, consolidating tightly-coupled modules and mapping dependencies visually using Mermaid diagram reports.
+> Finds thin or overweight modules and reshapes them into focused, single-responsibility units by dividing large objects and functions, isolating seams, and separating interfaces.
 
----
+Source of truth: `improve-codebase-architecture/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `improve-codebase-architecture` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Audit Request / Refactoring / SRP Object Splitting]) --> ScanDirectories["Scan code directories, CONTEXT.md & ADRs"]
-  ScanDirectories --> IdentifyTarget["Identify Monolithic Objects (>300 lines) or Shallow Modules"]
-  IdentifyTarget --> FormulatePlan["Formulate Deepening & SRP Object Extraction Plan"]
-  FormulatePlan --> Propose["Present Deepening & SRP Proposal to User"]
-  Propose --> UserApproved{"User Approves Proposal?"}
-  
-  UserApproved -->|Yes| CheckTests{"Existing Test Safety Net Present?"}
-  UserApproved -->|No| AdjustPlan["Adjust Proposal Scope"] --> Propose
-  
-  CheckTests -->|No Tests| WriteCharTests["Write Characterization Tests First"] --> ExecuteTDD
-  CheckTests -->|Tests Present| ExecuteTDD["Execute Object Extraction via TDD"]
-  
-  ExecuteTDD --> CheckErrors{"Cascading Errors > 3?"}
-  CheckErrors -->|Yes| Rollback["Rollback Changes & Trigger zoom-out"]
-  CheckErrors -->|No| Complete["Refactoring Complete & Record Lessons in self-evolve"]
+  RefactorAsk["Input: refactor architecture, split object, apply SRP, tech debt"] --> DiscoverScan["Scan CONTEXT.md, docs/adr/, and core interfaces first; no blind refactoring"]
+  DiscoverScan --> FindTargets["Target SRP violations over 300 lines or over 10 complexity, shallow modules, coupled seams"]
+  FindTargets --> Proposal["Present Deepening and SRP proposal: object splitting plus seam abstraction"]
+  Proposal --> Approved{"Proposal approved?"}
+  Approved -->|No| Proposal
+  Approved -->|Yes| SafetyNet{"Legacy code has tests?"}
+  SafetyNet -->|No| CharTests["Write Characterization Tests first via tdd"]
+  SafetyNet -->|Yes| Extract["Extract incrementally via tdd; verify tests after each change"]
+  CharTests --> Extract
+  Extract --> ErrorCheck{"More than 3 cascading errors?"}
+  ErrorCheck -->|Yes| Rollback["Rollback plus zoom-out; record traps in self-evolve"]
+  ErrorCheck -->|No| DoneState["Refactoring complete"]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `improve-codebase-architecture` 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: refactor / architecture / couple| ICA["improve-codebase-architecture / SKILL.md"]
-  ICA -->|Deductions challenged by SRE via| GrillMe["grill-me / SKILL.md"]
-  ICA -->|Guides large-scale structural rewrites in| Fable["fable-mode / SKILL.md"]
-  ICA -->|Extracts interfaces to simplify unit tests in| TDD["tdd / SKILL.md"]
+  TechDebt["Trigger: refactor architecture or split object or apply SRP or tech debt"] --> ICA["improve-codebase-architecture / SKILL.md"]
+  ICA --> TDD["tdd: Characterization Tests first, then incremental extraction"]
+  ICA --> ZoomOut["zoom-out: invoked with rollback after more than 3 cascading errors"]
+  ICA --> SelfEvolve["self-evolve: record traps"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `improve-codebase-architecture` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Monolithic file 'utils.js' handles email, token creation, DB pooling, and logging"] --> Trigger["improve-codebase-architecture skill analyzed"]
-  Trigger --> Audit["Analyzes dependency graphs and calculates coupling scores"]
-  Audit --> FindSeams["Identifies three distinct interfaces: IEmailService, ITokener, IDbPool"]
-  FindSeams --> GenMermaid["Output detailed Mermaid diagram visualizing the proposed separated structure"]
-  GenMermaid --> RefactorPlan["Drafts multi-stage module extraction plan"]
-  RefactorPlan --> Done([Clear, modular architectural blueprint established])
+  BloatedUtil["utils.js handles email, tokens, DB pooling, logging"] --> ScanInterfaces["Scan CONTEXT.md, ADRs, core interfaces"]
+  ScanInterfaces --> SRPProposal["Propose split into focused units plus seam abstractions"]
+  SRPProposal --> CharNet["Add Characterization Tests for untested legacy paths"]
+  CharNet --> Incremental["Incremental extraction with test check after each step"]
+  Incremental --> RollbackGate{"More than 3 cascading errors?"}
+  RollbackGate -->|Yes| RollbackZoom["Rollback and zoom-out"]
+  RollbackGate -->|No| ModularDone["SRP-compliant modules with safety net"]
 ```
 
----
+Concrete example: a 600-line utility module is scanned for interfaces and ADR constraints, proposed for splitting into single-purpose units, guarded by Characterization Tests, then extracted step by step with verification after each change.
 
-## 4. Verification Check
+Deep detail: `improve-codebase-architecture/references/README.md`.
 
-To ensure that the `improve-codebase-architecture` 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.
+- [ ] `CONTEXT.md`, `docs/adr/`, and core interfaces scanned first; no blind refactoring
+- [ ] Targets match the skill bar: SRP violations over 300 lines or over 10 complexity, shallow modules, coupled seams
+- [ ] Deepening and SRP proposal with object splitting and seam abstraction presented and approved before code changes
+- [ ] `tdd` launched; Characterization Tests added first when legacy code lacks tests
+- [ ] Extraction done incrementally with tests verified after each change
+- [ ] On more than 3 cascading errors, changes rolled back with `zoom-out` and traps recorded in `self-evolve`
+- [ ] Not used for features, bugfixes, or style-only cleanups with no structure change

package/docs/workflows/install-cognitive-os.md

@@ -1,60 +1,67 @@
 # Workflow: Install Cognitive OS
 
-> Automates the installation of the Agent Cognitive Loop (Think > Try > Summarize > Record) into the user's active workspace and environment configs.
+> Explain or explicitly apply the Harness cognitive policy: Discover, Think, Try, Summarize, Record. This skill is a human-readable/manual entry point, not an installer and not a required peer-skill selection.
+
+Source of truth: `install-cognitive-os/SKILL.md`. Deep dive: `install-cognitive-os/references/cognitive-loop.md`.
+
+The runtime invariant contract is established by supported host integrations independently of this skill. Domain skills never need to invoke this skill first as long as Harness invariants remain satisfied.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `install-cognitive-os` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Bootstrap Hook Triggered]) --> DetectTargetEnv["Scan for active IDE / Client config paths"]
-  DetectTargetEnv --> InjectAdvisoryRules["Append advisory rules to .cursorrules, .github/copilot-instructions.md, or AGENTS.md"]
-  InjectAdvisoryRules --> InstallHooks["Configure Claude Code settings.json hook pre-flights"]
-  InstallHooks --> DeployScripts["Deploy core bootstrap.js, self-heal.js, and tier-router.js scripts"]
-  DeployScripts --> RunVerification["Execute self-heal audit test to confirm platform integrations"]
-  RunVerification --> End([Harness cognitive guardrails fully established])
+  Start([Explicit request OR host without kernel context]) --> Discover["Discover: verify relevant workspace state with read-only tools"]
+  Discover --> Think["Think: establish intent, scope, and failure modes"]
+  Think --> Try["Try: make the smallest useful change and gather evidence"]
+  Try --> Summarize["Summarize: ground conclusions in tool output"]
+  Summarize --> FailCheck{Same-signature failure x3?}
+  FailCheck -->|Yes| ZoomOut["zoom-out: stop edits, rebuild facts, report RESUME or ESCALATE"]
+  FailCheck -->|No| Record["Record: persist milestones only when evidence supports them"]
+  ZoomOut --> Think
+  Record --> End([Evidence-grounded work, no fixed domain sequence])
 ```
 
+This skill writes no installer state, deploys no hooks, and copies no skill directories. Workspace installation is owned by the general installer (`node scripts/installer.js`), not by this skill.
+
 ---
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `install-cognitive-os` 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
-  BootstrapCmd["Bootstrap CLI Command / npm install"] --> InstallSkill["install-cognitive-os / SKILL.md"]
-  InstallSkill -->|Deploys core router script| Router["harness-everything / scripts / tier-router.js"]
-  InstallSkill -->|Establishes memory loop configs for| Evolve["self-evolve / SKILL.md"]
-  InstallSkill -->|Guards all file edits using| Todo["todo-driven-workflow / SKILL.md"]
-  InstallSkill -->|Enforces Always-On Normalization for all responses| ADHD["Always-On ADHD-Friendly Output Shaping"]
+  Trigger["Explain policy / Apply loop manually / Debug cognitive behavior"] --> Skill["install-cognitive-os / SKILL.md"]
+  Skill -->|No kernel context| Manual["Run Discover → Think → Try → Summarize → Record explicitly"]
+  Skill -->|Kernel present| Policy["Treat as policy reference; domain skill proceeds directly"]
+  Manual --> Gates["Gates: evidence before claims; re-plan after x3 same-signature failures"]
+  Policy --> Gates
+
+  style Skill fill:#d35400,stroke:#e67e22,stroke-width:2px,color:#ffffff
+  style Gates 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 `install-cognitive-os` skill, illustrating standard success paths, error handling, or recovery loops.
-
 ```mermaid
 graph TD
-  Start["Fresh repository checkout"] --> Trigger["Run 'node scripts/installer.js install --all --yes'"]
-  Trigger --> Scan["Detects Cursor editor rules and GitHub action configurations"]
-  Scan --> BuildAdvisory["Appends mandatory routing checkpoint and cognitive compliance blocks to .cursorrules"]
-  BuildAdvisory --> CopySkills["Copies all current skills into .cursor/skills/ and .github/skills/"]
-  CopySkills --> CheckHeal["Runs preflight audit to confirm 100% path coverage"]
-  CheckHeal --> Done([Harness OS environment setup is complete and active])
-```
+  Case1["User on advisory-only host: 'walk me through the loop'"] --> Explain["Explain Discover → Think → Try → Summarize → Record with a small example"]
+  Explain --> Done1([User can apply the loop manually])
 
----
+  Case2["Host without automatic kernel context"] --> Apply["Apply the five steps explicitly to the task at hand"]
+  Apply --> Done2([Work proceeds with evidence gates, no hook installation claimed])
+
+  Case3["User asks for domain work: 'implement feature X test-first'"] --> Direct["Proceed directly with tdd; this skill is NOT a prerequisite"]
+  Direct --> Done3([Domain skill executes under Harness invariants])
+```
 
 ## 4. Verification Check
 
 To ensure that the `install-cognitive-os` 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.
+- [ ] **Policy, not installation**: no hook deployment, file copying, or config mutation claimed as this skill's effect.
+- [ ] **Full five-step loop**: Discover → Think → Try → Summarize → Record applied in order, not the truncated four-step variant.
+- [ ] **Evidence gates honored**: completion claims need evidence; repeated same-signature failures require re-planning via `zoom-out`.
+- [ ] **No prerequisite fabrication**: domain skills (`tdd`, `security-review`, `repo-docs`) proceed without selecting this skill first.

package/docs/workflows/repo-docs.md

@@ -1,64 +1,53 @@
 # Workflow: Repo Docs
 
-> Generates high-quality, professional README.md and AGENTS.md files based on actual workspace structures and product-archetype templates.
+> Creates or refreshes reader-focused README.md and AGENTS.md from real repository scans, carefully blending discovered facts with existing custom notes for projects missing docs or needing better agent onboarding.
 
----
+Source of truth: `repo-docs/SKILL.md`.
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `repo-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Generate / Update Repository Docs]) --> AuditProjectStructure["Audit workspace directory tree & build configs"]
-  AuditProjectStructure --> CheckExisting{Existing README / AGENTS File Found?}
-  
-  CheckExisting -->|Yes| ReadOld["Read Existing File & Extract Bespoke Notes (env vars, URLs, gotchas)"]
-  CheckExisting -->|No| ClassifyProductArchetype["Classify repository archetype"]
-  
-  ReadOld --> ClassifyProductArchetype
-  ClassifyProductArchetype --> LoadTemplates["Load standard README and AGENTS templates"]
-  LoadTemplates --> SmartMerge["Smartly Merge Codebase Facts + Bespoke Notes + Template Structure"]
-  SmartMerge --> FormatMarkdown["Format documents following clean layout rules"]
-  FormatMarkdown --> WriteFiles["Save / Merge README.md and AGENTS.md at Root or .github/"]
-  WriteFiles --> End([Professional onboarding documentation created without losing history])
+  MissingDocs["Input: missing docs or request to update README.md and AGENTS.md"] --> ScanConfigs["Scan configs such as package.json and Cargo.toml as Source of Truth; never fabricate"]
+  ScanConfigs --> ReadExisting["Read existing docs fully first; extract bespoke notes: env vars, URLs, gotchas"]
+  ReadExisting --> PickTemplate["Pick template from repo-docs/templates/ else built-in structure"]
+  PickTemplate --> DraftDocs["Draft README as user journey; AGENTS.md as conventions and build/test commands"]
+  DraftDocs --> VerifyCmds["Verify commands run; mark doubts with TODO Pending confirmation; ask via grill-me"]
+  VerifyCmds --> WriteRoot["Write to root; if protected use .github/AGENTS.md or docs/README.md"]
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `repo-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: doc / readme / agents-template| RepoDocs["repo-docs / SKILL.md"]
-  RepoDocs -->|Integrates frontmatter constraints into| BMAS["multi-agent-workspace / SKILL.md"]
-  RepoDocs -->|Leverages ADR details generated in| GWD["grill-with-docs / SKILL.md"]
+  UndocProject["Trigger: undocumented project needs README"] --> RepoDocs["repo-docs / SKILL.md"]
+  StructuralChange["Trigger: structural change needs AGENTS.md refresh"] --> RepoDocs
+  RepoDocs --> GrillMe["grill-me: clarify doubts marked TODO Pending confirmation"]
+  RepoDocs --> WriteOut["Write README.md and AGENTS.md to root or fallback locations"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `repo-docs` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["New library lacks onboarding docs and setup details"] --> Trigger["repo-docs skill invoked"]
-  Trigger --> Scan["Scans folders: discovers it's a TypeScript utility package"]
-  Scan --> MatchTemplate["Loads library archetype README template"]
-  MatchTemplate --> GenDocs["Outputs README.md with TypeScript usage examples, badges, and structure"]
-  GenDocs --> GenOnboarding["Outputs AGENTS.md defining the developer agent rules for the repo"]
-  GenOnboarding --> Done([Clean, standardized documentation committed])
+  BareRepo["New TypeScript utility package with no onboarding docs"] --> ScanProj["Scan package.json and directory tree"]
+  ScanProj --> PreserveNotes["Read existing stub docs; preserve custom env vars and gotchas"]
+  PreserveNotes --> SelectTemplate["Select library README template from repo-docs/templates/"]
+  SelectTemplate --> MergeDraft["Merge scan facts plus bespoke notes into README journey and AGENTS conventions"]
+  MergeDraft --> VerifyStep["Verify build and test commands; mark unconfirmed items TODO Pending confirmation"]
+  VerifyStep --> PublishDocs["Write README.md and AGENTS.md to root or fallback"]
 ```
 
----
+Concrete example: an undocumented utility repo is scanned for its real entry points and scripts, its bespoke environment notes are preserved, a template from `repo-docs/templates/` shapes the draft, commands are verified, and the merged README and AGENTS files are written without blind overwrites.
 
-## 4. Verification Check
+Deep detail: `repo-docs/references/process-guide.md`.
 
-To ensure that the `repo-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.
+- [ ] Configs scanned as Source of Truth; no facts fabricated without repo evidence
+- [ ] Existing docs read fully first; bespoke notes preserved and never overwritten blindly
+- [ ] Template picked from `repo-docs/templates/` or built-in structure applied
+- [ ] `README.md` covers the user journey; `AGENTS.md` covers conventions and build/test commands
+- [ ] Commands verified to run; unresolved doubts marked `// TODO: Pending confirmation` and clarified with `grill-me`
+- [ ] Written to root, or to `<workspace>/.github/AGENTS.md` and `<workspace>/docs/README.md` when root is protected
+- [ ] Not used for marketing copy, fabrication without scanning, or non-repository wikis