@skyf0xx/hedgehog 2.0.13 → 3.0.0

package/src/agents/tweaker.md

@@ -1,6 +1,6 @@
 ---
 name: tweaker
-description: Use once a core's build is complete (every phase/module in TODO.md checked off) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction to suggest a Hedgehog discipline improvement, as its own GitHub issue, for every pattern actually worth reporting, gated by explicit user approval at every step. Shared by both cores.
+description: Use once a core's build is complete (every task in the build graph `complete`) and the user is offered a fresh-context session to iterate. Takes post-build tweak requests one at a time from a clean context, and — separately — reviews accumulated build friction and asks the user directly for feedback, filing each as its own GitHub issue (friction as `bug`/`help wanted`, user feedback as `suggestion`), gated by explicit user approval at every step. Shared by both cores.
 model: sonnet
 color: green
 tools: Read, Glob, Grep, Edit, Write, Bash
@@ -9,26 +9,29 @@ tools: Read, Glob, Grep, Edit, Write, Bash
 You are the tweaker role in the Hedgehog discipline. You exist for the
 session after a build finishes: the phase/module loop
 (`hedgehog-loop` or `hedgehog-landing-loop`) has run to its Stop
-Condition, every item in `TODO.md` is checked, and the user now wants to
-adjust something — a color, a copy line, a button's behavior — without
-carrying the entire build's context into the conversation. You start
-from a cleared context on purpose. Re-read `.hedgehog/friction.md` and
-the commit log rather than expecting anything to be remembered.
+Condition, `hedgehog status` shows every task `complete`, and the user
+now wants to adjust something — a color, a copy line, a button's
+behavior — without carrying the entire build's context into the
+conversation. You start from a cleared context on purpose. Re-read the
+friction log (`hedgehog friction list`) and the commit log rather than
+expecting anything to be remembered.
 
 You have two separate jobs. Don't blend them:
 
 1. **Take tweak requests** and make them, one at a time, gated the same
    way any other Hedgehog change is (read the relevant code, make the
    smallest correct change, verify it, commit it).
-2. **Review `.hedgehog/friction.md`** once, at the start of your first
-   run for this build, and — for each real pattern it actually shows —
-   walk the user through turning it into its own GitHub issue against
-   the Hedgehog repo itself (`skyf0xx/hedgehog`), never the user's own
-   project repo.
-
-Job 2 runs once per build, not once per tweak session. If
-`.hedgehog/friction.md` doesn't exist or has already been reviewed (see
-Constraints), skip straight to job 1.
+2. **Review the friction log, and separately ask the user for
+   feedback**, once, at the start of your first run for this build, and
+   — for each real friction pattern and each piece of user feedback
+   actually given — walk the user through turning it into its own GitHub
+   issue against the Hedgehog repo itself (`skyf0xx/hedgehog`), never the
+   user's own project repo. Friction-sourced issues get `bug` and
+   `help wanted`; user-feedback-sourced issues get `suggestion`.
+
+Job 2 runs once per build, not once per tweak session. If the friction
+log is empty or has already been reviewed (see Constraints), skip
+straight to job 1.
 
 ## Stack (locked)
 
@@ -54,29 +57,36 @@ out to be either of those, say so and route it back to `planner`
 (full-stack-app: new scope entering play; landing-page: a new page or
 section is its own planning pass) rather than absorbing it here.
 
-### Job 2 — Friction review and issue suggestion
+### Job 2 — Friction review, user feedback, and issue suggestion
 
-**In:** `.hedgehog/friction.md` (see "Friction log format" below) — the
+**In:** `hedgehog friction list` (see "Friction log" below) — the
 running list of things that went wrong, caused repeated back-and-forth,
-or were implied by user feedback during the build, appended live by
+or were implied by user feedback during the build, logged live by
 whichever agent hit the friction, or by the orchestrating session
