harness-everything 0.2.0

package/hooks/scripts/subagent-scope-guard.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Subagent Scope Guard (PreToolUse + PostToolUse: Task)
+ * Grounded in a real incident: a subagent briefed as "read-only, verify and
+ * report a verdict" still had full tool access by default and made
+ * substantial unrequested edits (a GitBook restructure, ~115 deleted lines)
+ * in a large parallel fan-out. It was only caught because someone happened
+ * to run `git status` on the whole repo afterward.
+ *
+ * This hook makes that check automatic instead of relying on remembering to
+ * do it: PreToolUse snapshots `git status --porcelain` the first time a Task
+ * spawn starts (shared baseline across any parallel/nested Task calls in the
+ * same burst), PostToolUse diffs the current status against that baseline
+ * and surfaces every changed file - not just the ones the task was expected
+ * to touch, since "expected" can't be reliably inferred from a natural-
+ * language task brief. It cannot block (the subagent already ran), only
+ * makes the diff impossible to miss.
+ * Fails open on any error - this is visibility, not a hard gate.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function gitStatus(root) {
+  try {
+    return execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (err) {
+    return null;
+  }
+}
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    if (payload.tool_name !== 'Task') process.exit(0);
+
+    const root = getWorkspaceRoot();
+    const stateFile = path.join(getSessionDir(root, payload.session_id), 'subagent-scope-state.json');
+
+    if (payload.hook_event_name === 'PreToolUse') {
+      // Only set the baseline if one isn't already pending - parallel/nested
+      // Task calls in the same burst share it, so the eventual diff covers
+      // everything the whole burst touched, not just the last one.
+      if (!fs.existsSync(stateFile)) {
+        const status = gitStatus(root);
+        if (status !== null) {
+          fs.writeFileSync(stateFile, JSON.stringify({ baseline: status }, null, 2), 'utf8');
+        }
+      }
+      process.exit(0);
+    }
+
+    if (payload.hook_event_name === 'PostToolUse') {
+      if (!fs.existsSync(stateFile)) process.exit(0);
+
+      const { baseline } = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      const current = gitStatus(root);
+      if (current === null) process.exit(0);
+
+      const baselineLines = new Set(baseline.split('\n').filter(Boolean));
+      const currentLines = current.split('\n').filter(Boolean);
+      const newlyChanged = currentLines.filter(line => !baselineLines.has(line));
+
+      if (newlyChanged.length > 0) {
+        console.error(`[Subagent Scope Guard] ${newlyChanged.length} file(s) changed since this Task burst started:`);
+        newlyChanged.forEach(line => console.error(`  ${line}`));
+        console.error(`Confirm every one of these was actually in scope before trusting or committing this output.`);
+        console.error(`Do not "git add -A" - stage files explicitly by path so anything unexpected here stays visible.`);
+      }
+
+      // Roll the baseline forward so the next Task burst only reports what's
+      // new since this report, not the same files over and over.
+      fs.writeFileSync(stateFile, JSON.stringify({ baseline: current }, null, 2), 'utf8');
+
+      if (newlyChanged.length > 0) {
+        process.exit(2);
+      }
+      process.exit(0);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});

package/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: improve-codebase-architecture
+description: Discovers and transforms shallow modules into deep ones to improve testability and AI navigability.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Improve Codebase Architecture (Deep Architectural Optimization)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Project shows tech debt, overly coupled modules, or the user requests to "refactor / improve architecture quality". |
+| **Expected Output** | A "Deepening Opportunities" report naming shallow modules and improperly coupled seams, followed (after human approval) by `tdd`-guarded refactoring. |
+| **State Mutations** | Refactors module boundaries/interfaces; may add Characterization Tests before touching legacy code that has no existing coverage. |
+| **Enforcement Gate** | Blind refactoring is **PROHIBITED** — must scan `CONTEXT.md`/ADRs/interfaces first. Refactoring code with no test safety net **MUST** start with Characterization Tests. More than 3 cascading compile errors **MUST** trigger `zoom-out` and rollback, not continued patching. |
+
+Triggered when a project is full of "Tech Debt", modules are overly coupled, or the user requests to "refactor / improve architecture quality". This skill aims to transform "Shallow" modules into "Deep" modules to enhance testability and AI navigability.
+
+## 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 "Shallow Modules" (interfaces that are complex but have very little internal implementation).
+- Identify improperly coupled boundaries (Seams).
+
+## 2. Analysis & Proposal `[Think]`
+Use consistent domain terminology (Module, Interface, Implementation, Depth, Seam, Adapter) to communicate with the human.
+- Submit a "Deepening Opportunities" report to the user.
+- Explicitly point out which modules should be encapsulated and which boundaries (Seams) should be extracted into 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.
+
+## 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.
+
+## Deep 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/improve-codebase-architecture/guides/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

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

