@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/harness/evals/cases.yaml

@@ -0,0 +1,72 @@
+skill: harness
+
+# >=5 realistic, VARIED prompts that MUST invoke the harness skill.
+# Includes non-obvious phrasings and cases where the user never names the tool.
+should_trigger:
+  - prompt: "Control the harness of this workspace — audit docs/tools and docs/ and tell me what's drifted."
+    why: "Names the harness control plane and its two layers (docs/tools / docs/) directly; this is the core ongoing-control job of the skill."
+
+  - prompt: "Gestiona el arnés de mi proyecto: tengo carpetas docs/legacy, docs/notes y docs/legacy sueltas y quiero la estructura canónica."
+    why: "Spanish trigger 'gestiona el arnés' plus legacy XX-* numbered folders to migrate into the canonical docs/tools/docs/ layout — squarely the migration/control behavior the skill owns."
+
+  - prompt: "My repo uses Stripe and Mailjet but there's no operational tooling for them. Set up connection-ready folders with a test_connection for each."
+    why: "Detecting external provider integrations in code and scaffolding docs/tools/<PROVIDER>/ tools (with test_connection, .env.example) is exactly the provider-detection scaffolding the harness performs; does not name the skill."
+
+  - prompt: "I've been dumping PDFs, CSVs and screenshots into a folder for weeks. Process the inbox and turn it into a proper knowledge base I can query."
+    why: "This is the docs/ Inbox Sweep / chaos->knowledge engine embedded in the harness ('procesa el inbox'); the user describes the behavior without naming the skill."
+
+  - prompt: "Generate a root AGENTS.md and AGENTS.md for this workspace with a Knowledge map that the other skills can read."
+    why: "Generating the root AGENTS.md and the Knowledge map index is an explicit harness responsibility (Phase 4 APPLY step 1)."
+
+  - prompt: "Sal a pasear por mi carpeta de documentos, clasifica todo lo que haya y enlázalo en la wiki."
+    why: "'Sal a pasear' / 'the agent goes for a walk' is the skill's own phrase for the Inbox Sweep that extracts, classifies by content and cross-links into the wiki — a non-obvious phrasing mapped to the docs/ engine."
+
+  - prompt: "This project grew organically and is a mess. Can you give it a real control plane so an agent can operate it reliably?"
+    why: "Describes a brownfield workspace needing the canonical control-plane apparatus (docs/tools + docs/ + Knowledge map) without naming any layer — the brownfield-first 'When to use' case."
+
+# >=4 NEAR-MISS prompts that must NOT invoke harness; each routes to the genuinely correct sibling.
+should_not_trigger:
+  - prompt: "I want to add a single Sentry tool folder to docs/tools. Just copy the template and wire it up."
+    route_to: "none"
+    why: "SKILL.md 'Out of scope' is explicit: adding a single tool is a manual `cp -r docs/tools/_TEMPLATE docs/tools/<X>` — the full SCAN/AUDIT/APPLY harness is overkill, no skill needed."
+
+  - prompt: "Refactor the runtime database layer in my FastAPI service to use async SQLAlchemy sessions."
+    route_to: "fastapi"
+    why: "Refactoring runtime application code is explicitly out of harness scope ('this skill is operational tooling only, never runtime'); FastAPI service runtime work routes to the fastapi skill."
+
+  - prompt: "Bootstrap a brand-new project from scratch — gauge me, draft my profile, and scaffold the first version."
+    route_to: "init"
+    why: "First-contact bootstrap / gauging the user / drafting the profile is the `init` front door; harness is the ONGOING control after bootstrap, not the kickoff."
+
+  - prompt: "Walk me through choosing and configuring where to deploy my app — Hetzner vs Vercel vs Fly, with the actual deploy commands."
+    route_to: "deployment"
+    why: "Harness defers concrete deploy mechanics to deployment; the user wants the deploy specifics and commands, which deployment owns."
+
+  - prompt: "Design a normalized Postgres schema with the right indexes and write the migration SQL."
+    route_to: "postgresdb"
+    why: "Pure database schema/SQL design is the postgresdb skill's domain; harness only detects a Postgres provider to scaffold operational tooling, it does not author schemas or migrations."
+
+  - prompt: "Build me a Next.js dashboard page that lists users from an API route."
+    route_to: "nextjs"
+    why: "Building application UI/routes is runtime app code — out of harness scope and squarely the nextjs skill's job."
+
+# 1-2 concrete tasks the skill should guide, each with a checkable rubric.
+capability:
+  - scenario: "User points the agent at an organically-grown workspace (a Next.js subproject, a .env referencing STRIPE_SECRET_KEY and MAILJET_API_KEY, plus legacy docs/legacy/ and docs/notes/ folders) and asks: 'Control the harness — get this to the canonical structure.'"
+    must_include:
+      - "Runs the five phases in order SCAN -> AUDIT -> CONSENT -> APPLY -> VERIFY, and never writes anything before rendering the AUDIT and obtaining consent."
+      - "Detects providers from evidence (Stripe, Mailjet) and proposes docs/tools/<PROVIDER>/ folders only because grep found imports/env_vars/deps — no speculative tools."
+      - "Renders the AUDIT as both a compact in-conversation summary AND a full HTML report at docs/audits/audit-YYYY-MM-DD-HHMM.html (gitignored), listing tools-to-create, legacy-folder per-file classification, ambiguous files, root-file plan, and a separate bold destructive-ops section."
+      - "Requires explicit consent ('yes, proceed' / 'go' / 'proceed'); treats silence/'ok'/'sure' as NO; and requires a SEPARATE second exact-string consent (quoting the path, e.g. 'yes, delete docs/legacy') before deleting any legacy folder."
+      - "Writes only .env.example (never a real .env, never fills credentials), merges existing AGENTS.md additively (never overwrites user content), and leaves AMBIGUOUS files in place (preserving the legacy folder)."
+      - "Treats node_modules/.venv/.next/__pycache__/.git/dist/build/.dart_tool and all subproject runtime internals as out of scope — read for detection only, never moved or modified."
+      - "VERIFY runs `bash -n` on every generated test_connection.sh as a syntax gate, checks python3 availability, and prints a final report of files written, folders deleted (with consent quote), and ambiguous files preserved."
+
+  - scenario: "User drops a pile of mixed raw files (PDF invoice, a CSV export, screenshots, a .txt of meeting notes) into docs/inbox/ and says: 'Process the inbox and build my knowledge base.'"
+    must_include:
+      - "Runs the Inbox Sweep ('the agent goes for a walk') per references/wiki-protocol.md rather than inventing an ad-hoc structure."
+      - "Multiformat ingest (per references/ingest-formats.md): converts each input to raw/ markdown while preserving the original in _originals/ (or equivalent), handling PDF/image/CSV/txt."
+      - "Classifies content by inferred topic (e.g. finanzas/, legal/, crm/) — never hardcodes software-doc topics — and compiles into wiki/<topic>/ with cross-links (See Also)."
+      - "Maintains the canonical wiki artifacts: wiki/index.md (with Score column), wiki/log.md, wiki/gaps.md, wiki/scores.json."
+      - "Triggers a Maintenance Pass after the sweep (deterministic lint, score recomputation, gap detection, See Also sweep) and notes Micro-Improve / Deep Improve cadence."
+      - "Indexes the result in the root AGENTS.md ## Knowledge map so other skills can read it."