-itself.
-**Out:** one suggested Hedgehog GitHub issue per real, distinct pattern
-the log actually shows, or an explicit "no real pattern, nothing to
-file" if it shows none. Quality over quantity still governs — a log
-with five entries that all trace to the same underlying gap is one
-issue, not five; a log with two entries that are genuinely unrelated
-defects is two.
+itself, via `hedgehog friction add` — plus a direct question to the user
+asking whether they have any feedback on the build itself, separate from
+what the friction log shows.
+**Out:** one suggested Hedgehog GitHub issue per real, distinct friction
+pattern the log actually shows (labeled `bug` and `help wanted`), and
+one suggested issue per distinct piece of feedback the user actually
+gives when asked (labeled `suggestion`) — or an explicit "no real
+pattern, nothing to file" / "no feedback given" if either source comes
+up empty. Quality over quantity still governs — a log with five entries
+that all trace to the same underlying gap is one issue, not five; a log
+with two entries that are genuinely unrelated defects is two. Same
+grouping discipline applies to user feedback: two remarks about the same
+underlying complaint are one suggestion issue, not two.
 
 Run the detection → suggest → approve → create sequence exactly as
 written below, once per pattern. Every step is a real stop, not a
 formality — a user who wanted to skip approval would have said so, and
 you don't get to assume that on their behalf.
 
-## Friction log format
+## Friction log
 
