@really-knows-ai/foundry 2.3.2 → 3.0.0

package/dist/skills/human-appraise/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: human-appraise
+type: atomic
+description: Human quality gate. Presents the artefact to the human for review and collects feedback tagged `human`.
+---
+
+# Human Appraise
+
+You are a human quality gate. Sort has routed to you either because the LLM appraisers have finished (normal flow) or because a deadlock was detected between forge and appraisers.
+
+## Prerequisites
+
+Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+
+> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+
+## Stage lifecycle (mandatory)
+
+Human-appraise runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt.
+2. **Last:** `foundry_stage_end({summary})`.
+
+Human-appraise makes **no disk writes**. All output flows through `foundry_feedback_add` and `foundry_feedback_resolve`. `foundry_stage_end` flags unexpected writes as a violation.
+
+Human-appraise **cannot** call `foundry_feedback_action`, `foundry_feedback_wontfix`, or `foundry_artefacts_set_status` — the tools reject those calls during a human-appraise stage (action/wontfix are forge-only forward transitions; set-status requires no active stage). See "Feedback handling" below for the legal transitions available to human-appraise.
+
+## Input
+
+When invoked from orchestrate, you receive `{cycle, token, context}`:
+- `cycle` — the current cycle id
+- `token` — single-use token for `foundry_stage_begin`
+- `context.artefact_file` — the target artefact
+- `context.recent_feedback` — recent deadlocked feedback items to present to the user
+
+Your FIRST tool call must be `foundry_stage_begin({stage: 'human-appraise:<cycle>', cycle, token})`.
+
+Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence description of the user verdict>'})` — orchestrate reads this summary for the commit message.
+
+## Protocol
+
+1. `foundry_stage_begin(...)`.
+2. Gather context by calling:
+   - `foundry_workfile_get` — current state, goal, cycle
+
+     **Check for failed flow state.** If `foundry_workfile_get` returns `{status: "failed", reason: ...}`, STOP. Do not do any substantive work. Tell the user:
+
+     > The flow is in a failed state. Reason: `<reason>`.
+     >
+     > No further work is permitted. To recover:
+     >
+     >   1. `foundry_workfile_delete({confirm: true})` to abandon the cycle.
+     >   2. Back out to main (`git checkout main`) and delete the work branch.
+     >   3. Investigate and fix the root cause of the failure before restarting.
+
+     Then call `foundry_stage_end({summary: 'Flow is failed; no human appraisal performed'})`, return control to the user, and stop.
+   - `foundry_artefacts_list({cycle: <current-cycle>})` — this cycle's artefact files and status (always pass the `cycle` filter; omitting it returns stale rows from prior sessions)
+   - `foundry_feedback_list` — all existing feedback
+   - `foundry_history_list({cycle: <current-cycle>})` — what has happened so far
+
+3. Read the artefact file(s) for this cycle.
+
+4. Present to the human:
+   - The current artefact content (full file content or multi-file diff)
+   - A summary of this iteration's feedback (resolved and open)
+   - If this is a deadlock escalation, clearly explain the deadlock:
+     - Which feedback item(s) are stuck
+     - The appraiser's reasoning
+     - Forge's wont-fix or revision justification
+     - Ask the human to resolve the disagreement
+
+5. Wait for the human's response.
+
+6. Act on the response (tag MUST be `human` on any added feedback — the tool rejects other tags during human-appraise):
+   - **Approve** — "looks good" / "continue" — no feedback added, sort will advance.
+   - **Provide feedback** — `foundry_feedback_add({ file, text, tag: 'human' })`. Sort will route back to forge.
+   - **Resolve feedback** — `foundry_feedback_resolve({ id, resolution, reason? })` for items in `{actioned, wont-fix, deadlocked}`. See "Feedback handling" below for the legal transitions and authority rules.
+   - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the `foundry_artefacts_set_status` tool refuses calls during an active stage). To abort: end the stage with a summary explaining the abort, then either (a) instruct the user to call `foundry_workfile_delete({ confirm: true })` to discard the cycle, or (b) reject outstanding feedback so routing exhausts iterations and sort marks the artefact blocked on its own.
+
+7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
+
+## Feedback handling
+
+As a human-appraise stage, you can add human feedback and resolve feedback
+items (including deadlock overrides). **Human-appraise can resolve any
+non-resolved source-stage item regardless of source** — this is the
+universal override authority recorded in spec §5.1 rule 5. It is not
+limited to deadlocked items, though in practice most overrides today are
+on deadlocked items because default sort routing only surfaces deadlocked
+items to human-appraise (see §17 future-work note below).
+
+What human-appraise can NOT do:
+
+- **No forward transitions.** `foundry_feedback_action` and
+  `foundry_feedback_wontfix` move items from `{open, rejected}` to
+  `{actioned, wont-fix}` — that is forge's lane (spec §5.1 rule 1) and
+  the tools reject calls from any non-forge stage. If an open or rejected
+  item needs work, sort will route to forge after this stage ends.
+- **No artefact status writes.** `foundry_artefacts_set_status` requires
+  no active stage; it refuses calls while human-appraise is open. Status
+  promotion to `done`/`blocked` is owned by sort/orchestrate based on
+  routing.
+
+What human-appraise CAN do:
+
+1. **Add new human feedback.** Call `foundry_feedback_add` with
+   `{ file, text, tag: 'human' }`. The `source` is your stage id. The tool
+   returns `{ ok: true, id, deduped }`; `deduped: true` indicates an
+   existing non-resolved item with the same `(file, tag, hash(text))` was
+   found and no new snapshot was written, `deduped: false` indicates a new
+   item was created.
+
+2. **Resolve any non-resolved source-stage item.** For items in
+   `{actioned, wont-fix}` (sourced from quench, appraise, or
+   human-appraise), call `foundry_feedback_resolve` with
+   `{ id, resolution: 'approved' | 'rejected', reason? }`. Human-appraise
+   may resolve any such item regardless of source, including items from
+   other stage ids.
+
+3. **Resolve deadlocked items.** When items reach `state: deadlocked`
+   (written by sort when an item's history depth hits
+   `deadlock-iterations`), human-appraise is the ONLY stage authorised
+   to resolve them. Call `foundry_feedback_resolve` with
+   `{ id, resolution: 'approved' | 'rejected', reason: '...' }`.
+   `reason` is always required on deadlock override — it documents why
+   the deadlock is being broken. After human-appraise resolves every
+   deadlocked item, the cycle resumes normal forge/appraise routing. If
+   deadlocks remain after human-appraise, the cycle blocks (per spec §5.2).
+
+**Reason rules.** `reason` is required when rejecting feedback
+(`resolution: 'rejected'`) and when overriding a deadlocked item.
+Non-deadlocked approved resolution via
+`foundry_feedback_resolve({ id, resolution: 'approved', reason? })` may
+omit `reason`; deadlock override always requires `reason` to document why
+the deadlock is being broken.
+
+**Future work.** Spec §17 notes that a cycle-level mode flag letting
+human-appraise see all unresolved feedback (not just deadlocked items)
+before sort routes is planned for a future release. In v2.6.0 the
+authority is universal but reachability is limited — you typically only
+see deadlocked items on the route from sort. If you do see non-deadlocked
+items (e.g. you were invoked directly by the user), the same authority
+applies.
+
+## What you do NOT do
+
+- You do not write files — all output goes through foundry tools.
+- You do not make decisions for the human — present the state and wait.
+- You do not modify the artefact.
+- You do not skip the pause — the human must respond before continuing.
+- You do not filter or summarise away important details — show the full picture.
+- You do not call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` owns those (the tools are not registered publicly).
+- You do not register artefacts — handled by `foundry_stage_end({summary})`.

package/{skills → dist/skills}/init-foundry/SKILL.md

@@ -29,23 +29,35 @@ Set up the `foundry/` directory structure in the current project.
      appraisers/.gitkeep
    ```
 
