@really-knows-ai/foundry 2.3.1 → 3.0.0

package/dist/skills/assay/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: assay
+type: atomic
+description: Deterministic population of flow memory by running project-authored extractor scripts. Writes JSONL output into entities and edges via foundry tools.
+---
+
+# Assay
+
+Runs the `assay` stage of a cycle. An assay stage executes every extractor listed in the cycle's `assay.extractors` frontmatter, in order. Each extractor is a project-authored CLI script at the path given in its definition file — see the `foundry/memory/extractors/<name>.md` files for what each one does.
+
+The assay stage is **deterministic**. This skill does **not** interpret extractor output. It only calls `foundry_assay_run`, which handles spawning, parsing, validation, and memory upserts. On any failure (extractor non-zero exit, parse error, permission violation, timeout, or post-run memory sync failure), `foundry_assay_run` marks the workfile failed (`status: failed`) with a reason describing the failure, and returns `{error, flow_failed: true, ...}`. The cycle is over — extractor scripts live outside any artefact's `file-patterns`, so forge cannot fix them. The user must fix the extractor and start a new cycle. Your job is to wrap the lifecycle cleanly: end the stage with a descriptive summary even on failure, then stop.
+
+## Protocol
+
+You have been dispatched to run an assay stage. The dispatch prompt contains a stage identifier like `assay:<cycle>` and a token.
+
+Follow these steps exactly and in order.
+
+### 1. Begin the stage
+
+Call `foundry_stage_begin({ stage, cycle, token })` with the values from the dispatch prompt. If the result is not `{ok: true}`, stop and report the error — something is wrong with the token or an already-active stage.
+
+### 2. Read WORK.md to find the extractor list
+
+Call `foundry_workfile_get()`. Read `frontmatter.assay.extractors`. This is an ordered array of extractor names. If it is missing or empty, this is a routing bug — end the stage (step 5) with an error summary describing the missing extractor list.
+
+### 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. Run the extractors
+
+Call `foundry_assay_run({ cycle, extractors })` passing exactly those values. Do not modify the list. Do not split it into multiple calls. The tool returns one of:
+
+- `{ok: true, perExtractor: [{name, rowsUpserted, durationMs}, ...]}` — all extractors succeeded.
+- `{error, flow_failed: true, aborted: true, failedExtractor, reason, stderr, perExtractor: [...]}` — the run aborted on an extractor failure. The workfile is already marked failed; no further work is permitted until the user abandons the cycle.
+- `{error, flow_failed: true}` — post-run memory sync failed. Same recovery path: workfile is failed, user must abandon.
+- `{error: "..."}` (without `flow_failed`) — a precondition failed (not an active assay stage, etc.). This should not happen if step 1 succeeded; treat as an error and end the stage (step 5) with the error text as the summary.
+
+### 4. Prepare the summary
+
+Build a short summary string for `foundry_stage_end`. Examples:
+
+- On success: `"ran 2 extractors, upserted 47 rows in 1420ms"`.
+- On abort: `"aborted on extractor 'java-symbols': extractor exited with exit code 2"`.
+
+Do not add feedback items, do not call `foundry_feedback_add`. Assay stages cannot file feedback — extractor failure is recorded directly on the workfile (`status: failed`).
+
+### 5. End the stage
+
+Call `foundry_stage_end({ summary })` with the summary from step 4. Always end the stage, whether the run succeeded or aborted. The stage lifecycle must close cleanly so the orchestrator can commit.
+
+## What this skill must not do
+
+- **Must not** read or parse extractor output files itself.
+- **Must not** call any memory write tools (`foundry_memory_put`, `foundry_memory_relate`, etc.). All writes go through `foundry_assay_run`.
+- **Must not** invoke `foundry_feedback_add`. Assay stages cannot file feedback; extractor failure is signalled by the workfile's `status: failed` field.
+- **Must not** modify any artefact files. The assay stage writes only to flow memory.
+
+## If something unexpected happens
+
+If `foundry_assay_run` throws an unrelated error (e.g. `error: memory not enabled`), that is a programming error in the cycle configuration — not an expected extractor failure. Do not retry. End the stage with a summary quoting the error and stop.