package/skills/shared/harness/examples/audit-example.md

@@ -0,0 +1,120 @@
+# Example — AUDIT output for a synthetic brownfield project
+
+This is a real example of the AUDIT report the skill produces. Use it as
+a reference for formatting, level of detail, and how to handle edge
+cases (ambiguous files, legacy folder migration, the embedded wiki
+bootstrap).
+
+## Input project
+
+```
+/tmp/ai-hub-harness-test/
+├── backend/
+│   ├── pyproject.toml          ← deps: fastapi, stripe, mailjet-rest
+│   ├── .env.example            ← STRIPE_SECRET_KEY, MAILJET_*
+│   └── app/services/
+│       ├── billing.py          ← import stripe
+│       └── email.py            ← from mailjet_rest import Client
+├── frontend/
+│   └── package.json            ← deps: next@15, @stripe/stripe-js
+├── 00-TOOLS/
+│   ├── STRIPE/
+│   │   ├── test_connection.sh  ← legacy bash, has shebang
+│   │   └── README.md           ← legacy tool doc
+│   └── random_helper.py        ← Python without shebang, unclear purpose
+└── 03-NOTES/
+    └── architecture.md         ← prose docs
+```
+
+## AUDIT output
+
+```
+# Audit — harness — 2026-05-31
+
+Workspace: /tmp/ai-hub-harness-test
+
+## 1. Stack detected
+- Backend: FastAPI (Python) — backend/ — pyproject.toml (fastapi, stripe, mailjet-rest)
+- Frontend: Next.js 15 — frontend/ — package.json (next@15, @stripe/stripe-js)
+
+## 2. Tools to create in 01-TOOLS/
+
+| Tool   | Category    | Evidence | Action |
+|--------|-------------|----------|--------|
+| STRIPE | pagos       | backend/app/services/billing.py:1 (import stripe); pyproject.toml dep; frontend dep | MERGE — legacy 00-TOOLS/STRIPE/ exists |
+| MAILJET| email       | backend/app/services/email.py:1 (from mailjet_rest); pyproject.toml dep            | CREATE |
+
+Rest of the catalog: SKIP — no evidence.
+
+## 3. Legacy XX-* folders
+
+### 00-TOOLS/
+| File | Classification | Proposed destination |
+|------|----------------|----------------------|
+| STRIPE/test_connection.sh | TOOLING | 01-TOOLS/STRIPE/migrated/test_connection.sh (collision with catalog) |
+| STRIPE/README.md          | TOOLING | 01-TOOLS/STRIPE/migrated/README.md (collision with catalog) |
+| random_helper.py          | AMBIGUOUS | (stays in 00-TOOLS/) |
+
+Total: 3 · TOOLING: 2 · DOCS: 0 · AMBIGUOUS: 1
+Deletion of 00-TOOLS/: BLOCKED — AMBIGUOUS present.
+
+### 03-NOTES/
+| File | Classification | Proposed destination |
+|------|----------------|----------------------|
+| architecture.md | DOCS | 02-DOCS/raw/migrated/03-NOTES/architecture.md |
+
+Total: 1 · TOOLING: 0 · DOCS: 1 · AMBIGUOUS: 0
+Deletion of 03-NOTES/: candidate for second consent.
+
+## 4. Documentation → 02-DOCS/ (embedded protocol)
+Sources to ingest (following references/wiki-protocol.md):
+- 01-TOOLS/README.md (after creation)
+- 01-TOOLS/STRIPE/README.md + CREDENTIALS.md
+- 01-TOOLS/MAILJET/README.md + CREDENTIALS.md
+- 02-DOCS/raw/migrated/03-NOTES/architecture.md (after migration)
+- Root CLAUDE.md and AGENTS.md
+
+## 5. Root files
+| File       | State       | Action |
+|------------|-------------|--------|
+| CLAUDE.md  | does not exist | CREATE from template |
+| AGENTS.md  | does not exist | CREATE from template |
+
+## 6. Files I will NEVER touch
+- 01-TOOLS/**/.env (real)
+- backend/.env.example, backend/app/**, frontend/package.json — subproject internals
+- node_modules/, .venv/, .next/, __pycache__/, .dart_tool/, .git/
+
+## 7. Subprojects git state
+No Git repos in the subprojects. Nothing to stash.
+
+## 8. Destructive operations
+| Operation         | When |
+|-------------------|------|
+| Delete 00-TOOLS/  | NEVER in this run (AMBIGUOUS present) |
+| Delete 03-NOTES/  | After migration + literal second consent "yes, delete 03-NOTES" |
+
+## Proceed?
+Respond with the literal string:
+- "yes, proceed" — run the plan
+- "adjust" — modify
+```
+
+## Lessons from this example
+
+1. **Ambiguity blocks deletion.** `random_helper.py` (no shebang, no
+   catalog provider integration) → AMBIGUOUS → `00-TOOLS/` is preserved
+   after migration. Don't force the classification.
+
+2. **Collision = `migrated/`.** When a legacy file
+   (`00-TOOLS/STRIPE/test_connection.sh`) collides with the catalog
+   file, it goes to `01-TOOLS/STRIPE/migrated/` for the user to resolve
+   manually. The catalog is NEVER overwritten.
+
+3. **Subproject internals are invisible.** `backend/.env.example`,
+   `backend/app/services/*.py`, `frontend/package.json` are READ for
+   detection but NEVER moved or modified.
+
+4. **Two distinct consents.** "yes, proceed" authorizes the general
+   APPLY. "yes, delete 03-NOTES" is ANOTHER, deletion-specific consent
+   quoting the exact path.

