@really-knows-ai/foundry 2.3.2 → 3.0.1

package/dist/skills/add-extractor/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: add-extractor
+type: atomic
+description: Create a new extractor definition under foundry/memory/extractors/. An extractor is a project-authored CLI that emits JSONL describing entities and edges to upsert into flow memory.
+---
+
+# Add Extractor
+
+Use this skill to register a new extractor — a script that reads the codebase (via `tree-sitter`, `javap`, language servers, or whatever suits the project) and emits line-delimited JSON describing entities and edges to upsert into flow memory during an `assay` stage.
+
+## 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. `foundry/memory/config.md` exists and has `enabled: true` (run
+   `init-memory` first if not). Every entity type the extractor will
+   populate must already be declared in `foundry/memory/entities/`
+   (use `add-memory-entity-type` to create any that are missing).
+
+## Steps
+
+### 1. Gather inputs
+
+Ask the user for, in this order (one question at a time):
+
+1. **Extractor name.** Lowercase kebab-case (`java-symbols`, `python-classes`, `tree-sitter-rust`). This becomes the filename under `foundry/memory/extractors/<name>.md` and the identifier referenced from cycle frontmatter.
+2. **Command.** The path to the executable (relative to the repo root, e.g. `scripts/extract-java-symbols.sh`) or a short shell command. This is passed to `/bin/sh -c` at runtime.
+3. **Entity types to populate (`memoryWrite`).** A list of entity type names already declared in this project's memory vocabulary. Validate against what exists; if the user names a type that doesn't exist, either offer to create it via `add-memory-entity-type` first or ask them to adjust.
+4. **Timeout** (optional). Duration string like `30s`, `2m`, or a number of milliseconds. Defaults to 60 seconds if omitted.
+5. **Brief description.** 1–3 paragraphs of prose describing what this extractor extracts, what it requires on `PATH`, and any re-run triggers. This body is injected into the forge prompt of every cycle that uses this extractor, so clarity here translates to better downstream generation.
+
+**Security note:** Remind the user that extractors inherit the agent's full environment, including any API tokens or credentials. Extractors should keep environment variable handling internal to extraction logic.
+
+### 2. Propose and confirm
+
+Summarise the proposed extractor back to the user and ask for confirmation before writing. Example:
+
+> I'll create `foundry/memory/extractors/java-symbols.md` with:
+> - command: `scripts/extract-java-symbols.sh`
+> - memoryWrite: [class, method]
+> - timeout: 60s (default)
+> - brief: "Walks the Java source tree with tree-sitter-java…"
+>
+> OK to proceed?
+
+### 3. Create the extractor file
+
+Call `foundry_extractor_create({ name, command, memoryWrite, body, timeout? })`. On error, surface the error to the user and stop — do not attempt to recover silently.
+
+### 4. Offer to scaffold the command script
+
+If the user confirms, create the script file at the `command` path with an executable permission. Provide a starter stub that documents the JSONL contract and a minimal example. For example, for `scripts/extract-java-symbols.sh`:
+
+```bash
+#!/bin/sh
+# Emits JSONL describing Java classes and methods.
+#
+# JSONL Contract (one JSON object per line):
+#   - One JSON object per line (JSONL/NDJSON format)
+#   - Pretty-printed multi-line JSON is NOT supported
+#   - Blank lines and lines starting with '#' are ignored
+#   - Each object discriminated by "kind":
+#
+#   Entities: {"kind":"entity","type":"<entity-type>","name":"<id>","value":"<string ≤ 4KB>"}
+#   Edges:    {"kind":"edge","from":{"type":..,"name":..},"edge":"<edge-type>","to":{"type":..,"name":..}}
+#
+# Exit 0 on success, non-zero on failure (aborts the assay stage).
+#
+# Environment: This script inherits the agent's full environment, including
+# any API tokens. Keep environment variable handling internal.
+
+set -euo pipefail
+
+# TODO: replace this stub with tree-sitter/javap/etc. invocations.
+echo '{"kind":"entity","type":"class","name":"example.Foo","value":"Example class, replace me."}'
+```
+
+Make the script executable (`chmod +x <path>`). Do **not** run the script — validation is the author's responsibility.
+
+### 5. Commit
+
+Commit both the definition and (if created) the stub script:
+
+```bash
+git add foundry/memory/extractors/<name>.md scripts/<command>
+git commit -m "feat(memory): add '<name>' extractor"
+```
+
+### 6. Guide the user on wiring it in
+
+After creation, tell the user how to opt a cycle into this extractor:
+
+> To use this extractor, add the following to the cycle's frontmatter:
+>
+> ```yaml
+> memory:
+>   write: [<each type in memoryWrite>]   # must include every type the extractor writes
+> assay:
+>   extractors: [<this extractor's name>]
+> ```
+>
+> Then run the `flow` or `orchestrate` skill. On the first iteration of the cycle, the assay stage will execute this extractor before forge.
+
+## What this skill must not do
+
+- **Must not** run the extractor script itself to verify it works. That is the author's job.
+- **Must not** modify cycle definitions. Opting a cycle into the extractor is an explicit editorial step for the user to take.
+- **Must not** create entity or edge types that don't already exist. Compose into `add-memory-entity-type` / `add-memory-edge-type` for any missing vocabulary.

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