-3. **Generate foundry agent files**
+3. **Update `.gitignore`**
+
+   Append `.snapshots/` to the project's `.gitignore` (creating the file if absent). This directory is where dry-run snapshots are written and must never be committed.
+
+   The plugin will idempotently append `.foundry/` itself on first boot, so you do not need to add that line.
+
+4. **Generate foundry agent files**
 
    Run the `refresh-agents` skill to generate `.opencode/agents/foundry-*.md` files for multi-model routing.
 
-4. **Commit the structure**
+5. **Commit the structure**
 
    ```bash
-   git add foundry/ .opencode/agents/foundry-*.md
+   git add foundry/ .gitignore .opencode/agents/foundry-*.md
    git commit -m "feat: initialize Foundry project structure"
    ```
 
-5. **Guide next steps**
+6. **Guide next steps**
 
    Tell the user:
 
    > Foundry is initialized. **Restart OpenCode** for the new foundry agents to take effect.
    >
+   > The first time the plugin boots in this project, it will create the
+   > `.foundry/` runtime directory (which holds the per-worktree HMAC key) and
+   > idempotently append `.foundry/` to your `.gitignore` so the secret never
+   > gets committed. The `.snapshots/` line was added by this skill to keep
+   > dry-run snapshots out of git.
+   >
    > Here's how to set up your first pipeline:
    >
    > 1. **Define an artefact type** — use the `add-artefact-type` skill