package/skills/shared/harness/references/agents-md-template.md

@@ -0,0 +1,41 @@
+# AGENTS.md — {{PROJECT_NAME}}
+
+> Template generated by `harness` on {{TODAY}}.
+> For agents OTHER than Claude Code (Codex, Cursor, Aider, etc.), this
+> file is the first read. For Claude Code, see `CLAUDE.md` (both files
+> are aligned, but `CLAUDE.md` may have Claude-specific runtime details).
+
+## Workspace
+
+Multi-repo orchestrated at the root level. Each subproject is an
+independent Git repo. The root is NOT a repo.
+
+## Quick map
+
+| Path | Role |
+|------|------|
+{{SUBPROJECT_ROWS}}
+| `01-TOOLS/` | Operational tooling per external provider. |
+| `02-DOCS/` | LLM wiki (`raw/` + `wiki/` + `index.md` + `log.md`). |
+
+## Minimum rules
+
+1. **Before editing a subproject**: `git -C <subproject> status --short`.
+2. **Do not commit without asking**.
+3. **Do not touch `01-TOOLS/**/.env`**. These are real credentials.
+4. **Do not touch generated outputs**: `node_modules/`, `.venv/`,
+   `.next/`, `__pycache__/`, `.dart_tool/`, `build/`.
+5. **To add a new external tool**, use `01-TOOLS/_TEMPLATE/`.
+6. **For reusable documentation**, write to `02-DOCS/raw/<topic>/` and
+   compile in `02-DOCS/wiki/<topic>/`. The protocol lives in
+   `harness/references/wiki-protocol.md` (embedded in the
+   skill).
+
+## Per-subproject commands
+
+{{SUBPROJECT_COMMANDS}}
+
+## Differences from `CLAUDE.md`
+
+If there are any, they're documented here. By default both files cover
+the same rules.