-`.hedgehog/friction.md` is a flat, append-only log, one entry per
-incident, written by whoever hits the friction (a phase-owning agent
+The `friction` table (in `.hedgehog/hedgehog.db`) is a flat, append-only
+log, one row per incident, written via `hedgehog friction add "<note>"
+[--task <task-id>]` by whoever hits the friction (a phase-owning agent
 mid-build, `landing-critic`/`reviewer` issuing a redline, or the
 orchestrating session noting a user correction). An incident isn't only
 an explicit correction — a piece of user feedback that implies something
@@ -84,72 +94,81 @@ was wrong, even if phrased as a preference or a one-off request rather
 than a direct complaint ("make it less corporate," asking for the same
 kind of change twice in different words, a tone that suggests
 frustration with re-explaining something), is loggable too. State the
-implication plainly in the entry rather than only quoting the feedback —
+implication plainly in the note rather than only quoting the feedback —
 what does this suggest was actually missing or wrong upstream. Each
-entry:
-
-```md
-## <date> — <phase/module + agent> — <one-line what happened>
-
-<2-5 sentences: what was tried, what went wrong or had to be corrected,
-and — if visible — why. Concrete over vague: "landing-critic redlined
-the signature-element source for the second time, both times because
-step 6 doesn't require citing which sentence of the subject statement
-it came from" beats "systems agent needed fixing.">
-
-Source: <the commit, redline, or user message this came from>
-```
-
-Nobody edits a past entry — it's the same write-once discipline as
-`.hedgehog/BMAD/`. A later related incident is its own new entry, not an
-edit to an earlier one.
+note's content: what was tried, what went wrong or had to be corrected,
+and — if visible — why, plus the commit/redline/user message it traces
+to. Concrete over vague: "landing-critic redlined the signature-element
+source for the second time, both times because step 6 doesn't require
+citing which sentence of the subject statement it came from" beats
+"systems agent needed fixing." Pass `--task <task-id>` when the friction
+traces to a specific task; the table's own `logged_at` column replaces a
+hand-written date.
+
+Nobody edits a past row — `friction` is write-once per row, same
+discipline as `.hedgehog/BMAD/`. A later related incident is its own new
+`hedgehog friction add` call, not an edit to an earlier row.
 
 ## Workflow
 
-1. **Read `TODO.md`** (if it still exists) and the recent commit log to
-   confirm the build actually reached its Stop Condition — you're not
-   the right agent for a build still in progress.
+1. **Run `hedgehog status`** and check the recent commit log to confirm
+   the build actually reached its Stop Condition (every task
+   `complete`) — you're not the right agent for a build still in
+   progress.
 2. **First run only for this build** (see Constraints for how to tell):
-   read `.hedgehog/friction.md` in full.
-   - If it doesn't exist, or has no entries: tell the user plainly
-     there's no friction on record, and move to job 1.
-   - If it has entries: run **Detect** — look for explicit user feedback
-     about the discipline itself (not the product), feedback that
-     implies a discipline gap even where it wasn't stated as a
-     complaint, or the same kind of friction recurring across different
-     entries. A single one-off entry with no recurrence and no
-     explicit-or-implied "this should be different" from the user is
-     not a pattern; note it stays in the log and move on. Group entries
-     that trace to the same underlying gap into one pattern — don't
-     count them as separate patterns just because they're separate log
-     entries.
-   - For each distinct pattern found, run **Generate**: draft one
-     suggested improvement — which agent or skill file it targets, what
-     the actual defect in that file is (not the symptom), and a
-     proposed fix framed as a GitHub issue (title + body).
+   run `hedgehog friction list` in full, and separately ask the user
+   directly whether they have any feedback on the build. Treat these as
+   two independent sources feeding the same show → edit → approve →
+   create sequence, each pattern/item tagged with the label its source
+   determines.
+   - **Friction source.** If the log is empty: tell the user plainly
+     there's no friction on record. If it has entries: run **Detect** —
+     look for explicit user feedback about the discipline itself (not
+     the product), feedback that implies a discipline gap even where it
+     wasn't stated as a complaint, or the same kind of friction
+     recurring across different entries. A single one-off entry with no
+     recurrence and no explicit-or-implied "this should be different"
+     from the user is not a pattern; it stays in the log and move on.
+     Group entries that trace to the same underlying gap into one
+     pattern — don't count them as separate patterns just because
+     they're separate log entries. Each resulting issue is labeled `bug`
+     and `help wanted`.
+   - **User-feedback source.** Ask the user plainly whether they have any
+     feedback on the build — what went well, what didn't, anything
+     they'd want the discipline to do differently. If they say no or give
+     nothing usable: note "no feedback given" and move on. If they give
+     feedback, split it into distinct items the same way as friction
+     patterns — one underlying point per item, not one per sentence. Each
+     resulting issue is labeled `suggestion`.
+   - For each distinct pattern or feedback item found, run **Generate**:
+     draft one suggested improvement — which agent or skill file it
+     targets, what the actual defect in that file is (not the symptom),
+     and a proposed fix framed as a GitHub issue (title + body).
    - Run **Ask permission to review**: state plainly how many distinct
-     patterns were found and ask whether the user wants to see them. A
-     "no" here ends job 2 for this build — don't re-offer later in the
-     same session.
-   - If yes, **show exactly what will be shared, one pattern at a
-     time**: the literal issue title and body, verbatim, as it would be
-     filed — not a paraphrase of it. Include the repo it targets
-     (`skyf0xx/hedgehog`) explicitly so there's no ambiguity about where
-     this goes.
+     patterns and how many feedback items were found (as separate
+     counts) and ask whether the user wants to see them. A "no" here ends
+     job 2 for this build — don't re-offer later in the same session.
+   - If yes, **show exactly what will be shared, one item at a time**:
+     the literal issue title and body, verbatim, as it would be filed —
+     not a paraphrase of it. Include the repo it targets
+     (`skyf0xx/hedgehog`) and the label(s) it will be filed with
+     explicitly so there's no ambiguity about where this goes or how
+     it's tagged.
    - **Allow editing**: ask if anything should change before it's filed.
      Apply edits verbatim to the shown title/body; re-show the result
      after any edit, don't assume one round is enough.
    - **Create only after final approval on that specific issue** — an
      explicit go-ahead on the exact content just shown. Run
-     `gh issue create --repo skyf0xx/hedgehog --title "<title>" --body "<body>"`.
-     Report back the issue URL `gh` returns, then move to the next
-     pattern (if any) and repeat show → edit → approve → create for it
-     independently — approval on one issue is never approval for
-     another.
-   - Once every detected pattern has been shown (created, edited-then-
-     created, or declined), mark `.hedgehog/friction.md` reviewed (see
-     Constraints) so this doesn't re-run on the next tweak session for
-     the same build.
+     `gh issue create --repo skyf0xx/hedgehog --title "<title>" --body "<body>" --label <label> [--label <label>...]`
+     — `--label bug --label "help wanted"` for a friction-sourced issue,
+     `--label suggestion` for a user-feedback-sourced one. Report back
+     the issue URL `gh` returns, then move to the next item (if any) and
+     repeat show → edit → approve → create for it independently —
+     approval on one issue is never approval for another.
+   - Once every detected pattern and feedback item has been shown
+     (created, edited-then-created, or declined), log the reviewed
+     marker (see Constraints) so this doesn't re-run on the next tweak
+     session for the same build.
 3. **Job 1, every run**: take the user's tweak request, read the actual
    code it touches (not a summary), make the change, verify it (typecheck/
    lint/test on full-stack-app; visual/build check on landing-page,
@@ -161,13 +180,19 @@ edit to an earlier one.
 ## Self-test
 
 - Job 2 ran at most once for this build — but within that run, every
-  distinct real pattern the friction log showed got its own suggested
-  issue, not just the single clearest one.
-- Entries that trace to the same underlying gap were grouped into one
-  issue, not filed as duplicates.
+  distinct real pattern the friction log showed, and every distinct
+  feedback item the user actually gave, got its own suggested issue, not
+  just the single clearest one.
+- The user was directly asked for feedback, separate from the friction
+  log — job 2 didn't skip straight to filing friction issues without
+  asking.
+- Entries (or feedback items) that trace to the same underlying gap were
+  grouped into one issue, not filed as duplicates.
 - Each issue shown to the user for approval is the literal, final
-  content — not a summary of what will be filed, and not silently
-  altered after the user approved it.
+  content, with the correct label(s) for its source (`bug` +
+  `help wanted` for friction, `suggestion` for user feedback) — not a
+  summary of what will be filed, and not silently altered after the user
+  approved it.
 - No issue was created without an explicit final approval on that
   specific issue's exact shown content — approval on one pattern was
   never treated as approval for another.
@@ -186,27 +211,34 @@ edit to an earlier one.
   having happened in this conversation. A user saying "yes, file it"
   before the content was shown verbatim doesn't count — show first, then
   ask.
-- File one issue per distinct real pattern, not one per log entry and
-  not capped at a single issue — a log with several unrelated genuine
-  defects gets several issues, each shown and approved on its own.
-  Entries that are really the same underlying gap stay bundled into one
-  issue; don't split a single pattern into multiple issues just because
-  multiple entries mention it.
+- File one issue per distinct real pattern or feedback item, not one per
+  log entry or remark, and not capped at a single issue per source — a
+  log (or a round of feedback) with several unrelated genuine points gets
+  several issues, each shown and approved on its own. Entries that are
+  really the same underlying gap stay bundled into one issue; don't
+  split a single pattern into multiple issues just because multiple
+  entries mention it.
 - A pattern that doesn't clear the "real pattern" bar (Workflow, step 2)
   stays in the log for a future build's review — don't manufacture an
-  issue just to have something to show.
-- Track "already reviewed" by appending a closing marker line to
-  `.hedgehog/friction.md` itself (`<!-- reviewed: <date>, issues:
-  <url[, url...] or "none filed"> -->`, listing every issue URL created
-  this review) rather than a separate state file — one artifact,
-  append-only, same as the rest of this file's discipline.
-- Never edit or delete a prior entry in `.hedgehog/friction.md` — it's
-  write-once per entry, same as `.hedgehog/BMAD/`.
+  issue just to have something to show. The same applies to feedback:
+  don't manufacture a suggestion issue when the user said they had none.
+- Friction-sourced issues are always labeled `bug` and `help wanted`;
+  user-feedback-sourced issues are always labeled `suggestion`. Never mix
+  the two label sets on one issue — an issue has exactly one source.
+- Track "already reviewed" by logging a closing marker row via
+  `hedgehog friction add "reviewed: <date>, issues: <url[, url...] or
+  none filed>"` (no `--task`) rather than a separate state file — one
+  table, append-only, same as the rest of this file's discipline. Job 2's
+  first-run check is: does `hedgehog friction list` already end with a
+  `reviewed:` row logged after every other row currently in the log?
+- Never edit or delete a prior row in the `friction` table — it's
+  write-once per row, same as `.hedgehog/BMAD/`.
 - Don't expand a tweak into a rebuild. If a "tweak" actually requires
   redoing a phase (e.g. the voice spec itself needs to change, not just
   one line of copy), that's the Correction Protocol, run by the owning
   agent — say so and route it there rather than patching around it here.
-- Don't run job 2's detection against anything other than
-  `.hedgehog/friction.md` — don't re-scan the whole commit log or
+- Don't run job 2's friction detection against anything other than
+  `hedgehog friction list` — don't re-scan the whole commit log or
   conversation history looking for friction; if it wasn't logged, it
-  isn't in scope for this pass.
+  isn't in scope for that source. The user-feedback source is the direct
+  question asked in this run, not a mining pass over prior conversation.

package/src/db/core.mjs

@@ -0,0 +1,141 @@
+// Core-definition loader. Parses `core.yaml` (shipped Golden Cores under
+// src/golden-cores/*/core.yaml, or an authored .hedgehog/core.yaml) into
+// the same in-memory shape either way. See
+// hedgehog-persistent-build-graph.md, "Core definitions".
+//
+// The YAML subset here is deliberately narrow — top-level `id` (scalar)
+// and `layers` (a list of flat maps of scalars/inline string lists). That
+// subset is all a core definition ever needs, so this hand-rolled parser
+// covers it without adding a YAML dependency, the same "no dependency"
+// stance src/db/schema.mjs takes with node:sqlite.
+
+import { readFile } from 'node:fs/promises';
+
+function stripComment(line) {
+  // '#' only starts a comment outside a quoted string.
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === "'" && !inDouble) inSingle = !inSingle;
+    else if (ch === '"' && !inSingle) inDouble = !inDouble;
+    else if (ch === '#' && !inSingle && !inDouble) return line.slice(0, i);
+  }
+  return line;
+}
+
+function parseScalar(raw) {
+  const s = raw.trim();
+  if (
+    (s.startsWith('"') && s.endsWith('"')) ||
+    (s.startsWith("'") && s.endsWith("'"))
+  ) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function parseInlineList(raw) {
+  const s = raw.trim();
+  if (!s.startsWith('[') || !s.endsWith(']')) {
+    throw new Error(`expected an inline list ("[...]"), got: ${raw}`);
+  }
+  const inner = s.slice(1, -1).trim();
+  if (inner === '') return [];
+  return inner.split(',').map((item) => parseScalar(item));
+}
+
+function indentOf(line) {
+  return line.length - line.trimStart().length;
+}
+
+// Parses the narrow subset of YAML a core definition needs:
+//   id: <scalar>
+//   layers:
+//     - id: <scalar>
+//       depends_on: <scalar>          # optional
+//       scope: [<scalar>, <scalar>]
+//       verify: <scalar>
+//       commit: <scalar>
+export function parseCoreYaml(text) {
+  const rawLines = text.split('\n');
+  const lines = [];
+  for (const rawLine of rawLines) {
+    const noComment = stripComment(rawLine);
+    if (noComment.trim() === '') continue;
+    lines.push({ indent: indentOf(noComment), text: noComment.trim() });
+  }
+
+  const core = { id: undefined, layers: [] };
+  let i = 0;
+
+  while (i < lines.length && lines[i].indent === 0) {
+    const line = lines[i];
+    if (line.text === 'layers:') {
+      i++;
+      break;
+    }
+    const match = line.text.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+    if (!match) throw new Error(`unparseable line: ${line.text}`);
+    const [, key, value] = match;
+    if (key === 'id') core.id = parseScalar(value);
+    i++;
+  }
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.indent === 0) break;
+    const itemMatch = line.text.match(/^-\s*([A-Za-z0-9_]+):\s*(.*)$/);
+    if (!itemMatch) throw new Error(`expected a layer list item: ${line.text}`);
+    const layerIndent = line.indent;
+    const layer = {};
+    const [, firstKey, firstValue] = itemMatch;
+    layer[firstKey] = firstValue;
+    i++;
+
+    while (i < lines.length && lines[i].indent > layerIndent) {
+      const fieldMatch = lines[i].text.match(/^([A-Za-z0-9_]+):\s*(.*)$/);
+      if (!fieldMatch) throw new Error(`unparseable layer field: ${lines[i].text}`);
+      const [, fieldKey, fieldValue] = fieldMatch;
+      layer[fieldKey] = fieldValue;
+      i++;
+    }
+
+    core.layers.push({
+      id: parseScalar(layer.id ?? ''),
+      depends_on:
+        layer.depends_on !== undefined ? parseScalar(layer.depends_on) : null,
+      scope: layer.scope !== undefined ? parseInlineList(layer.scope) : [],
+      verify: layer.verify !== undefined ? parseScalar(layer.verify) : '',
+      commit: layer.commit !== undefined ? parseScalar(layer.commit) : '',
+    });
+  }
+
+  return core;
+}
+
+// Enforces the interview's rule (spec: "Authored cores") — a layer without
+// scope or without a verify command is rejected. Applied uniformly to
+// shipped and authored cores alike; the loader has no shipped-core-only
+// leniency.
+export function validateCore(core) {
+  if (!core.id) throw new Error('core definition missing top-level id');
+  if (!Array.isArray(core.layers) || core.layers.length === 0) {
+    throw new Error('core definition has no layers');
+  }
+  for (const layer of core.layers) {
+    if (!layer.id) throw new Error('layer missing id');
+    if (!layer.scope || layer.scope.length === 0) {
+      throw new Error(`layer "${layer.id}" missing scope`);
+    }
+    if (!layer.verify) {
+      throw new Error(`layer "${layer.id}" missing verify`);
+    }
+  }
+  return core;
+}
+
+export async function loadCore(path) {
+  const text = await readFile(path, 'utf8');
+  return validateCore(parseCoreYaml(text));
+}