@@ -0,0 +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.

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

@@ -0,0 +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.

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

@@ -0,0 +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**.

package/install-cognitive-os/SKILL.md

@@ -0,0 +1,95 @@
+---
+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
+---
+
+# Agent Cognitive OS (Underlying Cognitive System)
+
+## 📋 Skill Contract
+
+| 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. |
+
+This skill defines the most fundamental physical laws of behavior that all Agents in the Harness Skills system must obey. 
+
+## 🚫 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 (Discover > Think > Try > Summarize > Record)
+
+```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.
+

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "harness-everything",
+  "version": "0.2.0",
+  "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
+  "main": "harness-everything/scripts/bootstrap.js",
+  "bin": {
+    "harness": "./bin/cli.js"
+  },
+  "scripts": {
+    "test": "node self-evolve/scripts/self-regression.js",
+    "self-regression": "node self-evolve/scripts/self-regression.js",
+    "test:mechanism": "node eval-framework/mechanism-test.js",
+    "harness:reset": "node hooks/scripts/reset-circuit-breaker.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Miya Daniel | Harness Core Team",
+  "license": "Apache-2.0",
+  "dependencies": {},
+  "devDependencies": {}
+}

package/repo-docs/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: repo-docs
+description: Automatically generates precise, reader-oriented README.md and AGENTS.md based on actual project scans.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Repo Docs (Automated Project Documentation Generation)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Project lacks documentation, or the user requests a `README.md` / `AGENTS.md` / architectural guideline be generated. |
+| **Expected Output** | A reader-journey-oriented `README.md` and/or agent-oriented `AGENTS.md`, built from the appropriate template in `repo-docs/templates/`. |
+| **State Mutations** | Creates/overwrites `README.md`, `AGENTS.md`, or other doc files at the target path. |
+| **Enforcement Gate** | **MUST NOT** be written from training-data assumptions — every claim (language, framework, test/build commands) **MUST** come from actually scanning the project. Uncertain parts **MUST** be marked `// TODO: Pending confirmation` and raised to the human, not guessed. |
+
+Triggered when a project lacks documentation, the user requests to create a `README.md`, or needs to define architectural guidelines in `AGENTS.md`.
+
+## 1. Reconnaissance & Environment Discovery `[Discover]`
+- **Fabrication Prohibited**: You absolutely MUST NOT rely on the model's historical training data to write documentation.
+- Call scripts or use `grep_search`, `read_file` to scan project directories, dependency files like `package.json`, `Cargo.toml`, etc.
+- Confirm the project's language, framework, test commands, and deployment methods.
+
+## 2. Organization & Writing `[Think] & [Try]`
+- **Reader-Oriented**: If generating a `README.md`, the content MUST focus on the "User Journey": what this product does, how to install it, how to use core features.
+- If generating `AGENTS.md` or developer guidelines: The content MUST focus on "architectural conventions, build commands, test commands" for future AI Agents (or human developers) to read.
+- **Combine with Cognitive Loop**: When writing, obey the `install-cognitive-os` rules, predict the chapter structure of the document first, generate it in one go, and leave room for future expansion.
+
+## 3. Verification & Alignment `[Summarize]`
+- After generating the document, you MUST ensure the installation or test commands within the document are **actually executable**.
+- If there are uncertain parts, leave `// TODO: Pending confirmation` markers in the document and ask the human questions (`grill-me` mode).
+
+## Deep Reference Templates
+To ensure professional quality, you MUST use the appropriate template from `repo-docs/templates/`:
+- `repo-docs/templates/readme-template.md` — Standard project documentation template
+- `repo-docs/templates/product-readme-template.md` — Product archetype user-journey template
+- `repo-docs/templates/multi-skills-readme-template.md` — Large project with multiple skills/modules
+- `repo-docs/templates/knowledge-readme-template.md` — Information-heavy/knowledge-base template
+- `repo-docs/templates/agents-template.md` — Standard agent onboarding instructions template
+- `repo-docs/templates/product-agents-template.md` — Agent instructions for product repositories
+- `repo-docs/templates/skills-agents-template.md` — Agent instructions for skills repositories
+- `repo-docs/templates/knowledge-agents-template.md` — Agent instructions for knowledge/research projects
+- `repo-docs/templates/manual-recon.md` — Methodology for manual repo scanning and classification