package/skills/shared/harness/references/audit-report-template.html

@@ -0,0 +1,140 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Audit — harness — {{TODAY}}</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+  :root {
+    --bg: #fafbfc; --panel: #ffffff; --panel-2: #f4f6f9; --border: #e5e7eb;
+    --text: #1a1d23; --muted: #6b7280; --accent: #2563eb;
+    --create: #16a34a; --merge: #d97706; --skip: #6b7280;
+    --good: #16a34a; --warn: #d97706; --bad: #dc2626;
+    --danger-bg: #fef2f2; --danger-border: #fca5a5;
+    --consent-bg: #ecfdf5; --consent-border: #6ee7b7;
+    --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace;
+    --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, Roboto, sans-serif;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg: #0f1115; --panel: #161a22; --panel-2: #1d2230; --border: #2a3140;
+            --text: #e6e8ee; --muted: #8b94a8; --accent: #7aa2f7;
+            --create: #9ece6a; --merge: #e0af68; --skip: #8b94a8;
+            --good: #9ece6a; --warn: #e0af68; --bad: #f7768e;
+            --danger-bg: #2a1316; --danger-border: #7f1d1d;
+            --consent-bg: #0c2920; --consent-border: #166534; }
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; padding: 32px 24px 80px; background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; line-height: 1.6; max-width: 1100px; margin-left: auto; margin-right: auto; }
+  h1 { font-size: 26px; margin: 0 0 6px; font-weight: 600; }
+  h2 { font-size: 13px; text-transform: uppercase; letter-spacing: 0.08em; color: var(--muted); margin: 32px 0 12px; font-weight: 600; }
+  h3 { font-size: 16px; margin: 18px 0 8px; font-weight: 600; }
+  a { color: var(--accent); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  code { font-family: var(--mono); font-size: 12px; background: var(--panel-2); padding: 1px 5px; border-radius: 4px; }
+  .meta { color: var(--muted); font-family: var(--mono); font-size: 12px; margin-bottom: 24px; }
+  .stack { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 12px; }
+  .stack .card { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; padding: 12px 14px; }
+  .stack .name { font-weight: 600; }
+  .stack .path { font-family: var(--mono); font-size: 12px; color: var(--muted); margin-top: 4px; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; background: var(--panel); border: 1px solid var(--border); border-radius: 8px; overflow: hidden; }
+  th { text-align: left; padding: 10px 12px; background: var(--panel-2); border-bottom: 1px solid var(--border); color: var(--muted); font-weight: 600; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; }
+  td { padding: 10px 12px; border-bottom: 1px solid var(--border); vertical-align: top; }
+  tr:last-child td { border-bottom: none; }
+  td.evidence { font-family: var(--mono); font-size: 11px; color: var(--muted); }
+  .action { display: inline-block; padding: 2px 10px; border-radius: 999px; font-size: 11px; font-family: var(--mono); font-weight: 700; }
+  .action.create { background: rgba(34, 197, 94, 0.15); color: var(--create); }
+  .action.merge  { background: rgba(217, 119, 6, 0.15); color: var(--merge); }
+  .action.skip   { background: rgba(107, 114, 128, 0.15); color: var(--skip); }
+  details { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; margin-bottom: 10px; }
+  details summary { cursor: pointer; padding: 12px 14px; font-weight: 600; }
+  details[open] summary { border-bottom: 1px solid var(--border); }
+  details .body { padding: 14px; }
+  .class { padding: 1px 7px; border-radius: 4px; font-family: var(--mono); font-size: 11px; font-weight: 700; }
+  .class.tooling { background: rgba(96, 165, 250, 0.15); color: var(--accent); }
+  .class.docs { background: rgba(34, 197, 94, 0.15); color: var(--good); }
+  .class.ambiguous { background: rgba(217, 119, 6, 0.15); color: var(--warn); }
+  .danger { background: var(--danger-bg); border: 1px solid var(--danger-border); border-radius: 8px; padding: 16px 18px; }
+  .danger h2 { margin-top: 0; color: var(--bad); }
+  .never-list { font-family: var(--mono); font-size: 12px; color: var(--muted); line-height: 1.9; }
+  .consent { position: sticky; bottom: 16px; background: var(--consent-bg); border: 2px solid var(--consent-border); border-radius: 10px; padding: 18px 22px; margin-top: 36px; font-size: 15px; }
+  .consent .yes { font-family: var(--mono); background: var(--panel); padding: 3px 10px; border-radius: 4px; border: 1px solid var(--border); font-weight: 600; }
+  ul.sources { list-style: none; padding: 0; margin: 0; }
+  ul.sources li { padding: 4px 0; font-family: var(--mono); font-size: 12px; }
+</style>
+</head>
+<body>
+  <h1>Audit — harness</h1>
+  <div class="meta">{{TODAY}} · workspace <code>{{WORKSPACE_ROOT}}</code></div>
+
+  <h2>1. Stack detected</h2>
+  <div class="stack">
+    {{STACK_CARDS}}
+    <!-- Each: <div class="card"><div class="name">FastAPI (Python 3.11)</div><div class="path">myapp-backend/</div></div> -->
+  </div>
+
+  <h2>2. Tools to create in <code>docs/tools/</code></h2>
+  <table>
+    <thead>
+      <tr><th>Tool</th><th>Category</th><th>Evidence</th><th>Action</th></tr>
+    </thead>
+    <tbody>
+      {{TOOLS_ROWS}}
+      <!-- Each: <tr><td><strong>STRIPE</strong></td><td>pagos</td><td class="evidence">backend/app/services/billing.py:1 · pyproject.toml dep · frontend dep</td><td><span class="action create">CREATE</span></td></tr> -->
+    </tbody>
+  </table>
+
+  <h2>3. Legacy <code>XX-*</code> folders detected</h2>
+  {{LEGACY_FOLDERS_DETAILS}}
+  <!-- Each: <details><summary>docs/legacy/ · 42 files · TOOLING: 35 · DOCS: 5 · AMBIGUOUS: 2 (deletion blocked)</summary><div class="body"><table>...rows with <span class="class tooling">TOOLING</span> etc...</table></div></details> -->
+
+  <h2>4. Documentation → <code>docs/</code> (embedded protocol)</h2>
+  <ul class="sources">
+    {{WIKI_SOURCES_LIST}}
+    <!-- Each: <li><a href="...">path</a></li> -->
+  </ul>
+
+  <h2>5. Root files</h2>
+  <table>
+    <thead><tr><th>File</th><th>State</th><th>Action</th></tr></thead>
+    <tbody>
+      <tr><td><code>AGENTS.md</code></td><td>{{CLAUDE_MD_STATE}}</td><td>{{CLAUDE_MD_ACTION}}</td></tr>
+      <tr><td><code>AGENTS.md</code></td><td>{{AGENTS_MD_STATE}}</td><td>{{AGENTS_MD_ACTION}}</td></tr>
+    </tbody>
+  </table>
+
+  <h2>6. Files I will NEVER touch</h2>
+  <div class="never-list">
+    <code>docs/tools/**/.env</code> · <code>docs/tools/**/keys/</code> · <code>*.p8</code> · <code>*.p12</code> · <code>*.jks</code> · service account JSONs<br>
+    <code>node_modules/</code> · <code>.next/</code> · <code>.venv/</code> · <code>.pytest_cache/</code> · <code>__pycache__/</code> · <code>.dart_tool/</code> · <code>build/</code> · <code>dist/</code><br>
+    Any <code>.git/</code> · subproject internals beyond their declarative root.
+  </div>
+
+  <h2>7. Subproject git state</h2>
+  <div>{{GIT_STATUS_HTML}}</div>
+
+  <div class="danger" style="margin-top: 24px;">
+    <h2 style="color: var(--bad); letter-spacing: 0.08em;">8. Destructive operations</h2>
+    <table>
+      <thead><tr><th>Operation</th><th>When</th></tr></thead>
+      <tbody>
+        {{DESTRUCTIVE_OPS_ROWS}}
+        <!-- Each: <tr><td><code>Delete docs/legacy/</code></td><td>NEVER this run (AMBIGUOUS present)</td></tr> -->
+      </tbody>
+    </table>
+    <p style="margin: 12px 0 0; font-size: 13px; color: var(--muted);">
+      Every deletion requires a <strong>second consent quoting the exact path</strong>. The first consent ("yes, proceed") does NOT authorize deletions.
+    </p>
+  </div>
+
+  <div class="consent">
+    <strong>Proceed?</strong> Respond with the literal string:
+    <ul style="margin: 8px 0 0;">
+      <li><span class="yes">yes, proceed</span> — run the plan as-is (no legacy folder deletions yet).</li>
+      <li><span class="yes">adjust</span> — drop or add something from the plan.</li>
+    </ul>
+    <div style="margin-top: 10px; font-size: 12px; color: var(--muted);">
+      Any other response (including "ok", "sure", "sounds good", silence) is interpreted as do NOT proceed.
+    </div>
+  </div>
+</body>
+</html>

package/skills/shared/harness/references/audit-report-template.md

@@ -0,0 +1,116 @@
+# Audit — `harness` — {{TODAY}}
+
+Workspace: `{{WORKSPACE_ROOT}}`
+
+---
+
+## 1. Stack detected
+
+{{STACK_SUMMARY}}
+
+> Example:
+> - Backend: FastAPI (Python 3.11) — `myapp-backend/`
+> - Frontend: Next.js 15 — `myapp-frontend/`
+> - Mobile: Flutter — `myapp-mobile/`
+
+## 2. Tools to create in `01-TOOLS/`
+
+| Tool | Category | Evidence | Action |
+|------|----------|----------|--------|
+{{TOOLS_TABLE}}
+
+> Actions:
+> - **CREATE** — didn't exist, created from the catalog template.
+> - **MERGE** — already exists (e.g. migrated from `00-TOOLS/`); new
+>   catalog files are written under `01-TOOLS/<X>/migrated/<file>` if
+>   they collide with a user file.
+> - **SKIP** — no evidence in code; not created (no speculative tools).
+
+## 3. Legacy `XX-*` folders detected
+
+{{LEGACY_FOLDERS_SECTION}}
+
+> Per folder, a sub-section with:
+>
+> ### `00-TOOLS/`
+>
+> | File | Classification | Proposed destination |
+> |------|----------------|----------------------|
+> | `STRIPE/test_connection.sh` | TOOLING | `01-TOOLS/STRIPE/test_connection.sh` |
+> | `STRIPE/README.md` | TOOLING (tool doc) | `01-TOOLS/STRIPE/README.md` |
+> | `RANDOM_NOTES.md` | DOCS | `02-DOCS/raw/migrated/00-TOOLS/RANDOM_NOTES.md` |
+> | `unclassified_script.py` | AMBIGUOUS | (stays in `00-TOOLS/`) |
+>
+> Result:
+> - Total: 42 files · TOOLING: 35 · DOCS: 5 · AMBIGUOUS: 2
+> - **Deletion of `00-TOOLS/`**: requires AMBIGUOUS = 0 + second consent after migration.
+
+## 4. Documentation → `02-DOCS/` (embedded protocol)
+
+`02-DOCS/` is built following `references/wiki-protocol.md` (embedded in
+this skill, no external dependency).
+
+Sources ingested in this bootstrap:
+
+{{WIKI_SOURCES}}
+
+> Example:
+> - `myapp-backend/README.md`
+> - `myapp-frontend/README.md`
+> - `01-TOOLS/README.md` (after creation)
+> - `01-TOOLS/<TOOL>/README.md` and `CREDENTIALS.md` per detected tool
+> - Content of `02-DOCS/raw/migrated/` (after migration)
+> - Root `CLAUDE.md` and `AGENTS.md`
+
+Resulting structure: `02-DOCS/raw/<topic>/`, `02-DOCS/wiki/<topic>/`,
+`02-DOCS/wiki/index.md`, `02-DOCS/wiki/log.md`.
+
+## 5. Root files
+
+| File | State | Action |
+|------|-------|--------|
+| `CLAUDE.md` | {{CLAUDE_MD_STATE}} | {{CLAUDE_MD_ACTION}} |
+| `AGENTS.md` | {{AGENTS_MD_STATE}} | {{AGENTS_MD_ACTION}} |
+
+> Possible actions:
+> - **CREATE** — doesn't exist, created from template.
+> - **MERGE-ADDITIVE** — exists; missing sections appended with marker
+>   `<!-- added by harness YYYY-MM-DD -->`. Nothing
+>   removed.
+> - **SKIP** — the existing file already covers the template.
+
+## 6. Files I will NEVER touch
+
+- `01-TOOLS/**/.env` (real)
+- `01-TOOLS/**/keys/`, `*.p8`, `*.p12`, `*.jks`, service account JSONs
+- `node_modules/`, `.next/`, `.venv/`, `.pytest_cache/`, `.ruff_cache/`,
+  `__pycache__/`, `.dart_tool/`, `build/`, `dist/`
+- Any `.git/`, internal subproject content beyond its declarative root.
+
+## 7. Subprojects git state
+
+{{GIT_STATUS_REPORT}}
+
+> If there are uncommitted changes, commit or stash them before the skill
+> moves anything (some files might belong to user work in flight).
+
+## 8. Destructive operations
+
+| Operation | When |
+|-----------|------|
+{{DESTRUCTIVE_OPS_TABLE}}
+
+> Every deletion requires a SECOND explicit consent quoting the exact
+> path. The first consent ("yes, proceed") does NOT authorize deletions.
+
+---
+
+## Proceed?
+
+Respond with the literal string:
+
+- `yes, proceed` — run the plan as-is (no legacy folder deletions yet).
+- `adjust` — I want to drop or add something from the plan.
+
+Any other response (including "ok", "sure", "sounds good", silence) is
+interpreted as do NOT proceed, and I will ask again.

package/skills/shared/harness/references/claude-md-template.md

@@ -0,0 +1,85 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+> Template generated by `harness` on {{TODAY}}.
+> Edit it freely: the skill respects your changes and only adds sections
+> that are missing on future runs.
+
+This file is the root instruction source for agents working in this
+workspace. If you're working in a subproject that also has its own
+`CLAUDE.md`, read this file first and then the subproject's `CLAUDE.md`.
+
+## What this project is
+
+> One or two sentences describing the product and its audience.
+
+## Knowledge map
+
+The **full** index of this project's conventions lives in **`02-DOCS/wiki/index.md`** — maintained by
+the stack skills plus the `harness/` topic. Read the relevant article before working in its area, and
+update it when conventions change. Keep this section a **short pointer**: CLAUDE.md is read on every
+turn, so the full per-area table belongs in `02-DOCS/wiki/index.md`, not here. New index entries go
+there, not into this file.
+
+Read first, always:
+
+| Area | Article |
+|------|---------|
+| User profile (register: technical or analogies) | `02-DOCS/wiki/harness/user-profile.md` |
+| SDD constitution (project non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
+| **Everything else — full index** | `02-DOCS/wiki/index.md` |
+
+## Workspace map
+
+| Path | Role |
+|------|------|
+{{SUBPROJECT_ROWS}}
+| `01-TOOLS/` | Operational arsenal: one folder per external provider, with co-located credentials and a working `test_connection`. |
+| `02-DOCS/` | LLM wiki: immutable sources in `raw/`, compiled articles in `wiki/`, plus `wiki/index.md` and `wiki/log.md`. |
+
+The root is not a single Git repo; the Git repos live inside the main
+subdirectories. Do not assume that `git status` at the root works.
+
+## Working rules
+
+- Before touching a subproject, run `git -C <subproject> status --short`.
+  The user may have in-flight changes; don't revert or merge them without
+  understanding them.
+- Ignore generated outputs unless the user asks for them: `node_modules/`,
+  `.next/`, `.venv/`, `.pytest_cache/`, `.ruff_cache/`, `.mypy_cache/`,
+  `.dart_tool/`, `build/`, `__pycache__/`.
+- Keep subproject boundaries clean. Don't mix dependencies or stacks
+  across repos.
+- Never publish secrets. `01-TOOLS/**/.env`, `CREDENTIALS.md`, SSH keys,
+  service accounts, and tokens are sensitive even though they live in the
+  workspace.
+- For UI changes, read the canonical design document for the affected
+  surface before editing.
+- For documentation, update `02-DOCS/` following the embedded wiki
+  protocol: new sources go in `raw/<topic>/`, distilled knowledge in
+  `wiki/<topic>/`. The skill maintains `wiki/index.md` and `wiki/log.md`.
+
+## Main commands
+
+{{SUBPROJECT_COMMANDS}}
+
+## Operational tooling
+
+Manual operations against external services live in `01-TOOLS/`. Each
+folder has `test_connection.{sh,py}` as a smoke-test.
+
+| Tool | What it's for |
+|------|---------------|
+{{TOOLS_ROWS}}
+
+To add a new tool: `cp -r 01-TOOLS/_TEMPLATE 01-TOOLS/<NAME>` and follow
+the README in `01-TOOLS/`.
+
+## Documentation
+
+- `02-DOCS/raw/` — immutable source material (READMEs, ADRs, notes).
+- `02-DOCS/wiki/index.md` — index of compiled articles.
+- `02-DOCS/wiki/log.md` — append-only ingest/query log.
+
+When you learn something new and reusable, ingest it with
+`harness` (the wiki protocol lives embedded in the skill,
+no external skill required).

package/skills/shared/harness/references/daily-curation-automation.md

@@ -0,0 +1,68 @@
+# Daily curation automation — the compounding pass on a timer
+
+The third trigger of the work-driven path (the other two: the PreCompact/SessionEnd
+hook and explicit milestones). This is the harness's existing **Continuous
+Improvement** (Maintenance Pass / Micro-Improve / Deep Improve) promoted to a
+**first-class, portable, scheduled** automation — "the agent goes for a walk" on a
+timer, not only when asked.
+
+**Portable definition + Claude-Code reliability** (same pattern as the hooks): the
+spec below works on any assistant as a protocol; on Claude Code, wire a real daily
+cron via the `schedule` skill pointed at this prompt.
+
+## Purpose
+
+Run once per day, at a quiet hour, to keep the second brain alive:
+
+- run the **Auto-Ingest Sweep**: process `inbox/`, then scan the workspace (minus
+  `.ai-hubignore`) for un-ingested documents, ingest the clearly-documentary folders,
+  record them in `wiki/.ingested.json`, and propose the ambiguous ones
+- process pending `raw/worklog/` material into `wiki/`
+- strengthen weak / low-score pages; fill one open gap
+- repair links and the graph (resolve broken wikilinks, add `## Related` where proper nouns recur)
+- mark `stale` pages whose sources moved on
+- record what changed in `wiki/log.md`
+
+## Suggested schedule
+
+Daily, at a quiet hour when the user is unlikely to be editing the vault.
+
+## Scope (paths)
+
+The **workspace root** (for Auto-Ingest discovery, bounded by `.ai-hubignore`),
+`raw/worklog/`, `inbox/`, `raw/`, `wiki/`, `wiki/.ingested.json`, `wiki/harness/`.
+
+## Prompt
+
+```text
+Run the daily curation pass for this 02-DOCS second brain.
+
+Use the harness wiki-protocol.md as the contract. First run the Auto-Ingest Sweep:
+process inbox/, then scan the workspace (minus .ai-hubignore) for un-ingested documents,
+applying Clean-as-you-go (move loose root-level + inbox files into raw/ after a
+verified ingest; copy files nested in user-maintained folders and propose
+consolidation), record them in wiki/.ingested.json, and list ambiguous folders as
+proposals (do not grab them). Then compile pending raw/worklog/ material into wiki/
+pages (update existing before creating new), keep frontmatter + relative markdown
+links OKF-consistent, append significant decisions to wiki/harness/decisions.md,
+refresh the .base-backed navigation, recompute scores.json + the score: property,
+and prepend a dated entry (newest first) to wiki/log.md.
+
+Be conservative. If the topic map no longer fits, record a recommendation in
+wiki/gaps.md or a page's Open Questions instead of moving large parts of the
+vault without explicit approval.
+```
+
+## Expected outcome (one of)
+
+- worklog/inbox material distilled; `status` flipped to processed
+- maintenance improvements to links, scores, `.base` views, or stale flags
+- a `wiki/log.md` entry explaining what was checked and what remains open
+- no file changes when there is genuinely nothing useful to do
+
+## Safety
+
+- Do not rewrite or delete raw sources.
+- Do not perform large taxonomy reorganizations without explicit approval.
+- Do not create pages from weak connections just to look busy.
+- Prefer small, compounding improvements over big sweeps.