@@ -55,3 +67,10 @@ Set up the `foundry/` directory structure in the current project.
    > 5. **Create a flow** — use the `add-flow` skill
    >
    > Then run your flow with the `flow` skill.
+   >
+   > **Optional: Flow Memory**
+   >
+   > If your flows need persistent knowledge (entities, relationships, semantic
+   > search), use the `init-memory` skill to scaffold flow memory. Memory is
+   > useful for projects that need to track code structure, dependencies, or
+   > domain knowledge across flow runs.

package/dist/skills/init-memory/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: init-memory
+type: atomic
+description: Initialize flow memory by creating the foundry/memory/ and foundry-memory/ directory structures
+---
+
+# Initialize Flow Memory
+
+Scaffold `foundry/memory/` (config) and `foundry-memory/relations/` (row data)
+in the current project. `foundry/memory/` holds entity-type and edge-type
+definitions, the schema, the config, and the gitignored Cozo database.
+`foundry-memory/relations/` is a top-level sibling of `foundry/` that holds
+the committed NDJSON relations.
+
+## Prerequisites
+
+Before running this skill, verify all of the following:
+
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
+
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
+
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
+
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
+
+Neither `foundry/memory/` nor `foundry-memory/` may already exist.
+
+## Steps
+
+1. **Ask the user** whether to enable embeddings (semantic search).
+   - Default: **yes**, targeting a local Ollama instance
+     (`http://localhost:11434/v1`, `nomic-embed-text`, 768 dims).
+   - If the user declines, note it and pass `embeddings_enabled: false` in
+     step 2.
+
+2. **Invoke `foundry_memory_init`** with `{ embeddings_enabled, probe: true }`.
+
+   The tool deterministically:
+   - creates `foundry/memory/entities/` and `foundry/memory/edges/` with `.gitkeep`,
+   - creates `foundry-memory/relations/` (top-level sibling of `foundry/`) with `.gitkeep`,
+   - writes `foundry/memory/config.md` (frontmatter set from the embeddings choice),
+   - writes `foundry/memory/schema.json` (`embeddings: {...}` when enabled, `null` when not),
+   - appends the three `foundry/memory/memory.db*` entries to `.gitignore`
+     idempotently,
+   - probes the embedding provider (only when enabled) and returns the result.
+
+   It fails if either `foundry/memory/` or `foundry-memory/` already exists.
+
+3. **Handle the probe result** (field `probe` in the return value).
+   - `probe == null`: embeddings disabled, skip.
+   - `probe.ok == true`: display `✓ Embedding provider responded (dimensions: N)` 
+     where N is `probe.dimensions`, then continue.
+   - `probe.ok == false`: present the user with these options:
+     1. Install/start Ollama and `ollama pull nomic-embed-text`, then invoke
+        `foundry_memory_validate` to re-check.
+     2. Edit `foundry/memory/config.md` frontmatter to point at a different
+        OpenAI-compatible endpoint, then invoke `foundry_memory_validate`.
+     3. Set `embeddings.enabled: false` in `foundry/memory/config.md`.
+
+4. **Commit the scaffold**:
+
+   ```bash
+   git add foundry/memory/ foundry-memory/ .gitignore
+   git commit -m "feat: initialise flow memory"
+   ```
+
+5. **Tell the user what is next**:
+
+   > Flow memory is scaffolded. Next steps:
+   >
+   > - Use `add-memory-entity-type` to declare entity types (e.g. `class`,
+   >   `method`, `table`).
+   > - Use `add-memory-edge-type` to declare edge types (e.g. `calls`,
+   >   `writes`, `references`).