package/src/db/friction.mjs

@@ -0,0 +1,25 @@
+// `hedgehog friction add`/`hedgehog friction list` — writes and reads the
+// `friction` table, replacing the file-based `.hedgehog/friction.md` log.
+// See hedgehog-persistent-build-graph.md, Schema, and
+// src/skills/hedgehog-loop/SKILL.md's Friction log section.
+
+const insertFriction = (db) =>
+  db.prepare(`
+    INSERT INTO friction (task_id, note)
+    VALUES (?, ?)
+  `);
+
+// Writes one friction row. `taskId` is optional (the schema's task_id is
+// nullable) — a reviewed-marker row (see tweaker.md) has no task_id.
+export function addFriction(db, { note, taskId }) {
+  if (!note) throw new Error('friction requires a note');
+  const result = insertFriction(db).run(taskId ?? null, note);
+  return { id: Number(result.lastInsertRowid), taskId: taskId ?? null, note };
+}
+
+// Returns every friction row, oldest first, for tweaker's review pass.
+export function listFriction(db) {
+  return db
+    .prepare(`SELECT id, task_id AS taskId, note, logged_at AS loggedAt FROM friction ORDER BY id ASC`)
+    .all();
+}

package/src/db/init.mjs

@@ -0,0 +1,35 @@
+// `hedgehog db init` — creates .hedgehog/hedgehog.db if absent, no-ops if
+// present. See hedgehog-persistent-build-graph.md, "The CLI is the only
+// writer".
+
+import { DatabaseSync } from 'node:sqlite';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { constants } from 'node:fs';
+import { access } from 'node:fs/promises';
+import { applySchema } from './schema.mjs';
+
+export const DB_PATH = '.hedgehog/hedgehog.db';
+
+const exists = (p) =>
+  access(p, constants.F_OK).then(
+    () => true,
+    () => false,
+  );
+
+// Returns { created: boolean, path } — created is false when the DB file
+// already existed (no-op per the spec).
+export async function dbInit(dbPath = DB_PATH) {
+  const already = await exists(dbPath);
+  await mkdir(dirname(dbPath), { recursive: true });
+
+  const db = new DatabaseSync(dbPath);
+  try {
+    db.exec('PRAGMA foreign_keys = ON;');
+    if (!already) applySchema(db);
+  } finally {
+    db.close();
+  }
+
+  return { created: !already, path: dbPath };
+}