package/dist/skills/change-embedding-model/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: change-embedding-model
+type: atomic
+description: Swap the embedding model for memory and re-embed all existing entities
+---
+
+# Change Embedding Model
+
+Update `foundry/memory/config.md` to target a new OpenAI-compatible endpoint / model
+and re-embed every existing entity.
+
+## 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 and enabled. The new provider is reachable
+   from this machine. Allow enough time and bandwidth to re-embed
+   (O(#entities) requests in batches).
+
+## Steps
+
+1. **Ask the user for**: `model`, `dimensions`, optionally new `baseURL`, `apiKey`.
+2. **Invoke `foundry_memory_change_embedding_model`** with `{ model, dimensions, baseURL?, apiKey? }`.
+   The tool probes the new provider, re-embeds every entity, rewrites
+   `schema.json`, and then updates `foundry/memory/config.md` frontmatter to
+   match. On probe or re-embed failure, nothing is written.
+3. **Verify** by invoking `foundry_memory_search` with a sample query.
+4. **Commit**:
+
+   ```bash
+   git add foundry/memory/config.md foundry/memory/schema.json foundry-memory/relations/
+   git commit -m "chore(memory): change embedding model to <model>"
+   ```

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

@@ -0,0 +1,54 @@
+---
+name: drop-memory-edge-type
+type: atomic
+description: Delete an edge type and all its rows
+---
+
+# Drop Memory Edge Type
+
+**Destructive.** Deletes all edges of this 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 (`foundry/memory/` exists; run `init-memory`
+   if not).
+
+## Steps
+
+1. Ask the user for the edge type name.
+2. Invoke `foundry_memory_drop_edge_type` with `{ name, confirm: false }` (or omit `confirm`). This returns `{ requiresConfirm: true, preview: { rows } }` — show the user the row count that will be deleted.
+3. Require explicit "yes, delete it" confirmation.
+4. Invoke `foundry_memory_drop_edge_type` again with `{ name, confirm: true }`.
+5. Commit:
+
+   ```bash
+   git add -A foundry/memory/ foundry-memory/relations/
+   git commit -m "refactor(memory): drop edge type <name>"
+   ```

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

@@ -0,0 +1,57 @@
+---
+name: drop-memory-entity-type
+type: atomic
+description: Delete an entity type; cascades to affected edges
+---
+
+# Drop Memory Entity Type
+
+**Destructive.** This deletes all rows of this type and strips or removes any
+edges that reference it.
+
+## 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. Ask the user for the type name.
+2. Invoke `foundry_memory_drop_entity_type` with `{ name, confirm: false }` (or omit `confirm`). This returns `{ requiresConfirm: true, preview: { entityRows, affectedEdges: [...] } }`. Show the user:
+   - `entityRows` — number of entities of this type that will be deleted.
+   - For each `affectedEdges` entry: `cascadeDrop` means the whole edge type disappears; `prune` means `rowsAffected` rows will be removed but the edge type survives.
+3. Require explicit "yes, delete it" confirmation.
+4. Invoke `foundry_memory_drop_entity_type` again with `{ name, confirm: true }`.
+5. Commit:
+
+   ```bash
+   git add -A foundry/memory/ foundry-memory/relations/
+   git commit -m "refactor(memory): drop entity type <name>"
+   ```

package/dist/skills/dry-run/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: dry-run
+type: atomic
+description: Trial-run a flow against in-progress config on a dry-run/<x>/<y> branch; finish writes a forensic snapshot and discards the branch.
+---
+
+# Dry-run
+
+You help the user trial in-progress config changes against a real flow,
+without merging the config or polluting the config branch's history.
+
+## When to use
+
+The user is on a `config/<x>` branch with edits in progress (a new law, a
+modified flow, a fresh appraiser, etc.) and wants to see how a flow
+behaves under those changes — without merging, and without leaving WORK
+files or memory rows behind on `config/<x>`.
+
+## Prerequisites
+
+1. Current branch is `config/<x>` (single segment, not nested).
+2. Working tree is clean.
+3. The flow id and a one-line description of the goal are known.
+
+If on `main`, edit on a `config/<x>` branch first:
+`foundry_git_branch({ kind: "config", description: "<short-name>" })`.
+
+## Protocol
+
+### 1. Branch into dry-run mode
+
+```text
+foundry_git_branch({
+  kind: "dry-run",
+  flowId: "<flow-id>",
+  description: "<dry-run-purpose-slug>"
+})
+```
+
+This creates `dry-run/<x>/<flow>-<purpose>` and truncates the trace
+file. From here every `foundry_*` tool call is logged to
+`.foundry/trace/<branch-slug>.jsonl`.
+
+### 2. Run the flow
+
+Use the `flow` skill (or call `foundry_orchestrate` directly) to drive
+the flow against the goal. Memory data writes go to `foundry-memory/`
+on this branch — they are discarded with the branch.
+
+If the flow needs config to be adjusted mid-run: stop, finish the
+dry-run (step 4), edit on `config/<x>`, then start a new dry-run.
+
+### 3. Inspect WORK during the run (optional)
+
+`foundry_workfile_get` and the read-only memory tools work as normal;
+they appear in the trace.
+
+### 4. Finish: snapshot + discard
+
+```text
+foundry_git_finish({
+  message: "<one-paragraph findings>",
+  confirm: true
+})
+```
+
+The tool:
+
+- writes `.snapshots/<run-id>/` on the parent `config/<x>` working
+  tree, containing `README.md`, `work/WORK*`, `diff.patch`, and
+  `trace.jsonl`;
+- force-deletes the dry-run branch (its commits become unreachable);
+- truncates `.foundry/trace/<branch-slug>.jsonl`.
+
+The user is now back on `config/<x>` with the snapshot on disk.
+Nothing is committed. The snapshot directory is gitignored.
+
+`baseBranch` is **not valid** for a dry-run finish — the parent is the
+config branch the dry-run was started from.
+
+### 5. Inspect the snapshot
+
+- `foundry_snapshot_list()` enumerates all snapshots.
+- `foundry_snapshot_show({ runId })` returns a structured summary.
+- The actual files at `.snapshots/<run-id>/` are flat — read directly
+  with `Read` or shell tools.
+
+If the snapshot reveals the config needs adjustment: edit on
+`config/<x>` (still on it after finish), then optionally re-enter
+dry-run mode for another run. Snapshots accumulate; prune them with
+`foundry_snapshot_delete` or `foundry_snapshot_prune`.
+
+### 6. Finish the config
+
+When ready, finish `config/<x>` to `main`:
+
+```text
+foundry_git_finish({
+  message: "<config description>",
+  baseBranch: "main",
+  confirm: true
+})
+```
+
+Snapshots are gitignored and stay in the local working tree; they do
+not merge with the config.
+
+## What you do NOT do
+
+- You do not run schema-mutation tools while on a dry-run branch.
+  `foundry_config_create_*` and the memory-schema tools refuse there
+  by design.
+- You do not nest dry-runs (deeper nesting under `dry-run/` is refused).
+- You do not commit the snapshot directory by hand. If a particular
+  snapshot must be preserved beyond the local checkout, copy it out
+  first, then delete the original via `foundry_snapshot_delete`.

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

@@ -9,6 +9,8 @@ composes: [orchestrate]
 
 A foundry flow reads a flow definition, creates a work branch, and executes cycles by following the dependency graph — each cycle declares its own targets and input contracts.
 
+**Testing uncommitted config changes:** If you are on a `config/<x>` branch with in-progress edits to artefact types, laws, cycles, or flows and want to trial-run a flow against those changes without committing them, use the `dry-run` skill instead. Dry-run creates an isolated `dry-run/<x>/<y>` branch, runs the flow, captures a forensic snapshot, and discards the branch — leaving your config branch clean.
+
 ## 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:
@@ -18,7 +20,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 ## Starting a flow
 
 1. Call `foundry_config_flow` with the flow ID — get the flow definition
-2. Call `foundry_git_branch` with the flow ID and a short description — create the work branch
+2. Call `foundry_git_branch` with `kind: "work"`, the flow ID, and a short description — create the work branch (e.g. `foundry_git_branch({ kind: "work", flowId, description })`)
 3. Determine the starting cycle:
    - Any cycle listed in the flow can be the starting cycle. The flow's `starting-cycles` list is a hint for when the user's request is ambiguous.
    - Map the user's goal to a cycle by matching the requested output (e.g. "write a short story from the tennis haiku" → `create-short-story`; "write a haiku" → `create-haiku`).
@@ -31,6 +33,17 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
       - **Resume** — keep the existing workfile and skip to step 6. **Only offer resume if the existing `flow` AND `cycle` match what the user just asked for.** If either differs, do not offer resume — running the wrong cycle against stale state corrupts the workflow.
       - **Discard** — call `foundry_workfile_delete`, then proceed to step 5.
       - **Abort** — stop the skill without modifying anything.
+   d. 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.
 5. Call `foundry_workfile_create` with **only** the flow ID, chosen cycle ID, and goal — do **not** pass `stages` or `maxIterations`. The `orchestrate` skill will read the cycle definition and handle setup on its first call.
 6. Execute the cycle by invoking the orchestrate skill
 
@@ -61,7 +74,7 @@ When all desired cycles are done:
 
 1. Present a summary of what was produced (all artefacts and their status)
 2. Ask the user how they want to finish:
-   - **Squash merge** — call `foundry_git_finish` with a commit message and base branch
+   - **Squash merge** — call `foundry_git_finish` with a commit message and base branch. The flow skill always lands on `work/<flow>-<desc>`, so the tool dispatches to its `work` mode. **Audit-aware**: commits `WORK.*` cleanup on the work branch, preserves the branch as `archive/work/<flow>-<desc>-<hash>` for immutable forensic history, squash-merges to the base branch, and creates a signed commit embedding the canonical Foundry attestation block. Requires `confirm: true` (without it returns a plan); refuses dirty worktrees; on merge conflict aborts and preserves the work branch. (`foundry_git_finish` self-classifies by current branch — `config/<x>` finishes integrate without WORK cleanup, and `dry-run/<x>/<y>` finishes write a snapshot. The flow skill exits on `work/<x>`, so only the `work`-mode behaviour applies here.)
    - **Keep the branch** — leave as-is for manual handling
    - **Create a PR** — push and create a pull request
 3. Execute the chosen option

package/dist/skills/forge/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: forge
+type: atomic
+description: Produces or revises an artefact, guided by WORK.md and the foundry cycle definition.
+---
+
+# Forge
+
+You produce or revise artefacts. You read the work file to understand the goal, call `foundry_feedback_list` to understand feedback, and read the foundry cycle definition to understand what you're producing and what inputs you can read.
+
+## 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)
+
+Forge runs inside an enforced stage. Your **first** and **last** tool calls are fixed:
+
+1. **First:** `foundry_stage_begin({stage, cycle, token})` — the orchestrator hands you `stage`, `cycle`, and an opaque `token` string in the dispatch prompt. Copy the token verbatim; never invent, edit, or re-sign it. No other tool call is permitted before this one. Any writes before `stage_begin` will be blocked by preconditions.
+2. **Last:** `foundry_stage_end({summary})` — return control to the orchestrator. After `stage_end`, the orchestrator's internal finalize step scans the disk and registers your output artefact. **You do not register artefacts yourself.**
+
+## Protocol
+
+### First generation (no artefact registered yet)
+
+1. `foundry_stage_begin(...)` with the token from the dispatch prompt.
+2. `foundry_workfile_get` — understand the goal.
+
+   **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_config_cycle` — understand what to produce and what inputs are available.
+4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, especially its `file-patterns`.
+5. `foundry_config_laws` — get all applicable laws (global + type-specific).
+6. If the cycle declares `inputs`, discover input files by filesystem scan:
+   - For each type listed in `inputs`, call `foundry_config_artefact_type` to get its `file-patterns`.
+   - Glob the working tree against those patterns to enumerate candidate input files.
+   - Read the goal (from `foundry_workfile_get`) and select the files that are relevant to this run. If the goal names specific files or slugs, use those; if it describes a category ("all the auth tests"), select the matching subset; if it's open-ended, you may consume all candidates or ask the user when the set is clearly ambiguous.
+   - Read the selected files for context.
+7. Produce the artefact, respecting all applicable laws from the start.
+8. Write the artefact file to a location that matches the artefact type's `file-patterns`.
+9. `foundry_stage_end({summary})`.
+
+### Revision (feedback exists)
+
+1. `foundry_stage_begin(...)`.
+2. `foundry_feedback_list` — find feedback whose state is `open` or `rejected` for the current cycle.
+3. Read the artefact file.
+4. If the cycle declares `inputs`, discover them via filesystem scan against each input type's `file-patterns` (same protocol as first-generation step 6). Re-read the relevant files — they may have changed on disk since the previous iteration (nothing in this cycle wrote to them, but the user may have modified them between iterations).
+5. For each item whose state is `open` or `rejected`, follow the feedback handling rules below.
+6. Update the artefact file.
+7. `foundry_stage_end({summary})`.
+
+## Feedback handling
+
+Call `foundry_feedback_list` to see feedback items for the current cycle.
+Each entry has shape `{ id, file, tag, text, source, state, depth, reason? }`.
+Action every item whose `state` is `open` or `rejected`:
+
+- If you address the feedback in the artefact: call `foundry_feedback_action`
+  with `{ id }`. This marks the item `actioned`. The tool returns
+  `{ ok: true }` on success; keep using the original list entry's `id` for
+  any follow-up.
+- If you decide not to address the feedback: call `foundry_feedback_wontfix`
+  with `{ id, reason }`. The reason is required. **You may only mark
+  `wont-fix` on items whose `source` stage base is `appraise`.** If the
+  item's source base is `quench` (objective validation failure) or
+  `human-appraise` (direct user instruction), you must action it — the
+  tool will return an error if you attempt `wont-fix`. This replaces the
+  old tag-based restriction (`#validation`/`#human` tag check); tags are
+  now categorical/display-only and not consulted by the state machine.
+
+`foundry_feedback_add` (if you ever call it — forge normally does not)
+returns `{ ok, id, deduped }`. `deduped: true` means an existing
+non-resolved item with the same `(file, tag, hash(text))` was found and no
+new item was written; the returned `id` is the existing item's id.
+`deduped: false` means a new item was created.
+
+You cannot resolve or reject items — only the stage that created the item
+(the `source` on each list entry) can do that, with the exception that
+human-appraise can override any non-resolved item. You also cannot action
+items whose state is `actioned`, `wont-fix`, `deadlocked`, or `resolved`.
+
+## Write invariant
+
+Forge may only write to:
+- Files matching the output artefact type's `file-patterns`.
+- `WORK.md`, `WORK.feedback.yaml`, and `WORK.history.yaml` (tool-managed).
+
+Everything else on disk — including files of the cycle's input types, files of unrelated artefact types, and files outside any artefact type — is read-only for this stage. This rule is tool-enforced: the orchestrator's internal finalize step returns `{error: 'unexpected_files'}` and the orchestrator's modified-file check routes a violation on the next call. Either outcome marks the cycle's target artefact `blocked` and you do not get a retry.
+
+When a cycle's output type overlaps with one of its input types (e.g. a `refine-haiku` cycle with input `haiku` and output `haiku`), the overlap is intentional: the cycle's job is to modify existing files of that type. The write invariant still holds — you may only touch files matching the output type's patterns, which in this case includes the files you read as inputs.
+
+## Resolution vocabulary
+
+An item is **unresolved** if its `history[0].state` is one of `open`,
+`rejected`, `actioned`, `wont-fix`, or `deadlocked`. An item is
+**resolved** only when `history[0].state === 'resolved'` (terminal).
+Forge only acts on `open` and `rejected` items; it never sees `resolved`
+items in the list output.
+
+## What you do NOT do
+
+- You normally do not add feedback — that is the quench and appraise skills' job.
+- You do not `foundry_feedback_resolve` — that belongs to quench/appraise/human-appraise.
+- You do not register artefacts — the orchestrator's internal finalize step handles that automatically.
+- You do not call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` does (those tools are not registered publicly).
+- You do not evaluate or score the artefact.
+- You do not mark feedback as actioned unless you actually changed the artefact to address it.
+- You do not wont-fix items whose `source` stage base is `quench` or `human-appraise`.
+- You do not write to any file outside the output artefact type's `file-patterns` (plus `WORK.md` / `WORK.feedback.yaml` / `WORK.history.yaml`). Input files are read-only unless the output type's patterns happen to cover them.