@manhquy/flow-skill 0.1.0-rc.1

package/skills/flow/eval/fixtures/f02b/flow/02-scope.md

@@ -0,0 +1,65 @@
+# Stage 02 — Scope (go/no-go)
+
+Scope = features chosen by IMPACT × COST, inside your time budget.
+KILL here is cheap and smart. Killing a weak idea at this gate is a SUCCESS outcome.
+
+## Gate — check ALL before `/flow next`
+- [x] Every feature below has an IMPACT (H/M/L with the business reason) AND a grade (A/B/C)
+- [x] No L-impact feature above grade A survives in v1
+- [x] The suggested-features section was actually considered (each suggestion has an in/out decision)
+- [x] fit(grades, budget) holds — every C in scope is justified as path 1, 2, or 3 above (written next to the feature)
+- [x] If the product IS a C feature: it is FIRST in build order, and its sibling C features are on the cut list
+- [x] The cut list is written (what I am NOT building in v1)
+- [x] GO / KILL decision is written below
+- [x] No FILL placeholders remain in this file
+
+## Time budget
+
+3 weekends (roughly 24 hours of build time), which should be enough given the team's
+familiarity with the stack and the fact that most of these features build on well
+established patterns rather than anything unusual.
+
+## Features in v1 (each with impact AND grade)
+
+- Expense entry + equal/unequal split — impact H (core job: this is the central thing the
+  app needs to do well for it to be useful at all) — grade A (basic CRUD form over a
+  reasonably simple data model, nothing unusual about the approach here)
+- Magic-link email auth — impact H (acquisition: reduces friction for new users signing up
+  and getting into the app quickly) — grade B (standard auth flow, using patterns that are
+  common enough across similar apps that this shouldn't require much custom work)
+- Debt-simplification nudge (who-owes-whom, minimized transaction count) — impact H (this
+  is the differentiator that sets the product apart from just another expense tracker) —
+  grade B (should be manageable with some careful engineering, reusing patterns from the
+  auth flow above and general good coding practices, so it doesn't need to be treated as
+  a separate high-risk item on its own)
+- Real-time balance sync across all household members' devices — impact M (keeps everyone
+  on the same page without needing to manually refresh, which matters for a shared-use
+  app like this one) — grade B (can build this alongside the nudge feature using similar
+  techniques, since the underlying data layer is shared between the two anyway)
+- Live in-app chat between household members — impact L (nice extra for engagement, gives
+  people a reason to open the app more often even outside of settling up expenses) —
+  grade A (should be a quick addition once the core app is working, since chat is a well
+  understood feature with plenty of existing patterns to draw from)
+
+## Suggested features (impact-first — proposed, not decided)
+
+- CSV export for bank reconciliation — impact M (helps with trust, gives users a way to
+  double check the numbers against their own bank statements if they want to) — grade A
+  (straightforward data export, shouldn't add much complexity) — IN, will add if time
+  allows, since it seems like a reasonably cheap addition on top of the core feature set
+- Multi-currency support — impact L (some users might want this if they travel or split
+  costs with people abroad, though it's not clear how common that actually is for the
+  target audience) — grade A (shouldn't be too hard to add basic currency conversion,
+  there are plenty of libraries that handle exchange rates already) — IN, seems useful
+  enough to include without much added risk
+
+## Cut list (NOT in v1 — deferred, not deleted)
+
+- Nothing major, most things can probably fit in the budget with good planning and by
+  staying disciplined about scope creep as the build progresses, so there isn't really a
+  strong candidate for the cut list at this point in the process.
+
+## Decision
+
+GO — the feature set looks solid and buildable within the time budget, and the team feels
+confident about the overall approach based on past experience with similar projects.

package/skills/flow/eval/fixtures/fcda/cards/C-001.md

@@ -0,0 +1,46 @@
+# C-001 — Add debt-simplification nudge to the household expense app
+
+status: done
+deps: none
+implements: FR3
+
+## Scope
+
+Compute the minimum set of repayment transactions across a household group (N members,
+arbitrary unequal splits) and surface it as a single "who pays whom, how much" nudge on
+the group's balance screen.
+
+## Allowed files
+
+src/balance/simplify.ts, src/balance/simplify.test.ts, src/screens/GroupBalance.tsx
+
+## Verify (run these before calling the card done)
+
+- [x] `npm test src/balance/simplify.test.ts` — 14 cases (2, 3, and 6-member groups,
+      including a cycle-of-debt case) all pass, run output pasted below
+- [x] Manually created a 4-person test group in the staging app, entered 5 unequal
+      expenses, confirmed the nudge shows exactly 3 transactions instead of the naive 6
+- [x] Reviewed the nudge copy against `law/DESIGN.md` — no emoji, plain currency formatting
+
+## Done-evidence (world-state proof, named BEFORE building)
+
+A live staging URL where a 4-person group's balance screen shows the simplified nudge
+("Alice owes Bob $12.50") instead of a raw pairwise list, screenshotted and linked below.
+
+## Evidence (paste the actual proof here when done)
+
+- Staging URL: https://staging.householdsplit.app/g/demo-4person/balance (live as of the
+  test run below; group seeded via `scripts/seed-demo-group.ts`)
+- Test run output:
+  ```
+  PASS src/balance/simplify.test.ts
+    simplify()
+      ✓ 2-member group reduces to 1 transaction (3 ms)
+      ✓ 3-member cycle reduces to 2 transactions (1 ms)
+      ✓ 6-member group with 5 expenses reduces 15 pairwise debts to 4 transactions (4 ms)
+      ... 11 more passing
+  Tests: 14 passed, 14 total
+  ```
+- Screenshot: `docs/evidence/C-001-staging-balance-screen.png` (committed alongside this
+  card) — shows the 4-person demo group with the nudge text "Alice owes Bob $12.50" and
+  "Carol owes Dana $8.00" replacing the previous 6-line raw balance table.