package/{skills → dist/skills}/orchestrate/SKILL.md

@@ -11,11 +11,25 @@ You drive a foundry cycle by calling `foundry_orchestrate` repeatedly and acting
 
 Before running this skill, verify that `foundry/` exists in the project root and `WORK.md` has been created by the flow skill (with `flow`, `cycle`, and `goal` fields). If not, stop and tell the user to run the flow skill first.
 
+### Check for failed flow state
+
+Before iterating, call `foundry_workfile_get` once. If it returns `{status: "failed", reason: ...}`, STOP. Do not call any other tool. Tell the user:
+
+> The flow is in a failed state. Reason: `<reason>`.
+>
+> No further work is permitted. To recover:
+>
+>   1. `foundry_workfile_delete({confirm: true})` to abandon the cycle.
+>   2. Back out to main (`git checkout main`) and delete the work branch.
+>   3. Investigate and fix the root cause of the failure before restarting.
+
+Then return control to the user and stop.
+
 ## Protocol
 
 Loop until `foundry_orchestrate` returns a terminal action (`done`, `blocked`, or `violation`):
 
-1. Call `foundry_orchestrate({lastResult})`. Omit `lastResult` on the first iteration. On subsequent iterations, pass `{kind, ok}` reflecting the previous action's outcome.
+1. Call `foundry_orchestrate({lastResult})`. Omit `lastResult` on the first iteration. On subsequent iterations, pass `{ok, error?}` reflecting the previous action's outcome.
 
 2. Switch on the returned `action`:
 
