harness-everything 0.2.2 → 0.3.6

package/improve-codebase-architecture/guides/HTML-REPORT.md

@@ -1,123 +1,123 @@
-# HTML Report Format
-
-The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
-
-## Scaffold
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Architecture review — {{repo name}}</title>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
-    </script>
-    <style>
-      /* small custom layer for things Tailwind doesn't cover cleanly:
-         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
-      .seam { stroke-dasharray: 4 4; }
-      .leak { stroke: #dc2626; }
-      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
-    </style>
-  </head>
-  <body class="bg-stone-50 text-slate-900 font-sans">
-    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
-      <header>...</header>
-      <section id="candidates" class="space-y-10">...</section>
-      <section id="top-recommendation">...</section>
-    </main>
-  </body>
-</html>
-```
-
-## Header
-
-Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
-
-## Candidate card
-
-The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms ([LANGUAGE.md](LANGUAGE.md)) without ceremony.
-
-Each candidate is one `<article>`:
-
-- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
-- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
-- **Files** — monospaced list, `font-mono text-sm`.
-- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
-- **Problem** — one sentence. What hurts.
-- **Solution** — one sentence. What changes.
-- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
-- **ADR callout** (if applicable) — one line in an amber-tinted box.
-
-No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
-
-## Diagram patterns
-
-Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
-
-### Mermaid graph (the workhorse for dependencies / call flow)
-
-Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
-
-```html
-<div class="rounded-lg border border-slate-200 bg-white p-4">
-  <pre class="mermaid">
-    flowchart LR
-      A[OrderHandler] --> B[OrderValidator]
-      B --> C[OrderRepo]
-      C -.leak.-> D[PricingClient]
-      classDef leak stroke:#dc2626,stroke-width:2px;
-      class C,D leak
-  </pre>
-</div>
-```
-
-### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
-
-Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
-
-### Cross-section (good for layered shallowness)
-
-Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
-
-### Mass diagram (good for "interface as wide as implementation")
-
-Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
-
-### Call-graph collapse
-
-Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
-
-## Style guidance
-
-- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
-- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
-- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
-- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
-- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
-
-## Top recommendation section
-
-One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
-
-## Tone
-
-Plain English, concise — but the architectural nouns and verbs come straight from [LANGUAGE.md](LANGUAGE.md). Concision is not an excuse to drift.
-
-**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
-
-**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
-
-**Phrasings that fit the style:**
-
-- "Order intake module is shallow — interface nearly matches the implementation."
-- "Pricing leaks across the seam."
-- "Deepen: one interface, one place to test."
-- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
-
-**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
-
-No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one.
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms ([LANGUAGE.md](LANGUAGE.md)) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from [LANGUAGE.md](LANGUAGE.md). Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one.

package/improve-codebase-architecture/guides/INTERFACE-DESIGN.md

@@ -1,44 +1,44 @@
-# Interface Design
-
-When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
-
-Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
-
-## Process
-
-### 1. Frame the problem space
-
-Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
-
-- The constraints any new interface would need to satisfy
-- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
-- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
-
-Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
-
-### 2. Spawn sub-agents
-
-Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
-
-Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
-
-- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
-- Agent 2: "Maximise flexibility — support many use cases and extension."
-- Agent 3: "Optimise for the most common caller — make the default case trivial."
-- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
-
-Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
-
-Each sub-agent outputs:
-
-1. Interface (types, methods, params — plus invariants, ordering, error modes)
-2. Usage example showing how callers use it
-3. What the implementation hides behind the seam
-4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
-5. Trade-offs — where leverage is high, where it's thin
-
-### 3. Present and compare
-
-Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
-
-After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.
+# Interface Design
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/improve-codebase-architecture/guides/LANGUAGE.md

@@ -1,53 +1,53 @@
-# Language
-
-Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
-
-## Terms
-
-**Module**
-Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
-_Avoid_: unit, component, service.
-
-**Interface**
-Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
-_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
-
-**Implementation**
-What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
-
-**Depth**
-Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
-
-**Seam** _(from Michael Feathers)_
-A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
-_Avoid_: boundary (overloaded with DDD's bounded context).
-
-**Adapter**
-A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
-
-**Leverage**
-What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
-
-**Locality**
-What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
-
-## Principles
-
-- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
-- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
-- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
-- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
-
-## Relationships
-
-- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
-- **Depth** is a property of a **Module**, measured against its **Interface**.
-- A **Seam** is where a **Module**'s **Interface** lives.
-- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
-- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
-
-## Rejected framings
-
-- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
-- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
-- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+# Language
+
+Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+## Terms
+
+**Module**
+Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
+_Avoid_: unit, component, service.
+
+**Interface**
+Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
+
+**Implementation**
+What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth**
+Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(from Michael Feathers)_
+A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
+_Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter**
+A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage**
+What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
+
+**Locality**
+What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

package/improve-codebase-architecture/guides/refactoring-workflow.md

@@ -0,0 +1,59 @@
+# Improve Codebase Architecture — Full Workflow
+
+## Process & Refactoring Flow
+
+Follow the decision matrix below when refactoring codebase architecture or splitting objects:
+
+```mermaid
+flowchart TD
+    Start[Trigger: Architecture Refactoring / SRP Object Splitting] --> Scan[1. Scan CONTEXT.md, ADRs & Module Interfaces]
+    Scan --> Analyze{2. Identify Architectural Anti-Patterns}
+
+    Analyze -- Oversized Object / Monolith --> SRPPlan[Plan SRP Extraction: Split Class / Extract Function]
+    Analyze -- Shallow Module / Tight Coupling --> DeepenPlan[Plan Interface Deepening & Seam Extraction]
+
+    SRPPlan --> Report[3. Present Refactoring & Extraction Proposal]
+    DeepenPlan --> Report
+
+    Report --> Approved{User Approves Proposal?}
+
+    Approved -- No --> Adjust[Adjust Proposal & Scope] --> Report
+    Approved -- Yes --> CheckTest{4. Existing Test Safety Net Present?}
+
+    CheckTest -- No Tests --> WriteCharTest[Write Characterization Tests First] --> Execute
+    CheckTest -- Tests Pass --> Execute[5. Execute Refactoring via TDD]
+
+    Execute --> ErrorsCheck{6. Cascading Errors > 3?}
+
+    ErrorsCheck -- Yes --> Rollback[Rollback Changes & Trigger zoom-out]
+    ErrorsCheck -- No --> Complete[Refactoring Complete & Record Lessons in self-evolve]
+```
+
+## 1. Architectural Exploration & Discovery `[Discover]`
+- **Blind Refactoring Prohibited**: Before proposing any modification suggestions, you MUST first scan `CONTEXT.md`, `docs/adr/`, and core interface definitions (Interfaces/Types).
+- **Identify Refactoring Targets**:
+  - **Single Responsibility Principle (SRP) Violations**: Oversized objects, classes, or functions (>300 lines or >10 cyclomatic complexity) handling multiple uncoupled concerns.
+  - **Shallow Modules**: Complex, wide interfaces with minimal internal implementation.
+  - **Improperly Coupled Seams**: Modules directly referencing implementation details instead of clean abstraction interfaces.
+
+## 2. Analysis & Proposal `[Think]`
+Use consistent domain terminology (Module, Interface, Implementation, Depth, Seam, SRP, Extraction) to communicate with the human.
+- Submit a "Deepening & SRP Refactoring" proposal to the user detailing:
+  1. **Object Splitting Strategy**: Which responsibilities will be extracted into focused helper objects or separate modules.
+  2. **Interface Abstraction**: Which boundaries (Seams) will be extracted into clean interfaces or adapters.
+
+## 3. Implementation Refactoring `[Try]`
+- After gaining human approval, launch `tdd` mode.
+- **Iron Rule of Refactoring**: MUST be done under the safety net of test coverage. If there are no tests, the first step MUST be to "write Characterization Tests for the legacy code" before modifying the architecture.
+- **Extract Safely**: Extract objects/functions incrementally, verifying test suite execution after each atomic change.
+
+## 4. Circuit Breaker & Evolution `[Summarize]` & `[Self-Evolve]`
+- If refactoring triggers more than 3 cascading compilation errors that cannot be fixed immediately, trigger the `zoom-out` circuit breaker and Rollback.
+- Write the discovered coupling traps into `self-evolve` memory, ensuring future newly generated code does not repeat the same mistakes.
+
+## Reference Guides
+For precise architectural paradigms and deep module analysis, refer to:
+- `improve-codebase-architecture/guides/DEEPENING.md` — Deepening opportunities & modular depth rules
+- `improve-codebase-architecture/guides/INTERFACE-DESIGN.md` — Principles of interface design and seams
+- `improve-codebase-architecture/guides/LANGUAGE.md` — Language-specific refactoring and pattern guidelines
+- `improve-codebase-architecture/guides/HTML-REPORT.md` — Creating visual reports with Mermaid diagrams

package/install-cognitive-os/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: install-cognitive-os
-description: Defines the fundamental physical laws of behavior (Discover > Think > Try > Summarize > Record) for all Agents.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Defines the fundamental physical laws of behavior — Discover, Think, Try, Summarize, Record — for all Agents. Use this loop before acting on any task to ground progress in verified tool output.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.5
 ---
 
 # Agent Cognitive OS (Underlying Cognitive System)
@@ -11,85 +13,26 @@ version: 0.2.0
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | Always — the foundational cognitive loop every other skill in this repository builds on; loaded before any action on any task. |
-| **Expected Output** | Every action passes through Discover → Think → Try → Summarize → Record, where Summarize is a script-gated reality check, not a self-assessment. |
-| **State Mutations** | None of its own — it is the meta-loop other skills' state changes (e.g. `todo-cli.js complete`) run inside. |
-| **Enforcement Gate** | Progress **MUST NOT** be recorded (`[Record]`) except after a verification script exits 0. A failing script (`verify-gate.js` or equivalent) forces a step back to `[Think]`; 3 consecutive failures forces `zoom-out` instead of a 4th blind retry. |
+| **Trigger / Input** | Always — the foundational loop; loaded before acting. |
+| **Expected Output** | Actions follow Discover → Think → Try → Summarize → Record; Summarize relies on objective verification. |
+| **State Mutations** | None directly — provides the meta-loop within which other skills manage state. |
+| **Enforcement Gate** | `[Record]` is grounded in verified tool output. A failing step returns to `[Think]`; repeated failures lead to `zoom-out`. |
+## USE FOR:
+- Structuring any multi-step task with the Discover > Think > Try > Summarize > Record loop
+- Grounding progress in verified tool output before recording state
 
-This skill defines the most fundamental physical laws of behavior that all Agents in the Harness Skills system must obey. 
+## DO NOT USE FOR:
+- Skill authoring style (use `skill-style`) or Git history conventions
+- Tasks already governed by a more specific domain skill's own gates
 
-## 🚫 The Anti-Linear Paradigm (拒絕直線思維)
-Software engineering is **NOT a linear 1 -> 2 -> 3 -> Done process**. It is a cyclical process of hypothesis, execution, failure, and correction.
-If you attempt to write code sequentially and assume it works without verification, you are hallucinating.
-Your progression is **STRICTLY GATED** by terminal scripts (like `verify-gate.js` and `todo-cli.js`). If a script fails, you MUST step back, re-evaluate, and fix the issue. You cannot progress until the environment allows you to.
+## Core Loop: The State Machine
 
-## Core Loop: The State Machine (Discover > Think > Try > Summarize > Record)
+1. `[Discover]` Verify workspace state first: confirm OS, shell, tooling (`environment-detection`); trace code references instead of assuming.
+2. `[Think]` Establish intent before modifying code; evaluate failure modes early.
+3. `[Try]` Apply minimal, focused changes; run commands to validate behavior.
+4. `[Summarize]` Base conclusions on actual tool outputs (`npm test`, linters, `harness-everything/scripts/verify-gate.js`, `npx github:dyphn1/Harness-everything verify`). On failure, use diagnostics to refine `[Think]`. After 3 consecutive failures, step back to `zoom-out`.
+5. `[Record]` Record milestones via the native host tracker or Markdown checklist once verification passes.
 
-```mermaid
-flowchart TD
-    State_Awake[Discover: Where am I?] --> State_Think[Think: Form Hypothesis]
-    State_Think --> State_Try[Try: Execute Code / Run Script]
-    State_Try --> Gate{Summarize: Verify via Gate}
-    
-    Gate -->|Exit 1: Reality Mismatch| State_Think
-    Gate -->|Exit 1: Repeated Failures| ZoomOut[Record: Zoom-Out / Reflect]
-    ZoomOut --> State_Think
-    Gate -->|Exit 0: Reality Match| State_Record[Record: Commit State]
-    State_Record --> State_Think
-```
-
-### 0. `[Discover]`: State Awakening & Deep Environment Discovery
-- **Action**: Before any thinking or execution, you **MUST confirm where you are first**.
-- **Environment Detection**: Detect the OS, and specifically verify the current shell/terminal environment.
-- **Deep Information Exploration**: Do not stop at reading a single file. Trace dependencies, check call sites, and cross-reference with architectural docs.
-
-### 1. `[Think]`: Form Hypothesis
-- Before executing any command or modifying code, confirm your high-level intent.
-- Predict possible failure paths. If a direction is doomed to fail, eliminate it early.
-
-### 2. `[Try]`: Execution and Action
-- Write the minimal amount of code to test your hypothesis.
-- Run terminal commands to test the code.
-
-### 3. `[Summarize]`: The Script-Gated Reality Check
-- **CRITICAL**: You CANNOT summarize based on your own assumptions. You MUST run a verification script (e.g., tests, linter, `verify-gate.js`).
-- If the script fails (Exit Code 1), you have been slapped by reality. You MUST step back to `[Think]`, diagnose the failure using the terminal output, and try again.
-- **Deep Reflection**: If a trial fails 3 times, do NOT blindly retry. You MUST trigger a `zoom-out` reflection.
-
-### 4. `[Record]`: Commit State
-- ONLY when the verification script passes (Exit Code 0), you may use the task tracker (e.g., `todo-cli.js complete`) to record your progress and move to the next phase.
-
-## 🧠 Global Output Normalization: Always-On ADHD-Friendly Output Shaping
-Regardless of which tier is active, where you start, or which skill is currently executing, your response MUST strictly comply with the following communication standardization and formatting laws to eliminate cognitive overhead and LLM conversational bloat.
-
-### 1. Lead with the Action or Answer (開門見山)
-- **Direct Opener**: The first line of your response MUST contain the direct answer, the executed command, the code snippet, or the next concrete action.
-- **NO Preamble**: Absolutely forbidden openers include: "Sure!", "Great question!", "Let me help you...", "Let's look at this...", "Here is...", "I'll...", or any generic welcoming text. Start immediately with the substance.
-
-### 2. Complete the Task Autonomously (Don't Delegate Back / Agent 獨立自主)
-- **Do the Work**: If the task can be safely researched, written, edited, compiled, tested, or verified by you (using your available tools), you MUST complete it yourself.
-- **NO Command Lists for the User**: Do not present a list of commands for the user to run unless you are genuinely blocked by missing permissions, credentials, physical hardware interaction, or critical choices.
-
-### 3. Numbered & Bounded Multi-Step Work (步驟有邊界)
-- **Single-Action Steps**: For multi-step procedures, use numbered lists where each item is a single, bounded, actionable task. Avoid "and then" or compound steps.
-- **Cap at 5 Items**: Never exceed 5 items in a single list. If there are more, split them into "Do Now" vs "Later", or "Must-Haves" vs "Nice-to-Haves".
-
-### 4. Continuous Progress Tracking (Turn-by-Turn State / 進度可見)
-- **Restate State**: For multi-stage tasks, explicitly restate the current state at the start or end of each turn in a single concise line (e.g., "Step 3 of 5 completed: [Action]. Next: [Action].").
-- **Concrete Next Step**: Every response that leaves tasks open MUST end with exactly ONE concrete action the user can do in under two minutes (or that you will perform next).
-
-### 5. Matter-of-Fact Error Diagnostics (除錯具體且客觀)
-- **Neutral Tone**: When errors, test failures, or bugs occur, state the failure line, the observed output, the diagnosed cause, and the fix in a completely matter-of-fact tone.
-- **NO Fluff**: Never use emotive phrases like "Uh oh," "Oh no," "Seems to be a problem," or undocumented speculation.
-- **Direct Cause Only**: If the user provides an error/cause, address that specific cause immediately. Do not extend into unverified hypotheses or generic diagnostics checklist unless requested.
-
-### 6. Zero Conversational Bloat (移除無資訊文字)
-- **NO Recaps**: Do not write paragraphs summarizing what you just did (e.g., "I have successfully modified X and Y to ensure..."). The code and git diff are the evidence.
-- **NO Closing Pleasantries**: Completely remove all polite sign-offs, such as "Hope this helps!", "Let me know if you need anything else," or "Happy coding!" End exactly when the final step or answer is displayed.
-
-### 7. Language and Terminology Consistency (自然在地化繁中)
-- **User Language Alignment**: While this skill contract and files are in English, the final response MUST be in the language of the user's input (defaulting to Taiwanese Traditional Chinese (`zh-TW`) for Taiwanese requests).
-- **Natural Phrasing**: For Traditional Chinese, use natural Taiwanese engineering terminology. Avoid Chinese tech buzzwords or literal translationese.
-  - Use `程式碼` (not `代碼`), `資料/資料庫` (not `數據/數據庫`), `預設` (not `默認`), `資訊` (not `信息`), `相容` (not `兼容`), `最佳化` (not `優化`).
-  - Do not translate standard tech literals: keep code blocks, inline code, commands, paths, URLs, API/class/function names, and common industry terms (like `commit`, `PR`, `deploy`, `runtime`) exactly in their original English form.
+On advisory-only platforms hooks cannot block tool calls; gates are self-directed guidance.
 
+Deep dive: references/cognitive-loop.md