rsc-universal 0.1.1

package/skills/harness/evals/README.md

@@ -0,0 +1,54 @@
+# Eval harness — `harness` skill
+
+This evaluates the `harness` skill on two axes: **triggering** (does it fire on
+the right prompts and stay quiet on near-misses) and **capability** (does loading
+it measurably improve the agent's output). These run via an **agent harness**
+(an agent loop with skills loadable on/off), not a pure shell script — grading the
+triggering and rubric coverage requires a model in the loop.
+
+`cases.yaml` is the source of truth: `should_trigger` (7), `should_not_trigger`
+(6), `capability` (2 scenarios).
+
+## Triggering
+
+1. Load **only** the `harness` skill into the agent (plus its declared siblings'
+   *names/descriptions* so routing is realistic — do not load their bodies).
+2. For each `should_trigger` prompt: feed it cold to the agent, run **3–5 trials**,
+   record whether the agent invokes `harness`. Pass = it fires on every trial.
+3. For each `should_not_trigger` prompt: same protocol. Pass = `harness` does
+   **not** fire; bonus-check that it routes toward the `route_to` sibling (or
+   correctly declines when `route_to: none`).
+4. Score = (correct trigger decisions) / (total prompts × trials).
+
+**Pass bar: >= 90% trigger accuracy** across all prompts and trials, with **no
+single `should_not_trigger` prompt firing harness in a majority of its trials**
+(a consistent false-positive is a hard fail even if the average clears 90%).
+
+## Capability
+
+For each `capability` scenario, run it twice with an identical agent:
+
+- **WITHOUT** the skill (baseline) — skill not loaded.
+- **WITH** the skill loaded.
+
+Grade each transcript against that scenario's `must_include` checklist: one point
+per checkable point that appears, correct and unprompted, in the output. A second
+agent (or a human) grades; keep the grading rubric = the literal `must_include`
+list so it stays reproducible.
+
+**Pass bar:**
+- WITH the skill covers **>= 80%** of the `must_include` points.
+- WITH must **beat** WITHOUT by a clear margin (>= 30 percentage points). If the
+  baseline already covers most points, the skill isn't adding value — investigate.
+
+## Honesty notes
+
+- These are **model-graded** evals; expect run-to-run variance. Always run
+  multiple trials and report the spread, not a single number.
+- Keep prompts **cold** — no system hint that the harness skill exists, or the
+  trigger test is meaningless.
+- Do **not** let the capability runs actually write to disk; the skill is
+  destructive-by-consent. Run in a throwaway/sandbox workspace, or grade on the
+  *proposed plan* (AUDIT output) rather than executed APPLY.
+- When a case starts failing after a SKILL.md edit, fix the skill or the case —
+  don't tune the grader to pass.

package/skills/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 01-TOOLS and 02-DOCS and tell me what's drifted."
+    why: "Names the harness control plane and its two layers (01-TOOLS / 02-DOCS) directly; this is the core ongoing-control job of the skill."
+
+  - prompt: "Gestiona el arnés de mi proyecto: tengo carpetas 00-TOOLS, 03-NOTES y 04-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 01-TOOLS/02-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 01-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 02-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 CLAUDE.md and AGENTS.md for this workspace with a Knowledge map that the other skills can read."
+    why: "Generating root CLAUDE.md/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 02-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 (01-TOOLS + 02-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 01-TOOLS. Just copy the template and wire it up."
+    route_to: "none"
+    why: "SKILL.md 'Do NOT use' is explicit: adding a single tool is a manual `cp -r 01-TOOLS/_TEMPLATE 01-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 00-TOOLS/ and 03-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 01-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 02-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 00-TOOLS') before deleting any legacy folder."
+      - "Writes only .env.example (never a real .env, never fills credentials), merges existing CLAUDE.md/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 02-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 CLAUDE.md ## Knowledge map so other skills can read it."

package/skills/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/risco-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/risco-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/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/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>01-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>00-TOOLS/ · 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>02-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>CLAUDE.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>01-TOOLS/**/.env</code> · <code>01-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 00-TOOLS/</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/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/harness/references/claude-md-template.md

@@ -0,0 +1,98 @@
+# 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 living record of this project's conventions lives under `02-DOCS/wiki/` and is maintained by
+the stack skills, plus the `harness/` topic maintained by the harness itself (user profile +
+decisions log). Each skill links its article here as it is created — read the relevant article
+before working in its area (the `harness/user-profile.md` first, to match the user's technical +
+accompaniment level), and update it when conventions change.
+
+| Area | Article |
+|------|---------|
+| User profile (technical + accompaniment level) | `02-DOCS/wiki/harness/user-profile.md` |
+| Decisions log (append-only, "siempre 3 opciones") | `02-DOCS/wiki/harness/decisions.md` |
+| SDD constitution (project non-negotiables) | `02-DOCS/wiki/sdd/constitution.md` |
+| SDD specs (what & why, per feature) | `02-DOCS/wiki/sdd/specs/` |
+| SDD plans (technical approach, per feature) | `02-DOCS/wiki/sdd/plans/` |
+| SDD decisions (implement-phase log) | `02-DOCS/wiki/sdd/decisions.md` |
+| Brand & voice | `02-DOCS/wiki/brand/` |
+| Design system | `02-DOCS/wiki/stack/design.md` |
+| FastAPI / API | `02-DOCS/wiki/stack/fastapi.md` |
+| Next.js app | `02-DOCS/wiki/stack/nextjs.md` |
+| Go services | `02-DOCS/wiki/stack/go.md` |
+| PostgreSQL | `02-DOCS/wiki/stack/postgresdb.md` |
+| Flutter app | `02-DOCS/wiki/stack/flutter.md` |
+| Agents | `02-DOCS/wiki/stack/agents.md` |
+| Security | `02-DOCS/wiki/stack/security.md` |
+| Deployment | `02-DOCS/wiki/stack/deployment.md` |
+| Presentations | `02-DOCS/wiki/stack/presentations.md` |
+| Course storytelling | `02-DOCS/wiki/stack/course-storytelling.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).