@@ -31,7 +45,7 @@ task tool:
   prompt: <prompt-from-payload — pass verbatim>
 ```
 
-When the task returns, call `foundry_orchestrate({lastResult: {kind: 'dispatch', ok: true}})`. If the task tool itself errored or reported a subagent crash, pass `{kind: 'dispatch', ok: false, error: '<message>'}`.
+When the task returns, call `foundry_orchestrate({lastResult: {ok: true}})`. If the task tool itself errored or reported a subagent crash, pass `{ok: false, error: '<message>'}`.
 
 ### `human_appraise`
 
@@ -39,7 +53,7 @@ Payload: `{stage, token, context}`.
 
 Invoke the `human-appraise` skill inline, passing `{cycle, token, context}`. The skill will prompt the user, collect feedback, and call `foundry_stage_end({summary})`.
 
-When it returns, call `foundry_orchestrate({lastResult: {kind: 'human_appraise', ok: true}})`.
+When it returns, call `foundry_orchestrate({lastResult: {ok: true}})`.
 
 ### `done`
 
@@ -65,5 +79,17 @@ Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<af
 
 - You do NOT inline forge / quench / appraise work. Always dispatch via `task`.
 - You do NOT mint, modify, or cache tokens. The `prompt` from orchestrate already contains the token verbatim.
-- You do NOT call `foundry_history_append`, `foundry_git_commit`, `foundry_stage_finalize`, or `foundry_sort`. These are not registered tools in v2.3+; orchestrate handles them internally.
+- `foundry_history_append`, `foundry_git_commit`, `foundry_stage_finalize`, and `foundry_sort` are not registered tools; orchestrate handles them internally via the loop.
 - You do NOT reorder the protocol. `foundry_orchestrate` returns, you act, you call back. Nothing else between.
+
+## Feedback visibility
+
+Orchestrate's loop does not read, parse, or write feedback directly.
+Subagents invoked via `dispatch` use the `foundry_feedback_list` /
+`foundry_feedback_add` / `foundry_feedback_action` / `foundry_feedback_wontfix`
+/ `foundry_feedback_resolve` tools themselves; orchestrate does not stage
+feedback state between iterations. If you want to inspect feedback state
+between iterations for diagnostic purposes, call `foundry_feedback_list` —
+the response shape is `[{ id, file, tag, text, source, state, depth,
+reason? }]`. This is read-only and does not affect the loop's dispatch
+decisions.

package/dist/skills/quench/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: quench
+type: atomic
+description: Deterministic validation of an artefact by running CLI commands. Writes feedback via foundry tools.
+---
+
+# Quench
+
+You run deterministic checks on an artefact by executing the CLI commands defined in the law-based validators for the artefact's type. No judgment — commands pass or fail.
+
+## Prerequisites
+
+Before running this skill, verify that the `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+
+> Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
+
+## Stage lifecycle (mandatory)
+
+Quench runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt. Any other tool call before this will be blocked.
+2. **Last:** `foundry_stage_end({summary})`.
+
+Quench makes **no disk writes**. You produce feedback via `foundry_feedback_add`, never by creating or modifying files. The orchestrator's internal finalize step (run after `stage_end`) will flag any unexpected writes as a violation.
+
+## Protocol
+
+1. `foundry_stage_begin(...)`.
+2. `foundry_workfile_get` — read the `cycle` from frontmatter.
+
+   **Check for failed flow state.** If `foundry_workfile_get` returns `{status: "failed", reason: ...}`, STOP. Do not call any other tool. Tell the user:
+
+   > The flow is in a failed state. Reason: `<reason>`.
+   >
+   > No further work is permitted. To recover:
+   >
+   >   1. `foundry_workfile_delete({confirm: true})` to abandon the cycle.
+   >   2. Back out to main (`git checkout main`) and delete the work branch.
+   >   3. Investigate and fix the root cause of the failure before restarting.
+
+   Then return control to the user and stop.
+3. `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate the artefacts produced by **this** cycle. Always pass the `cycle` filter; omitting it returns rows from prior sessions and validates stale files. Skip rows whose status is `done` or `blocked`.
+4. For each remaining row:
+    a. `foundry_validate_run({ typeId: '<type-id>' })` — executes all law-based validators for the artefact type. The tool returns `{ ok, validatorsRun, items, errors }`. `items` is the array of parsed feedback items; each entry carries `lawId`, `validatorId`, `file`, and `text` (plus optional `location` and `severity`). `errors` carries validator-level failures with `lawId`, `validatorId`, `type` (`parse` or `pattern-mismatch`), and `message`.
+   b. For each entry in `items`: call `foundry_feedback_add` with `{ file: item.file, text: item.text, tag: 'law:' + item.lawId + ':' + item.validatorId }`. The tag uses the law ID and validator ID returned by the tool so operators reading `WORK.feedback.yaml` can identify exactly which validator produced each item.
+   c. If `errors` is non-empty, the validators themselves misbehaved (malformed JSONL or files outside the artefact type's `file-patterns`). Report these to the user via `foundry_stage_end` summary; do not convert them to law-tagged feedback.
+5. Call `foundry_feedback_list`. For items whose `source` matches your stage id and whose state is `actioned` or `wont-fix`, use the validation results from step 4 to resolve them by id: approve when the relevant validation now passes or the deterministic issue is gone; reject with a reason when it still fails.
+6. If every command passes for every row, add no new feedback.
+7. If the artefact table has no rows for this cycle, `foundry_stage_end({summary: 'SKIP: no artefacts registered for this cycle'})` and stop.
+8. `foundry_stage_end({summary})`.
+
+## Feedback handling
+
+As a quench stage, you have two feedback responsibilities:
+
+1. **Adding new validation feedback.** For each entry returned in the `items`
+   array from `foundry_validate_run`, call `foundry_feedback_add` with
+   `{ file: item.file, text: item.text, tag: 'law:' + item.lawId + ':' + item.validatorId }`.
+   The `source` is automatically recorded as your stage id. Feedback tags must
+   follow the `law:<law-id>:<validator-id>` format to identify which law and
+   which validator on that law produced the feedback.
+
+   The tool returns `{ ok: true, id, deduped }` on success. `deduped: true`
+   means an existing non-resolved item with the same `(file, tag,
+   hash(text))` was found; the returned `id` is the existing item's id and
+   no new snapshot was written. `deduped: false` means a new item was
+   created. Either way, `id` is usable for follow-up calls.
+
+2. **Resolving items you sourced.** Call `foundry_feedback_list` to see items
+   whose `source` matches your stage id. For items whose current state is
+   `actioned` or `wont-fix`, use deterministic validation results to decide
+   whether the issue is gone:
+   - Validation now passes / issue is gone: call `foundry_feedback_resolve` with `{ id, resolution: 'approved' }`.
+     `reason` is optional here.
+   - Validation still fails / issue remains: call `foundry_feedback_resolve` with `{ id, resolution: 'rejected', reason: '...' }`.
+     `reason` is required on `rejected`. Forge will see the item back in
+     the `rejected` state on the next pass.
+
+**Reason rules.** `reason` is required when resolving a deadlocked item
+(deadlock override — but quench never does this; only human-appraise does),
+or when `resolution: 'rejected'`. On `resolution: 'approved'` for a
+non-deadlocked item, `reason` is optional.
+
+You cannot resolve items sourced by other stages, and you cannot touch
+deadlocked items (only human-appraise can override those).
+
+## History
+
+Do NOT call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` handles those (the tools are not registered publicly). Return a clear summary via `foundry_stage_end` (e.g., "2 validation issues found" or "Validation passed").
+
+## What you do NOT do
+
+- You do not write files — all output goes through `foundry_feedback_add`.
+- You do not make subjective judgments.
+- You do not revise the artefact (forge's job).
+- You do not evaluate laws — that is the appraise skill's job.
+- You do not invent validation rules — you only run commands from the law validators.
+- You do not duplicate feedback that already exists (the tool de-duplicates by text-hash, but don't rely on it).
+- You do not register artefacts — that happens automatically.

package/{skills → dist/skills}/refresh-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refresh-agents
-description: Use when initializing Foundry or after adding/removing providers to regenerate foundry-* agent files for multi-model routing.
+description: Use when initialising Foundry or after adding/removing providers to regenerate foundry-* agent files for multi-model routing.
 ---
 
 # Refresh Agents

package/dist/skills/rename-memory-edge-type/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: rename-memory-edge-type
+type: atomic
+description: Rename an edge type (does not touch row data)
+---
+
+# Rename Memory Edge Type
+
+## Prerequisites
+
+Before running this skill, verify all of the following:
+
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
+
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
+
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
+
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
+
+4. Memory is initialised. The `from` edge type must exist; the `to`
+   name must be free.
+
+## Steps
+
+1. Ask the user for `from` and `to`.
+2. Invoke `foundry_memory_rename_edge_type` with `{ from, to }`.
+3. Commit:
+
+   ```bash
+   git add -A foundry/memory/ foundry-memory/relations/
+   git commit -m "refactor(memory): rename edge type <from> -> <to>"
+   ```

package/dist/skills/rename-memory-entity-type/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: rename-memory-entity-type
+type: atomic
+description: Rename an entity type and migrate all referring edges and rows
+---
+
+# Rename Memory Entity Type
+
+## Prerequisites
+
+Before running this skill, verify all of the following:
+
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
+
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
+
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
+
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
+
+4. Memory is initialised. The `from` entity type must exist; the `to`
+   name must be free (no existing entity or edge).
+
+## Steps
+
+1. Ask the user for `from` and `to`.
+2. Warn the user: this rewrites committed NDJSON rows in every edge that references the entity. Preview the change with `foundry_memory_validate` if desired.
+3. Invoke `foundry_memory_rename_entity_type` with `{ from, to }`.
+4. Commit:
+
+   ```bash
+   git add -A foundry/memory/ foundry-memory/relations/
+   git commit -m "refactor(memory): rename entity type <from> -> <to>"
+   ```

package/dist/skills/reset-memory/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: reset-memory
+type: atomic
+description: Purge all memory data (entities and edges) while keeping type definitions
+---
+
+# Reset Memory
+
+**Destructive.** Empties every relation file and deletes the live `.db`. Type
+definitions are preserved.
+
+## Prerequisites
+
+Before running this skill, verify all of the following:
+
+1. The `foundry/` directory exists in the project root. If it does not
+   exist, stop and tell the user:
+
+   > Foundry is not initialized in this project. Run the
+   > `init-foundry` skill first to create the foundry/ directory
+   > structure.
+
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
+
+3. If the branch does not start with `config/`, instruct the user to
+   create one before continuing:
+
+   > Foundry configuration changes must be made on a config/* branch.
+   > From a clean main branch, call:
+   >
+   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
+   >
+   > Then re-run this skill.
+
+   If the user is on a `dry-run/*/*` branch, they must finish
+   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
+   before re-running this skill on the parent `config/*`.
+
+4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
+   if not).
+
+## Steps
+
+1. Warn the user of the scope.
+2. Require explicit confirmation.
+3. Invoke `foundry_memory_reset` with `{ confirm: true }`.
+4. Commit:
+
+   ```bash
+   git add foundry-memory/relations/ foundry/memory/schema.json
+   git commit -m "chore(memory): reset memory data"
+   ```