@@ -10,15 +10,32 @@ You help the user create a new foundry flow. A foundry flow is a set of foundry
 
 ## Prerequisites
 
-Before running this skill, verify both of the following:
+Before running this skill, verify all three of the following:
 
-1. The `foundry/` directory exists in the project root. If it does not exist, stop and tell the user:
+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.
+   > 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 not a work branch. Run `git rev-parse --abbrev-ref HEAD` — if it starts with `work/`, stop and tell the user:
+2. The current git branch is a `config/*` branch. Run
+   `git rev-parse --abbrev-ref HEAD` and confirm it matches
+   `config/<description>`.
 
-   > You're on a work branch (`<branch>`). Foundry configuration changes must be made on the base branch (usually `main`). Complete or discard the in-flight flow (`foundry_git_finish`, or switch branches and delete it), then re-run this skill from the base branch.
+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/*`.
 
 ## Protocol
 
@@ -83,16 +100,25 @@ The `starting-cycles` field lists entry points. `## Cycles` lists all cycles in
 
 Ask: does this capture the flow correctly?
 
-### 6. Write the file
+### 6. Validate the draft
+
+Call `foundry_config_validate_flow({ name: "<id>", body: "<full markdown>" })`.
+
+If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+
+### 7. Create the file
+
+Call `foundry_config_create_flow({ name: "<id>", body: "<full markdown>" })`. The tool:
 
-Create `foundry/flows/<id>.md` with the agreed definition.
+- re-validates the body (TOCTOU);
+- writes `foundry/flows/<id>.md`;
+- produces one git commit on the current `config/*` branch.
 
-### 7. Confirm
+If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_flow` does not support updates.
 
-Show the user the created file and its contents.
+Show the user the resulting commit hash from the response.
 
 ## What you do NOT do
 
 - You do not create foundry cycles — that is a separate skill
-- You do not write files without showing the user first
 - You do not skip dependency validation

package/dist/skills/add-law/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: add-law
+type: atomic
+description: Creates a new law, checking for conflicts with existing laws.
+---
+
+# Add Law
+
+You help the user create a new law. You ensure it's well-scoped, doesn't conflict with existing laws, and ends up in the right file.
+
+## Prerequisites
+
+Before running this skill, verify all three 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/*`.
+
+## Protocol
+
+### 1. Determine scope
+
+If the user specifies where the law applies:
+- "global law" → goes in `foundry/laws/` (ask which file, or create a new one)
+- "law for X artefacts" → goes in `foundry/artefacts/<type>/laws.md`
+
+If the user doesn't specify, ask:
+
+> Should this law apply globally to all artefact types, or to a specific type?
+
+If they name a type, verify it exists in `foundry/artefacts/`. If it doesn't, tell them and ask if they want to create the artefact type first.
+
+### 2. Draft the law
+
+Write the law following the standard format:
+
+```markdown
+## <law-id>
+
+<What this law checks — one or two sentences.>
+
+validators:
+  - id: validator-id
+    command: ./script.sh
+    failure-means: (optional description)
+```
+
+The `law-id` (heading) should be:
+- Lowercase, hyphenated
+- Short but descriptive
+- Unique across all laws (global and type-specific)
+
+The `validators:` block is optional. Include it only if you want to add validation commands for this law.
+
+### 3. Check for conflicts
+
+Read all existing laws that would apply to the same artefact types:
+- All files in `foundry/laws/` (global)
+- `foundry/artefacts/<type>/laws.md` if the law is type-specific
+- If the law is global, also read all `foundry/artefacts/*/laws.md` since a global law applies everywhere
+
+For each existing law, check:
+- Does the new law contradict an existing law? (e.g., "must be formal" vs "must be conversational")
+- Does the new law duplicate an existing law? (same criterion, different wording)
+- Does the new law overlap with an existing law? (partially covers the same ground)
+
+If any conflict is found, present it to the user:
+
+> The new law `<new-id>` may conflict with existing law `<existing-id>`:
+> - New: <summary of new law>
+> - Existing: <summary of existing law>
+> - Conflict: <what the conflict is>
+>
+> Options:
+> 1. Proceed anyway (both laws will apply)
+> 2. Replace the existing law with the new one
+> 3. Rephrase the new law to avoid the conflict
+> 4. Cancel
+
+### 4. Refine with the user
+
+Present the drafted law to the user before writing it. Ask:
+
+> Here's the draft law:
+>
+> ## <law-id>
+>
+> <law content>
+>
+> Does this capture what you want, or should we adjust the wording?
+
+Iterate until the user is happy.
+
+### 5. Validate the draft
+
+Call `foundry_config_validate_law({ name: "<file-name-without-extension>", body: "<full markdown>" })`.
+
+If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types that don't exist yet.
+
+### 6. Create the file
+
+Pick the target. The user has already chosen scope in step 1 — translate that into the `target` argument:
+
+- Global → `target: { kind: "global", file: "<file-name>.md" }` (lives at `foundry/laws/<file-name>.md`).
+- Type-specific → `target: { kind: "type-specific", typeId: "<artefact-type>" }` (lives at `foundry/artefacts/<typeId>/laws.md`).
+
+Then call:
+
+```
+foundry_config_add_law({
+  name: "<file-name-without-extension>",
+  body: "<full markdown>",
+  target: { kind: "global", file: "<file-name>.md" }   // OR
+           { kind: "type-specific", typeId: "<artefact-type>" }
+})
+```
+
+The tool:
+
+- re-validates the body (TOCTOU);
+- writes the law file at the path determined by `target`;
+- produces one git commit on the current `config/*` branch.
+
+If the tool returns `{ ok: false, errors }` because the target file already exists, use `foundry_config_edit_law({ id: "<law-id>", body: "<updated-body>" })` to modify the law.
+
+Show the user the resulting commit hash from the response.
+
+### 7. Verify uniqueness
+
+After the file is created, confirm the law id is unique across all law files. If a collision exists, ask the user to rename and edit by hand on this branch.
+
+### 8. Editing existing laws (prose or validators)
+
+When the user wants to modify an existing law — whether updating the prose description or adding/changing validators — use this flow:
+
+#### 8a. Read the existing law
+
+Call `foundry_config_read_law({ id: "<law-id>" })` to fetch the full markdown content.
+
+#### 8b. Refine with the user
+
+Show the current content and ask what should change. Iterate on the updated markdown until the user is satisfied.
+
+#### 8c. Drift mitigation: Prose changes
+
+**If the user is modifying the law's prose description**, insert this prompt before updating:
+
+> 🔍 **Drift check:** Verify that all existing validators on this law still accurately enforce the updated intent. Open each validator's command and confirm it catches the same class of failure the prose now describes.
+
+Then proceed with the update.
+
+#### 8d. Drift mitigation: Validator changes
+
+**If the user is adding or modifying a validator**, insert this prompt before updating:
+
+> 🔍 **Drift check:** Verify that the changed validator still aligns with the law's prose. If the validator has narrowed or broadened, the prose may need a corresponding update.
+
+Then proceed with the update.
+
+#### 8e. Apply the update
+
+Call `foundry_config_edit_law({ id: "<law-id>", body: "<updated-markdown>" })` with the full updated body (prose and validators combined).
+
+Validate the result. If the tool returns `{ ok: true }`, show the user the commit hash. If it returns `{ ok: false, errors }`, address each error and retry.
+
+## What you do NOT do
+
+- You do not skip the conflict check
+- You do not silently overwrite existing laws
+- You do not create artefact types — that is a separate skill

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

@@ -0,0 +1,52 @@
+---
+name: add-memory-edge-type
+type: atomic
+description: Create a new edge type between entity types in flow memory
+---
+
+# Add 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 (`foundry/memory/` exists; run `init-memory`
+   if not). Entity types referenced in `sources` and `targets` must
+   already exist (or be added first).
+
+## Steps
+
+1. **Ask the user for**: edge name (snake_case), `sources` (list of entity types or `any`), `targets` (list of entity types or `any`), and a prose body describing what the edge represents.
+2. **Push back on narrow wording**. A good edge description describes WHEN the edge holds and what it does NOT cover (boundary with related edges).
+3. **Invoke `foundry_memory_create_edge_type`** with `{ name, sources, targets, body }`.
+4. **Commit**:
+
+   ```bash
+   git add foundry/memory/edges/<name>.md foundry/memory/schema.json
+   git commit -m "feat(memory): add edge type <name>"
+   ```

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

@@ -0,0 +1,74 @@
+---
+name: add-memory-entity-type
+type: atomic
+description: Create a new entity type in flow memory, with a prose brief for the LLM
+---
+
+# Add Memory Entity Type
+
+Declare a new entity type. The prose body becomes part of every cycle's prompt and
+decides what the LLM writes into memory.
+
+## 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** (lowercase snake_case, e.g. `class`, `stored_proc`).
+2. **Propose a prose body template** for the user to edit. Sections required: Name (naming convention for this type), Value (what goes in the value field, must state that relationships belong in edges), Relationships (informational list of likely edges). Example:
+
+   ```markdown
+   # <type>
+
+   Short description of what this entity represents in the subject system.
+
+   ## Name
+   Convention for how `name` is formed. Be specific enough to guarantee uniqueness.
+
+   ## Value
+   Describe what the `value` string should contain: intrinsic characteristics of
+   the entity only. Relationships to other entities belong in edges, not here.
+
+   ## Relationships
+   - `<edge>` to `<type>`: brief semantic note
+   ```
+
+3. **Confirm the body with the user.** Short bodies (≤100 chars) are a red flag; push back.
+4. **Create the type** by invoking `foundry_memory_create_entity_type` with `{ name, body }`. The tool rejects duplicate names (entity or edge) — surface the error to the user if it fires and stop.
+5. **Commit**:
+
+   ```bash
+   git add foundry/memory/entities/<name>.md foundry/memory/schema.json
+   git commit -m "feat(memory): add entity type <name>"
+   ```
+
+6. **Guidance to the user**: suggest they also add relevant edge types using `add-memory-edge-type`.

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

@@ -21,13 +21,25 @@ Appraise runs inside an enforced stage. Your **first** and **last** tool calls a
 1. **First:** `foundry_stage_begin({stage, cycle, token})` — copy the token verbatim from the dispatch prompt.
 2. **Last:** `foundry_stage_end({summary})`.
 
-Appraise makes **no disk writes**. All output flows through `foundry_feedback_add`. `foundry_stage_finalize` flags any unexpected writes as a violation.
+Appraise makes **no disk writes**. Feedback output flows through `foundry_feedback_add` and `foundry_feedback_resolve`. The orchestrator's internal finalize step flags any unexpected writes as a violation.
 
 ## Protocol
 
 1. `foundry_stage_begin(...)`.
 2. Gather context:
    - `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.
    - `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate this cycle's artefacts. Always pass the `cycle` filter; omitting it returns stale rows from prior sessions. Skip rows whose status is `done` or `blocked`.
    - For each remaining row, gather its type-specific context:
      - `foundry_config_laws` with the row's type — applicable laws (global + type-specific)
@@ -43,19 +55,52 @@ Appraise makes **no disk writes**. All output flows through `foundry_feedback_ad
    - De-duplicate: merge overlapping observations into a single feedback item
    - Preserve which appraiser(s) raised each issue (for traceability)
 
-6. For each consolidated issue: `foundry_feedback_add(file, text, tag: 'law:<law-id>')`. Tag MUST start with `law:` — the tool rejects other tags during appraise. The tool also de-duplicates by text-hash.
+6. For each consolidated issue: `foundry_feedback_add` with `{ file, text, tag: 'law:<slug>' }`. Tags must match `law:<slug>`, and dedup uses the non-resolved `(file, tag, hash(text))` semantics described in Feedback handling.
 
 7. If no appraiser found any issues, the artefact clears appraisal.
 
 8. `foundry_stage_end({summary})`.
 
-## Reviewing actioned and wont-fix feedback
-
-On subsequent passes, review previously actioned and wont-fix items:
-
-1. `foundry_feedback_list` — find `actioned` and `wont-fix` items for this artefact.
-2. Appraiser sub-agents evaluate whether the change addresses the issue (`actioned`) or the justification is sound (`wont-fix`).
-3. `foundry_feedback_resolve(file, index, resolution: 'approved'|'rejected', reason?)`. Appraise is the only stage (other than human-appraise) allowed to resolve `wont-fix` items.
+## Feedback handling
+
+As an appraise stage, you have two feedback responsibilities:
+
+1. **Adding new law-violation feedback.** For each unmet law, call
+   `foundry_feedback_add` with `{ file, text, tag: 'law:<slug>' }`.
+   The `source` is automatically your stage id (e.g. `appraise:write-check`).
+   The tool rejects any tag not matching `law:<slug>` during an appraise
+   stage; do not attempt bare `'appraise'` or `'review'` tags.
+
+   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 (no new snapshot written); `deduped: false`
+   means a new item was created. Resolved items are NOT considered for
+   dedup — a re-added item after a resolution is a legitimate new item
+   (regression feedback).
+
+2. **Resolving items you sourced.** Call `foundry_feedback_list` and look
+   at items whose `source` exactly matches your stage id. For items whose
+   current state is `actioned` or `wont-fix`:
+   - Approve: `foundry_feedback_resolve` with `{ id, resolution: 'approved' }`.
+     `reason` is optional.
+   - Reject: `foundry_feedback_resolve` with `{ id, resolution: 'rejected', reason: '...' }`.
+     `reason` is required. A rejection sends the item back to forge for
+     another attempt (the `rejected` state is a legal forge input per
+     §5.1 rule 2).
+
+**Reason rules.** `reason` is required on `resolution: 'rejected'` and on
+any deadlock-override transition. On `resolution: 'approved'` for a
+non-deadlocked item, `reason` is optional.
+
+**Source-authorship rule.** You can only resolve/reject items whose `source`
+matches your own stage id — not every appraise stage in the cycle, just yours.
+This prevents a second appraise stage from rubber-stamping work it didn't
+request. For deadlocked items, only human-appraise has the override authority.
+
+**Future work.** Spec §17 notes a planned cycle-level mode that would let
+human-appraise see non-deadlocked unresolved feedback before the orchestrator routes.
+Not available in v2.6.0; appraise stages today are the sole resolver of
+their own non-deadlocked items.
 
 ## Dispatch
 
@@ -67,11 +112,15 @@ Each appraiser is dispatched as an independent sub-agent. The sub-agent receives
 
 ### Model resolution
 
-`foundry_appraisers_select` returns raw model IDs for each appraiser. Convert each to an agent name: `foundry-<model.replace(/\//g, '-')>` (e.g., `openai/gpt-4o` becomes `foundry-openai-gpt-4o`).
+`foundry_appraisers_select` returns raw model IDs for each appraiser. Convert each to an agent name: `foundry-<model.replace(/[/.]/g, '-')>` — both `/` and `.` are replaced with `-`. Examples:
+- `openai/gpt-4o` → `foundry-openai-gpt-4o`
+- `github-copilot/claude-sonnet-4.6` → `foundry-github-copilot-claude-sonnet-4-6`
 
 - If a model is specified: dispatch with `subagent_type: "foundry-<converted-name>"`. If no agent with that name exists, **hard fail**.
 - If no model is specified: dispatch with `subagent_type: "general"` (inherits session model).
 
+Note: per-appraiser `model` overrides are applied here at dispatch time. The cycle-level `models.appraise` value (if set) is used for routing-time agent-file validation only; this skill does not consult it when iterating appraisers.
+
 Dispatch all appraisers in parallel (multiple Task calls in a single response).
 
 ### Sub-agent prompt template
@@ -105,7 +154,7 @@ If there are no issues, return an empty list.
 
 ## History
 
-Do NOT call `foundry_history_append` or `foundry_git_commit` — the sort skill handles those. Return a summary via `foundry_stage_end` (e.g., "3 issues found across 2 appraisers" or "No issues found").
+Do NOT call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` handles those (the tools are not registered publicly). Return a summary via `foundry_stage_end` (e.g., "3 issues found across 2 appraisers" or "No issues found").
 
 ### Human override awareness
 
@@ -113,8 +162,8 @@ When reviewing an artefact, check the feedback history for `#human` tagged items
 
 ## What you do NOT do
 
-- You do not write files — all output goes through `foundry_feedback_add`.
+- You do not write files — feedback output goes through `foundry_feedback_add` and `foundry_feedback_resolve`.
 - You do not revise the artefact.
 - You do not check deterministic rules — that is the quench skill's job.
 - You do not filter out feedback because only one appraiser raised it — one is enough.
-- You do not register artefacts — that happens automatically via `foundry_stage_finalize`.
+- You do not register artefacts — that happens automatically via the orchestrator's internal finalize step.