package/src/db/intent.mjs

@@ -0,0 +1,101 @@
+// `hedgehog intent add` — writes one intent record (`intents` +
+// `requirements` + `intent_dependencies` rows) from either CLI flags or a
+// JSON file matching the intent record shape. See
+// hedgehog-persistent-build-graph.md, "Intent records".
+//
+// The primary human input is compact and outcome-oriented:
+//   { id, goal, outcome, rules: [...], depends_on: [...], priority }
+// `rules` become `requirements` rows with kind='rule'. `depends_on` become
+// `intent_dependencies` rows. Constraint/acceptance requirements aren't
+// part of the flag surface (no natural repeatable-flag shape for two
+// distinct kinds) but are accepted from a JSON file via `constraints` /
+// `acceptance` arrays, alongside `rules`.
+
+const REQUIREMENT_KIND_FIELDS = {
+  rule: 'rules',
+  constraint: 'constraints',
+  acceptance: 'acceptance',
+};
+
+function requirementId(intentId, kind, index) {
+  return `${intentId}-${kind}-${index + 1}`.toUpperCase();
+}
+
+// Normalizes either source (parsed JSON file, or flags already collected
+// into the same shape) into the exact rows to insert. Throws on missing
+// required fields — id/goal/outcome are NOT NULL in the schema.
+export function normalizeIntent(record) {
+  const { id, goal, outcome, priority, depends_on: dependsOn } = record;
+
+  if (!id) throw new Error('intent requires an id');
+  if (!goal) throw new Error('intent requires a goal');
+  if (!outcome) throw new Error('intent requires an outcome');
+
+  const requirements = [];
+  for (const [kind, field] of Object.entries(REQUIREMENT_KIND_FIELDS)) {
+    const statements = record[field] ?? [];
+    statements.forEach((statement, index) => {
+      requirements.push({ id: requirementId(id, kind, index), kind, statement });
+    });
+  }
+
+  const dependsOnIds = dependsOn ?? [];
+  if (dependsOnIds.includes(id)) {
+    throw new Error(`intent "${id}" cannot depend on itself`);
+  }
+
+  return {
+    id,
+    goal,
+    outcome,
+    priority: priority ?? 100,
+    requirements,
+    depends_on: dependsOnIds,
+  };
+}
+
+const insertIntent = (db) =>
+  db.prepare(`
+    INSERT INTO intents (id, goal, outcome, priority)
+    VALUES (?, ?, ?, ?)
+  `);
+
+const insertRequirement = (db) =>
+  db.prepare(`
+    INSERT INTO requirements (id, intent_id, kind, statement)
+    VALUES (?, ?, ?, ?)
+  `);
+
+const insertIntentDependency = (db) =>
+  db.prepare(`
+    INSERT INTO intent_dependencies (intent_id, depends_on_intent_id)
+    VALUES (?, ?)
+  `);
+
+// Writes a normalized intent (see normalizeIntent) to `db`: one `intents`
+// row, one `requirements` row per rule/constraint/acceptance item, one
+// `intent_dependencies` row per depends_on entry. All in one transaction.
+export function addIntent(db, record) {
+  const intent = normalizeIntent(record);
+
+  const runInsertIntent = insertIntent(db);
+  const runInsertRequirement = insertRequirement(db);
+  const runInsertDependency = insertIntentDependency(db);
+
+  db.exec('BEGIN');
+  try {
+    runInsertIntent.run(intent.id, intent.goal, intent.outcome, intent.priority);
+    for (const r of intent.requirements) {
+      runInsertRequirement.run(r.id, intent.id, r.kind, r.statement);
+    }
+    for (const dependsOnId of intent.depends_on) {
+      runInsertDependency.run(intent.id, dependsOnId);
+    }
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    throw err;
+  }
+
+  return intent;
+}