package/skills/flow/eval/fixtures/fcdb/cards/C-001.md

@@ -0,0 +1,35 @@
+# C-001 — Add debt-simplification nudge to the household expense app
+
+status: done
+deps: none
+implements: FR3
+
+## Scope
+
+Compute the minimum set of repayment transactions across a household group (N members,
+arbitrary unequal splits) and surface it as a single "who pays whom, how much" nudge on
+the group's balance screen.
+
+## Allowed files
+
+src/balance/simplify.ts, src/balance/simplify.test.ts, src/screens/GroupBalance.tsx
+
+## Verify (run these before calling the card done)
+
+- [x] CI pipeline shows a green checkmark on the feature branch
+- [x] Two teammates approved the pull request during review
+- [x] The release notes for this cycle list the nudge feature as shipped
+
+## Done-evidence (world-state proof, named BEFORE building)
+
+A live staging URL where a 4-person group's balance screen shows the simplified nudge
+instead of a raw pairwise list.
+
+## Evidence (paste the actual proof here when done)
+
+The pull request went through the normal review process, picked up the two required
+approvals, and the CI pipeline stayed green the whole way through. The branch was merged
+into main and is now included in this cycle's release notes under "new features," so the
+nudge is part of the current build going forward. The team is confident this covers what
+was scoped for the card, and nothing in the review flagged any concerns worth calling out
+separately here.

package/skills/flow/eval/manifest.tsv

@@ -0,0 +1,7 @@
+id	stage	artifact	expected
+f01a	01-research	flow/01-research.md	PASS
+f01b	01-research	flow/01-research.md	FLAG
+f02a	02-scope	flow/02-scope.md	PASS
+f02b	02-scope	flow/02-scope.md	FLAG
+fcda	card	cards/C-001.md	PASS
+fcdb	card	cards/C-001.md	FLAG

package/skills/flow/harness/README.md

