harness-everything 0.11.6 → 0.12.0

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

package/docs/workflows/rewrite-commits.md

@@ -1,60 +1,64 @@
 # Workflow: Rewrite Commits
 
-> Safely rewrites or squashes a specified range of commits into highly professional, Conventional Commits (Angular style) on a new branch.
+> Rewrites past Git history into Angular Style messages — cleaning unpushed commits before a PR, squashing fixups, rewording, and reordering safely on a temp branch with abort on conflict.
+
+Source of truth: `rewrite-commits/SKILL.md`.
 
 ---
 
 ## 1. Skill Behavior Workflow
 
-This section visualizes how the `rewrite-commits` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
 ```mermaid
 graph TD
-  Start([Define Commit Range]) --> BackupBranch["Create a backup branch of current state"]
-  BackupBranch --> ReadCommits["Read all commit messages in the range"]
-  ReadCommits --> AnalyzeDiffs["Read files & diffs associated with each commit"]
-  AnalyzeDiffs --> GenNewMessages["Generate high-quality Angular-style messages for each diff"]
-  GenNewMessages --> SoftReset["Execute git reset --soft to merge range changes"]
-  SoftReset --> ReapplyCommits["Re-apply changes with perfectly clean, segmented commit history"]
-  ReapplyCommits --> VerifyBranch["Run verification checks on the final rebuilt branch"]
-  VerifyBranch --> End([Perfectly clean Git history on new branch])
+  DiscoverRange["Discover: git log --oneline -n <num> to confirm range"] --> PushedGuard{"Pushed to remote main/master?"}
+  PushedGuard -->|Yes| WarnConfirm["Warn and require secondary human confirmation"]
+  PushedGuard -->|No| TempBranch["Create temp branch for rewrite"]
+  WarnConfirm --> TempBranch
+  TempBranch --> ResetSoft["Rewrite via git reset --soft HEAD~N plus structured commits"]
+  ResetSoft --> AngularMsg["Messages follow Angular Style per git-commit skill"]
+  AngularMsg --> ConfirmLog["Confirm with git log --oneline"]
+  ConfirmLog --> ConflictCheck{"Merge conflict?"}
+  ConflictCheck -->|Yes| AbortStop["Run git rebase --abort, STOP, hand to human or zoom-out"]
+  ConflictCheck -->|No| DoneHistory["Rewritten Angular-Style history on temp branch"]
 ```
 
----
+```mermaid
+graph TD
+  NoRebaseI["Gate: no bare interactive git rebase -i"] --> ScriptOpt["Use git reset --soft or Node.js scripting, no hardcoded sed -i"]
+  ScriptOpt --> DeepRef["Deep dive: rewrite-commits/references/workflow.md"]
+  DeepRef --> ConfirmOut["Expected output: temp-branch history confirmed via git log --oneline"]
+```
 
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `rewrite-commits` 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 / rewrite / squash| Rewrite["rewrite-commits / SKILL.md"]
-  Rewrite -->|Supplements convention templates in| GitCommit["git-commit / SKILL.md"]
-  Rewrite -->|Pre-verify rewritten commits via| VerLoop["verification-loop / SKILL.md"]
+  UserReq["User requests cleaning, squashing, or rewriting past history to Angular Style"] --> RewriteSkill["rewrite-commits / SKILL.md"]
+  RewriteSkill --> TempOut["Output: rewritten history on temp branch"]
+  RewriteSkill --> AbortPath["On conflict: git rebase --abort + handover"]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `rewrite-commits` skill, illustrating standard success paths, error handling, or recovery loops.
-
 ```mermaid
-graph TD
-  Start["Branch has messy commits: 'fixed stuff', 'more fixes', 'bug'"] --> Trigger["Rewrite-commits skill run for HEAD~3"]
-  Trigger --> Backup["Backup branch 'backup-feature-x' created"]
-  Trigger --> GatherDiffs["Analyze total diff across the 3 messy commits"]
-  GatherDiffs --> Generate完美["Determine changes relate to user auth session handling"]
-  Generate完美 --> Rebuild["Reset and make 1 perfect commit: 'fix(auth): correct token refresh race condition'"]
-  Rebuild --> Done([Clean, reviewable PR history ready])
+graph LR
+  RewriteSkill2["rewrite-commits / SKILL.md"] -->|Message conventions per| GitCommit["git-commit skill"]
+  RewriteSkill2 -->|Conflict handover to| ZoomOut["zoom-out"]
+  NewCommitReq["New commits on current work"] -->|Not this skill| GitCommit
+  PushedMain["Rewrite of pushed main/master without confirmation"] -->|Blocked| NeedConfirm["Require explicit human confirmation"]
 ```
 
----
+## 3. Real-World Use Case
 
-## 4. Verification Check
+A branch has 4 messy unpushed commits before a PR (`wip`, `fix`, `oops`, `final fix`). The user asks to squash to Angular Style. The skill runs `git log --oneline -n 4` to confirm the range, verifies the commits are not pushed to `main`, creates a temp branch, uses `git reset --soft HEAD~4` plus structured recommits with Angular Style messages, then confirms with `git log --oneline`. If a rebase conflict appears, it runs `git rebase --abort`, stops, and hands over for a human decision.
 
-To ensure that the `rewrite-commits` 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.
+- [ ] Range confirmed with `git log --oneline -n <num>` before rewriting
+- [ ] Rewrite done on a temp branch first, not directly on `main` / release branches
+- [ ] No bare interactive `git rebase -i` used; used `git reset --soft HEAD~<N>` or script editors
+- [ ] No hardcoded `sed -i` scripting used
+- [ ] All new messages follow Angular Style per the `git-commit` skill
+- [ ] Final history confirmed with `git log --oneline`
+- [ ] If commits were pushed to remote `main` / `master`, warned and obtained secondary human confirmation
+- [ ] On merge conflict, ran `git rebase --abort`, stopped, and handed over instead of resolving beyond abort
+- [ ] Not used for creating new commits on current work (belongs to `git-commit`)
+- [ ] Deep detail checked in `rewrite-commits/references/workflow.md` where needed