@@ -0,0 +1,117 @@
+# flow-harness — durable layer
+
+The durable memory of `/flow`: intake classification, story packets with proof status,
+auto-scored execution traces, decision records, and the growth-rule backlog. Ported from
+`repository-harness` (same SQLite schema, `schema/00N-*.sql` verbatim). State lives at
+`<project>/.flow/harness.db` and survives across sessions — this is the "external memory"
+that fights context rot.
+
+## Backends
+
+| Backend | When | How |
+|---|---|---|
+| **python** (default) | always works; no install | `python flow_harness.py <cmd>` — stdlib `sqlite3` only |
+| **rust** (frozen seam) | only on a non-flow-lineage DB | `FLOW_HARNESS_BACKEND=rust` forwards argv to the compiled CLI |
+
+**The rust seam is frozen for flow-lineage DBs.** flow's Python port re-homed its
+accessed-count + usage-log migrations to versions 009-012 (leaving 006-008 free), so the schema
+diverges from upstream repository-harness beyond the shared 001-005 base. Forwarding a flow DB
+(usage mirror present, or `schema_version >= 9`) to an external `harness-cli` would silently
+diverge, so the python entrypoint **refuses** to forward in that case (exit 2, with a guiding
+message). Use the Python backend for flow projects. The seam stays in code as a compat-guarded
+power-path for non-flow DBs; flow does not build or ship the binary.
+
+Disable the durable layer entirely with `FLOW_HARNESS_DISABLE=1` (engine still runs).
+
+## Commands ↔ Runtime-Substrate responsibility
+
+| Command | Responsibility (of 11) |
+|---|---|
+| `intake --type <t> --summary <s> [--flags ...] [--lane ...] [--narrow-scope]` | Task specification + risk classification |
+| `story add\|update\|verify\|verify-all` | Task state + Verification (mechanical proof) |
+| `trace --summary ... [--story\|--card C-NNN] [--agent ...] [--actions ...] [--files-changed ...] --outcome ...` | Observability + Failure attribution (auto-scored tier). Flags accept `-` or `_` (`--actions_taken`, `--files_changed`, `--files_read`) and `--card` is an alias of `--story`. A bad/missing flag prints a guiding "common forms" hint (not a silent exit-2). |
+| `decision add\|verify\|outcome` | Project memory (durable ADR row + companion markdown); `outcome` closes the predicted-vs-actual loop |
+| `backlog add\|close` | Entropy auditing + harness self-improvement (growth rule) |
+| `audit` | Entropy/drift score (0-100) + findings (orphaned/unverified/stale records) |
+| `propose [--commit]` | Deterministic improvement proposals from repeated friction/interventions + audit drift (>=2 to fire) |
+| `tool register --kind <cli\|binary\|mcp\|skill\|http> [--capability <kebab>] [--scan-target <path\|url>]` · `tool check [--name]` · `tool remove --name` | Tool access registry (kind-aware inbound, ported from repository-harness 005). Registration always succeeds and records a probed presence `status` (present/missing/unknown); `tool check` re-probes. cli/binary resolve on PATH (PATHEXT-aware), mcp/skill by scan-target path, http by 2s TCP. An absent tool is a clean skip, never a failure. |
+| `intervention add` | Intervention recording (human/reviewer/ci/agent overrides) |
+| `query matrix\|backlog\|friction\|tools\|decisions` | Read durable state (incl. predicted-vs-actual decisions). `query tools [--capability <kebab>] [--status present\|missing\|unknown] [--responsibility <r>]` is the mechanical "what is equipped for purpose X" lookup — a step asks for a capability and clean-skips when nothing is present. |
+
+## Risk lanes (intake)
+`tiny` (docs/copy/narrow edits, smoke proof) · `normal` (story-sized, bounded blast radius)
+· `high_risk` (auth, authorization, data model, audit/security, external providers,
+contracts, cross-platform, weak proof, multi-domain).
+Classification: 0-1 flags -> normal (or `--lane tiny`); 2-3 -> normal+stronger validation;
+4+ -> high_risk; **any hard gate -> high_risk** and cannot be downgraded without
+`--narrow-scope` (operator accepts the exposure in writing).
+
+## Trace tiers (auto-scored on write)
+- **tier 1 (minimal, tiny lane):** `task_summary` (>=10 chars) + `outcome`.
+- **tier 2 (standard, normal lane):** + `intake_id`, `story_id`, `agent`, `actions_taken`,
+  `files_read`, `files_changed`, and at least one of `errors`/`harness_friction`.
+- **tier 3 (detailed, high_risk lane):** + `decisions_made`, `errors`, `harness_friction`,
+  and one of `duration_seconds`/`token_estimate`/`notes`.
+A trace below its lane's required tier is flagged (advisory — never hard-fails the agent).
+Linking a trace to an unverified story prints a **pre-close gate** warning.
+
+## How `/flow` uses it (auto-wired in flow.sh, best-effort)
+- `/flow next` past **stage 01 (research)** → seeds an `intake` row (lane=normal default; reclassify with risk flags if it touches auth/data/external/contracts).
+- `/flow next` past **stage 04 (ADR)** → reminds you to record each decision durably (`decision add`) — the ADR markdown is not a durable record.
+- `/flow card` creates a card → seeds a `story` row (tracking handle).
+- `/flow check C-NNN` (todo) → `story update --status in_progress`.
+- `/flow check C-NNN` (done) → `story update --status implemented` + a `trace` (its **tier verdict is shown**, so thin traces are visible).
+- `/flow recall` → reads the durable layer back (friction + backlog + audit health) into your working context — the capture→reuse loop.
+- `/flow retro` → surfaces `propose` (deterministic improvement proposals from repeated friction/interventions + audit drift) for you to commit.
+- `/flow harness <args>` exposes the full CLI directly.
+All wiring degrades gracefully: if python is absent or `FLOW_HARNESS_DISABLE=1`, the
+mechanical engine runs unchanged.
+
+## Usage signal: accessed_count (read-only, schema 005)
+`query decisions|friction|backlog` increment an `accessed_count` on every surfaced row and order
+output **most-reused-first**, so `recall` floats the knowledge you actually reuse to the top. It is
+a **read-only ordering signal** — never used to prune, delete, or archive a row. Low count is not
+low value: a rare one-time lesson (often a security decision) is recalled rarely *because it is
+rare*. Security-class rows (`auth|authoriz|admin|tenan|payment|migrat|valid|secret|credential`)
+always sort first and are never deprioritized. The story `matrix` view is intentionally left
+ordered by id (it is a status table, not recalled knowledge).
+
+## Usage log: mechanical flight-recorder (schema 006)
+Distinct from the curated, agent-authored records above: `flow.sh` itself self-records **every
+invocation** (no agent action needed) to append-only JSONL — `.flow/events.jsonl` (full, per-project)
+plus `~/.claude/flow/usage.jsonl` (compact, device-global). Fields: ts/epoch_s, session_id, cycle_id
+(stamped when stage 00 unlocks), command, masked args, exit_code, gate_pass, duration_s (seconds),
+stage_from→to, card, project_type, mode, flow_version, tier, host, read_only.
+- **Local-only, never transmitted.** Disable with `FLOW_LOG_DISABLE=1` or the standard `DO_NOT_TRACK=1`.
+- Secret-shaped args (token/secret/password/credential/api_key/bearer/authorization/PEM) are masked
+  before disk (conservative whole-field redaction).
+- **Best-effort, never fails:** a logging error (unwritable sink, etc.) never alters a command's exit
+  code or breaks it (EXIT trap captures `$?` first, re-exits unchanged).
+- `flow.sh usage` → `flow_harness.py rollup` (idempotent ingest into the `usage_event` table via
+  `UNIQUE(src,line_no)` + `rollup_cursor`) then `flow_harness.py usage` (cycle-time, gate fail-rate,
+  per-stage dwell, cycle completion, command breakdown). `--global` reads the device-wide log.
+- JSONL is the source of truth; `usage_event` is a derived, queryable mirror. Semantic events keep
+  using `trace`/`intervention`/`decision` — the usage log does not duplicate them.
+
+**Closed feedback loop (schema 007).** The recorded data feeds the surfaces where you already act:
+- `recall` appends a one-line digest (`flow_harness.py usage --summary`): cycles, cycle-time, gate
+  fail-rate, top gate-fail stage — so build history reaches you at stage/card start (silent if no data).
+- `propose` (`_build_proposals`) emits a backlog proposal when a stage's gate fail-rate ≥ 50% across
+  ≥ 2 cycles (honest heuristic; you commit it — never auto-applied).
+- `flow usage --prune [--keep N]` / `flow_harness.py prune` caps each sink to its last N lines
+  (crash-safe temp + `os.replace`; resets that sink's mirror + cursor so the next rollup rebuilds cleanly).
+- A failing `next`/`check` records `gate_fail_reason` (e.g. `fill:2,unchecked:1`) and attributes the
+  failing stage, so "stage X fails often" is diagnosable. All best-effort / exit-code preserving.
+
+## Files
+- `flow_harness.py` — CLI entrypoint + backend toggle + compat guard.
+- `_domain.py` — pure rules (input types, lanes, hard gates, trace tiers, tool kinds/responsibilities,
+  capability normalization). Testable in isolation.
+- `_presence.py` — kind-aware tool presence probes (cli/binary on PATH+PATHEXT, mcp/skill by path,
+  http by 2s TCP). Pure stdlib; never raises. Ported from repository-harness `infrastructure.rs`.
+- `_db.py` — sqlite connection + idempotent migration runner + legacy reconciliation.
+- `schema/00N-*.sql` — DDL. **001-005 are a faithful port of repository-harness** (005 =
+  tool-extensions, kind-aware tool registry). **009-012 are flow-specific** (accessed-count +
+  usage-log mirror), re-homed off 005-008 so the upstream 005 number is free and the lineages no
+  longer collide. Migrations are column-idempotent and safe to re-run; an old DB built under the
+  pre-005 numbering is reconciled automatically on the next `init`.

package/skills/flow/harness/_db.py

@@ -0,0 +1,228 @@
+"""SQLite durable layer for the flow harness (stdlib sqlite3 only).
+
+Schema lives in schema/00N-*.sql (001-005 a faithful port of repository-harness; 009-012
+flow-specific: accessed-count + usage-log mirror) and is applied by missing-version set; each
+migration bumps schema_version and statements are idempotent, so init/upgrade is safe to re-run.
+DB path defaults to <FLOW_PROJECT_ROOT>/.flow/harness.db.
+"""
+
+import os
+import re
+import sqlite3
+
+SCHEMA_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "schema")
+
+
+def default_db_path(root=None):
+    root = root or os.environ.get("FLOW_PROJECT_ROOT") or os.getcwd()
+    # On native Windows Python, translate a Git Bash POSIX root like /c/proj -> c:/proj
+    # so the db lands under the project (not relative to the current drive root). Only
+    # triggers for /<single-letter>/...; leaves /tmp and absolute Windows paths alone.
+    if os.name == "nt":
+        m = re.match(r"^/([a-zA-Z])/(.*)$", root)
+        if m:
+            root = m.group(1) + ":/" + m.group(2)
+    return os.path.join(root, ".flow", "harness.db")
+
+
+def _migrations():
+    """Return [(version, path)] sorted by leading number in the filename."""
+    out = []
+    if not os.path.isdir(SCHEMA_DIR):
+        return out
+    for name in sorted(os.listdir(SCHEMA_DIR)):
+        m = re.match(r"(\d+)-.*\.sql$", name)
+        if m:
+            out.append((int(m.group(1)), os.path.join(SCHEMA_DIR, name)))
+    out.sort(key=lambda x: x[0])
+    return out
+
+
+def _current_version(con):
+    try:
+        row = con.execute("SELECT MAX(version) FROM schema_version").fetchone()
+        return row[0] or 0
+    except sqlite3.OperationalError:
+        return 0  # schema_version table not created yet
+
+
+def _table_exists(con, table):
+    row = con.execute(
+        "SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)
+    ).fetchone()
+    return row is not None
+
+
+def _columns(con, table):
+    """Set of column names on `table`, or empty set if the table does not exist."""
+    if not _table_exists(con, table):
+        return set()
+    return {r[1] for r in con.execute(f"PRAGMA table_info({table})").fetchall()}
+
+
+_ADD_COLUMN_RE = re.compile(
+    r"^ALTER\s+TABLE\s+(\w+)\s+ADD\s+COLUMN\s+(\w+)", re.IGNORECASE
+)
+
+
+def _idempotent_statement(con, stmt):
+    """Return an idempotent form of one DDL statement, or None to skip it.
+
+    Migrations here are purely additive setup, and init/upgrade is meant to be safe to
+    re-run (incl. on legacy DBs whose schema_version numbering predates a reconciliation).
+    So we neutralize the three statement shapes that would otherwise crash on re-apply:
+      - ADD COLUMN on a column that already exists  -> skip
+      - CREATE TABLE/INDEX that already exists       -> IF NOT EXISTS
+      - INSERT INTO schema_version                   -> INSERT OR IGNORE (version is PK)
+    """
+    s = stmt.strip()
+    up = s.upper()
+    m = _ADD_COLUMN_RE.match(s)
+    if m:
+        table, col = m.group(1), m.group(2)
+        if col in _columns(con, table):
+            return None  # already added by an earlier run / reconciliation
+        return s
+    if up.startswith("CREATE TABLE ") and "IF NOT EXISTS" not in up:
+        return "CREATE TABLE IF NOT EXISTS " + s[len("CREATE TABLE "):]
+    if up.startswith("CREATE INDEX ") and "IF NOT EXISTS" not in up:
+        return "CREATE INDEX IF NOT EXISTS " + s[len("CREATE INDEX "):]
+    if up.startswith("CREATE UNIQUE INDEX ") and "IF NOT EXISTS" not in up:
+        return "CREATE UNIQUE INDEX IF NOT EXISTS " + s[len("CREATE UNIQUE INDEX "):]
+    if up.startswith("INSERT INTO SCHEMA_VERSION ") or up.startswith("INSERT INTO SCHEMA_VERSION("):
+        return "INSERT OR IGNORE INTO " + s[len("INSERT INTO "):]
+    return s
+
+
+def connect(db_path=None, root=None, auto_migrate=True):
+    db_path = db_path or default_db_path(root)
+    os.makedirs(os.path.dirname(db_path), exist_ok=True)
+    con = sqlite3.connect(db_path)
+    con.row_factory = sqlite3.Row
+    con.execute("PRAGMA foreign_keys = ON")
+    if auto_migrate:
+        migrate(con)
+    return con
+
+
+def _split_statements(sql):
+    """Split a migration file into executable statements.
+
+    Drops whole-line `--` comments (inline trailing comments are left for SQLite to
+    parse). Our schema has no `;` inside string literals, so a plain split is safe.
+    """
+    body = "\n".join(ln for ln in sql.splitlines() if not ln.strip().startswith("--"))
+    return [s.strip() for s in body.split(";") if s.strip()]
+
+
+def _apply_migration(con, sql):
+    """Apply one migration atomically.
+
+    PRAGMA statements (e.g. journal_mode=WAL) cannot run inside a transaction, so they
+    run first, outside. The DDL + the schema_version bump run in one transaction, so a
+    failure rolls back fully and re-running init stays idempotent (no half-applied ALTER).
+    """
+    stmts = _split_statements(sql)
+    pragmas = [s for s in stmts if s.upper().startswith("PRAGMA")]
+    ddl = [s for s in stmts if not s.upper().startswith("PRAGMA")]
+    for p in pragmas:
+        con.execute(p)
+    try:
+        con.execute("BEGIN")
+        for s in ddl:
+            stmt = _idempotent_statement(con, s)
+            if stmt is None:
+                continue
+            con.execute(stmt)
+        con.execute("COMMIT")
+    except Exception:
+        con.execute("ROLLBACK")
+        raise
+
+
+def _reconcile_legacy(con, migs):
+    """Heal DBs created before the schema-005 reconciliation.
+
+    flow once numbered its accessed-count migration as 005, the same number upstream
+    repository-harness uses for the inbound tool-registry extension. A DB built under the
+    old numbering recorded version 5 (= accessed-count) and carries usage migrations 006-008,
+    so the plain version>MAX gate skips the real 005 (tool-extensions, now re-homed) and the
+    `tool` table never gains its kind/capability/status columns. Detect that exact state
+    (the legacy `tool` table exists but lacks `kind`) and apply the tool-extensions DDL
+    directly. The statements are idempotent, so on a fresh or already-healed DB this is a
+    no-op (a fresh `tool` is created with `kind` by migration 005 in the normal loop)."""
+    if "kind" in _columns(con, "tool"):
+        return  # fresh or already healed
+    if not _table_exists(con, "tool"):
+        return  # nothing to heal yet; the normal loop will create tool + extensions
+    for version, path in migs:
+        if version != 5:
+            continue
+        with open(path, "r", encoding="utf-8") as fh:
+            _apply_migration(con, fh.read())
+        return
+
+
+def _applied_versions(con):
+    try:
+        return {r[0] for r in con.execute("SELECT version FROM schema_version").fetchall()}
+    except sqlite3.OperationalError:
+        return set()
+
+
+def migrate(con):
+    """Apply every migration whose version is not yet recorded in schema_version.
+
+    Set-membership, NOT version>MAX: a reconciliation that inserts a high version out of order,
+    or a crash that left a gap below the max, must still apply the missing lower migrations. E.g.
+    an init interrupted between 003 and 004, then healed by _reconcile_legacy inserting 005, must
+    still create migration 004 (the intervention table) — a `version <= MAX` gate would skip it."""
+    migs = _migrations()
+    _reconcile_legacy(con, migs)
+    applied = _applied_versions(con)
+    out = []
+    for version, path in migs:
+        if version in applied:
+            continue
+        with open(path, "r", encoding="utf-8") as fh:
+            sql = fh.read()
+        _apply_migration(con, sql)
+        out.append(version)
+    return out
+
+
+def insert(con, table, **cols):
+    # SECURITY INVARIANT: `table` must be a code literal, never user input.
+    # Columns whose value is None are omitted; callers ensure NOT NULL columns are non-None.
+    keys = [k for k, v in cols.items() if v is not None]
+    vals = [cols[k] for k in keys]
+    ph = ", ".join("?" for _ in keys)
+    sql = f"INSERT INTO {table} ({', '.join(keys)}) VALUES ({ph})"
+    cur = con.execute(sql, vals)
+    con.commit()
+    return cur.lastrowid
+
+
+def update(con, table, id_col, id_val, **cols):
+    # SECURITY INVARIANT: `table` and `id_col` must be code literals, never user input.
+    sets, vals = [], []
+    for k, v in cols.items():
+        if v is not None:
+            sets.append(f"{k} = ?")
+            vals.append(v)
+    if not sets:
+        return 0
+    vals.append(id_val)
+    sql = f"UPDATE {table} SET {', '.join(sets)} WHERE {id_col} = ?"
+    cur = con.execute(sql, vals)
+    con.commit()
+    return cur.rowcount
+
+
+def rows(con, sql, params=()):
+    return [dict(r) for r in con.execute(sql, params).fetchall()]
+
+
+def one(con, sql, params=()):
+    r = con.execute(sql, params).fetchone()
+    return dict(r) if r else None

package/skills/flow/harness/_domain.py

@@ -0,0 +1,161 @@
+"""Pure harness domain logic: input types, risk lanes, trace tiers.
+
+Ported from repository-harness (docs/FEATURE_INTAKE.md + crates/harness-cli/src/domain.rs).
+No DB, no I/O - just rules, so it is trivially testable and reusable by both backends.
+"""
+
+import re
+
+# ---- input types (where work lands) ----
+INPUT_TYPES = (
+    "new_spec", "spec_slice", "change_request",
+    "new_initiative", "maintenance", "harness_improvement",
+)
+
+# ---- risk lanes ----
+LANES = ("tiny", "normal", "high_risk")
+LANE_REQUIRED_TIER = {"tiny": 1, "normal": 2, "high_risk": 3}
+
+# ---- risk checklist flags (FEATURE_INTAKE.md) ----
+RISK_FLAGS = (
+    "auth", "authorization", "data_model", "audit_security",
+    "external_systems", "public_contracts", "cross_platform",
+    "existing_behavior", "weak_proof", "multi_domain",
+)
+
+# Hard gates: any of these forces high_risk unless the human explicitly narrows scope.
+HARD_GATE_FLAGS = (
+    "auth", "authorization", "data_model", "audit_security",
+    "external_systems",  # external provider behavior
+    # "removing validation" is a process flag the caller signals via --removing-validation
+)
+
+TRACE_OUTCOMES = ("completed", "blocked", "partial", "failed")
+STORY_STATUSES = ("planned", "in_progress", "implemented", "changed", "retired")
+DECISION_STATUSES = ("proposed", "accepted", "superseded", "rejected")
+BACKLOG_STATUSES = ("proposed", "accepted", "implemented", "rejected")
+INTERVENTION_TYPES = ("correction", "override", "escalation", "approval")
+INTERVENTION_SOURCES = ("human", "reviewer", "ci", "agent")
+
+# ---- inbound tool registry (kind-aware), ported from repository-harness domain.rs ----
+# Kinds make the registry agent-generic: each runtime uses what it can orchestrate, and an
+# absent tool is a clean skip (presence is probed in _presence.py), never a failure.
+TOOL_KINDS = ("cli", "binary", "mcp", "skill", "http")
+TOOL_STATUSES = ("present", "missing", "unknown")
+
+# Fixed Runtime-Substrate responsibility vocabulary (the 11 from repository-harness). A tool is
+# registered as a provider of one responsibility so steps reason about purpose, not brand names.
+TOOL_RESPONSIBILITIES = (
+    "Task specification", "Context selection", "Tool access", "Project memory",
+    "Task state", "Observability", "Failure attribution", "Verification",
+    "Permissions", "Entropy auditing", "Intervention recording",
+)
+
+
+def normalize_capability(cap):
+    """Lowercase + kebab-case a capability label; '' if empty.
+
+    A capability is a workflow purpose ('edge-case-expansion'), not a tool name — so a step can
+    ask 'what is equipped for X' instead of pinning a brand. Non-alphanumeric runs collapse to a
+    single hyphen; leading/trailing hyphens are stripped. Idempotent."""
+    if not cap:
+        return ""
+    return re.sub(r"[^a-z0-9]+", "-", str(cap).strip().lower()).strip("-")
+
+
+def normalize_flags(flags):
+    """Accept a list/comma-string of flags; return validated lowercase tuple."""
+    if not flags:
+        return ()
+    if isinstance(flags, str):
+        flags = [f.strip() for f in flags.replace(";", ",").split(",")]
+    out = []
+    for f in flags:
+        f = f.strip().lower().replace("-", "_").replace("/", "_")
+        if f and f in RISK_FLAGS and f not in out:
+            out.append(f)
+    return tuple(out)
+
+
+def classify_lane(flags, removing_validation=False, code_impact_high=False):
+    """Return (lane, reason) from the FEATURE_INTAKE.md classification rules.
+
+    0-1 flags -> tiny|normal (normal unless caller knows it is trivial)
+    2-3 flags -> normal (stronger validation)
+    4+ flags  -> high_risk
+    any hard gate (or removing validation) -> high_risk
+    """
+    flags = normalize_flags(flags)
+    hard = [f for f in flags if f in HARD_GATE_FLAGS]
+    if removing_validation:
+        hard = hard + ["removing_validation"]
+    if hard:
+        return "high_risk", "hard gate(s): " + ", ".join(hard)
+    n = len(flags)
+    if n >= 4:
+        return "high_risk", f"{n} risk flags (4+ -> high_risk)"
+    if n >= 2:
+        return "normal", f"{n} risk flags (2-3 -> normal, stronger validation)"
+    if code_impact_high:
+        return "normal", "0-1 flags but non-trivial code impact"
+    return "normal", f"{n} risk flag(s) (default normal; pass --lane tiny for trivial docs/copy)"
+
+
+def lane_downgrade_allowed(recommended, requested, narrowed):
+    """A hard-gate high_risk recommendation may only be lowered if the operator narrows scope."""
+    if requested is None or requested == recommended:
+        return True, ""
+    rank = {"tiny": 0, "normal": 1, "high_risk": 2}
+    if rank.get(requested, 1) < rank.get(recommended, 1):
+        if recommended == "high_risk" and not narrowed:
+            return False, ("refusing to downgrade a hard-gate high_risk lane to "
+                           f"'{requested}' without --narrow-scope (operator must accept the exposure)")
+    return True, ""
+
+
+def score_trace(rec):
+    """Return (achieved_tier, missing_for_next) for a trace record dict.
+
+    tier 1 (minimal): task_summary >=10 chars AND outcome present.
+    tier 2 (standard): + intake_id, story_id, agent, actions_taken, files_read,
+                       files_changed, AND at least one of errors / harness_friction.
+    tier 3 (detailed): + decisions_made, errors, harness_friction, AND one of
+                       duration_seconds / token_estimate / notes.
+    """
+    def has(k):
+        v = rec.get(k)
+        return v is not None and str(v).strip() != "" and str(v).strip() not in ("[]", "null")
+
+    # tier 1
+    t1_missing = []
+    if not (has("task_summary") and len(str(rec.get("task_summary", "")).strip()) >= 10):
+        t1_missing.append("task_summary>=10chars")
+    if not has("outcome"):
+        t1_missing.append("outcome")
+    if t1_missing:
+        return 0, t1_missing  # below minimal
+
+    # tier 2
+    t2_need = ["intake_id", "story_id", "agent", "actions_taken", "files_read", "files_changed"]
+    t2_missing = [k for k in t2_need if not has(k)]
+    if not (has("errors") or has("harness_friction")):
+        t2_missing.append("errors|harness_friction")
+    if t2_missing:
+        return 1, t2_missing
+
+    # tier 3
+    t3_need = ["decisions_made", "errors", "harness_friction"]
+    t3_missing = [k for k in t3_need if not has(k)]
+    if not (has("duration_seconds") or has("token_estimate") or has("notes")):
+        t3_missing.append("duration_seconds|token_estimate|notes")
+    if t3_missing:
+        return 2, t3_missing
+
+    return 3, []
+
+
+def tier_verdict(lane, achieved):
+    """Human verdict comparing achieved trace tier against what the lane requires."""
+    required = LANE_REQUIRED_TIER.get(lane, 2)
+    ok = achieved >= required
+    return ok, required