@really-knows-ai/foundry 3.8.4 → 3.9.0

package/dist/skills/appraise/SKILL.md

@@ -21,9 +21,9 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 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. No other tool call is permitted before this one.
-2. **Last:** `foundry_stage_end({summary})`.
+2. **Last:** `foundry_stage_end()`.
 
-Appraise makes **no disk writes**. Feedback output flows through JSONL returned in your response text. The orchestrator's internal consolidate step parses the JSONL, posts feedback, and resolves prior items.
+Appraise makes **no disk writes**. Feedback output flows through `foundry_stage_output` calls. The orchestrator's internal consolidate step reads the outputs, posts feedback, and resolves prior items.
 
 ## Protocol
 
@@ -35,43 +35,25 @@ Appraise makes **no disk writes**. Feedback output flows through JSONL returned
 6. Evaluate each file against each law. For each law, either:
    - Note no issues (pass)
    - Describe the violation, quoting evidence from the artefact
-7. Output JSONL. Each line is one JSON object:
-
-   ```json
-   {"file": "<path>", "law": "<law-slug>", "text": "<issue description>", "evidence": "<quote from artefact>"}
-   ```
-
+7. For each violation, call `foundry_stage_output({ file, law, text, evidence })`.
    `file` and `text` are required. `law` and `evidence` are recommended — `law` tells the orchestrator which law tag to use, `evidence` quotes the offending passage. Optional extra fields (`severity`, `location`) are passed through unchanged.
 
-   If there are no issues, output nothing (empty response).
-
-   Your response text is ONLY JSONL — one JSON object per line. No markdown headings, no code blocks, no commentary, no YAML.
-
-8. `foundry_stage_end({summary})`. The summary describes how many issues were found (e.g. "3 issues found" or "No issues found").
-
-## Output examples
-
-Good (issues found):
-
-```
-{"file": "haikus/mountain.md", "law": "syllable-count", "text": "Line 2 has 8 syllables, expected 7", "evidence": "A frog jumps into the pond", "location": "2:1"}
-{"file": "haikus/mountain.md", "law": "nature-imagery", "text": "Contains industrial imagery violating nature-only requirement", "evidence": "The rusty old machine"}
-```
+   If no issues, call `foundry_stage_end()` directly — no `stage_output` calls needed.
 
-Good (no issues found — empty response, then stage_end):
+   Do NOT write JSONL as text. Call the tool.
 
-(no output text)
+8. `foundry_stage_end()`.
 
 ## Feedback handling
 
-You do NOT call `foundry_feedback_add` or `foundry_feedback_resolve`. The orchestrator's consolidate step reads your JSONL output, de-duplicates across all appraisers, posts feedback items with tag `law:<slug>`, and resolves prior appraise-sourced feedback.
+You do NOT call `foundry_feedback_add` or `foundry_feedback_resolve`. The orchestrator's consolidate step reads your stage outputs, de-duplicates across all appraisers, posts feedback items with tag `law:<slug>`, and resolves prior appraise-sourced feedback.
 
 ## What you do NOT do
 
-- You do not write files — feedback output goes through JSONL, not `foundry_feedback_add`.
+- You do not write files — feedback output goes through `foundry_stage_output`, not `foundry_feedback_add`.
 - You do not revise the artefact — that is the forge skill's job.
 - You do not run deterministic validators — that is the quench skill's job.
 - You do not call `foundry_feedback_add`, `foundry_feedback_action`, `foundry_feedback_wontfix`, or `foundry_feedback_resolve`.
 - You do not call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` handles those.
 - You do not register artefacts — that happens automatically.
-- You do not output YAML, markdown, or prose — only JSONL.
+- You do not output YAML, markdown, or prose — use `foundry_stage_output` for structured data.

package/dist/skills/assay/SKILL.md

@@ -8,7 +8,7 @@ description: Deterministic population of flow memory by running project-authored
 
 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.
+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 and stop.
 
 ## Protocol
 
@@ -22,7 +22,7 @@ Call `foundry_stage_begin({ stage, cycle, token })` with the values from the dis
 
 ### 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.
+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 4) with an error describing the missing extractor list.
 
 ### Check for failed flow state
 
@@ -45,21 +45,14 @@ Call `foundry_assay_run({ cycle, extractors })` passing exactly those values. Do
 - `{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.
+- `{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 4).
 
-### 4. Prepare the summary
+### 4. End the stage
 
-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"`.
+Call `foundry_stage_end()`. Always end the stage, whether the run succeeded or aborted. The stage lifecycle must close cleanly so the orchestrator can commit.
 
 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.
@@ -69,4 +62,4 @@ Call `foundry_stage_end({ summary })` with the summary from step 4. Always end t
 
 ## 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.
+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 and stop.

package/dist/skills/forge/SKILL.md

@@ -21,7 +21,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 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 finalise step scans the disk and registers your output artefact. **You do not register artefacts yourself.**
+2. **Last:** `foundry_stage_end()` — return control to the orchestrator. After `stage_end`, the orchestrator's internal finalise step scans the disk and registers your output artefact. **You do not register artefacts yourself.**
 
 ## Protocol
 
@@ -51,7 +51,7 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
    - 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: "DONE"})`.
+9. `foundry_stage_output({ status: "done" })` then `foundry_stage_end()`.
 
 ### Revision (feedback exists)
 
@@ -60,26 +60,25 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 3. 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).
 4. Address the single feedback item from the dispatch prompt following the feedback handling rules below.
 5. Update the artefact file (if fixing), or skip (if WONT-FIX).
-6. `foundry_stage_end({summary})`. The summary must be EXACTLY one of:
-   - `"ACTIONED"` — file was changed to address the feedback
-   - `"WONT-FIX: <justification>"` — item already resolved or does not apply
-   Write NOTHING else in the summary.
+6. `foundry_stage_output({ status: "actioned" })` then `foundry_stage_end()` — file was changed to address the feedback.
+   Or: `foundry_stage_output({ status: "wont-fix", reason: "<justification>" })` then `foundry_stage_end()` — item already resolved or does not apply.
+   Call `foundry_stage_output` with the correct status object. Write nothing else — format is validated by the tool.
 
 ## Feedback handling
 
 The dispatch prompt contains one feedback item to address.
 
 **To fix the issue** — change the artefact file and call
-`foundry_stage_end({summary: "ACTIONED"})`.
+`foundry_stage_output({ status: "actioned" })` then `foundry_stage_end()`.
 
 **If the issue is already resolved** — call
-`foundry_stage_end({summary: "WONT-FIX: <justification>"})`.
+`foundry_stage_output({ status: "wont-fix", reason: "<justification>" })` then `foundry_stage_end()`.
 Do NOT change the file.
 
 **If the issue does not apply** (appraise judgement you disagree with) — same
-`WONT-FIX:` flow.
+`wont-fix` flow.
 
-The summary is ONLY one of these keywords. No descriptions, no explanations.
+The status is validated by the tool. No descriptions, no explanations.
 
 Do NOT call `foundry_feedback_action`, `foundry_feedback_wontfix`, or
 `foundry_feedback_resolve`. The orchestrator handles transitions automatically.
@@ -109,5 +108,5 @@ items in the list output.
 - You do not register artefacts — the orchestrator's internal finalise 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 or wont-fix via tool calls — the orchestrator handles feedback transitions based on your artefact changes and `stage_end` summary.
+- You do not mark feedback as actioned or wont-fix via tool calls — the orchestrator handles feedback transitions based on your artefact changes and stage output.
 - 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.

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

@@ -19,7 +19,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 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})`.
+2. **Last:** `foundry_stage_end()`.
 
 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.
 
@@ -35,83 +35,170 @@ When invoked from orchestrate, you receive `{cycle, token, context}`:
 
 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.
+Your last tool calls must be `foundry_stage_output({ verdict: "approved" })` then `foundry_stage_end()`. The verdict is communicated through `foundry_stage_output` before the stage is closed.
 
 ## Protocol
 
+### Step 1: Gather context
+
 1. `foundry_stage_begin(...)`.
-2. Gather context by calling:
-   - `foundry_workfile_get` — current state, goal, cycle
+2. `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()`, return control to the user, and stop.
+
+3. `foundry_artefacts_list({})` — this cycle's branch artefact changes as `[{ file, state }]` entries.
+4. `foundry_feedback_list` — all existing feedback items.
+5. `foundry_history_list({cycle: <current-cycle>})` — what has happened so far.
+
+### Step 2: Classify feedback
+
+Split the feedback list into two categories by `state`:
+- **Resolved**: `state === 'resolved'` — no action needed, informational only.
+- **Unresolved**: all other states (`open`, `rejected`, `actioned`, `wont-fix`).
+
+### Step 3: Route to the correct review mode
+
+- **If there are NO unresolved feedback items** → go to **Mode A: Clean review**.
+- **If there ARE unresolved feedback items** → go to **Mode B: Feedback review**.
+
+---
+
+## Mode A: Clean review (no unresolved feedback)
+
+The cycle is in good shape — all feedback from appraisers and quench has been addressed. You present the artefact summary only, not the full content.
+
+### A.1 Show the artefact summary
+
+Get the artefact type's file-patterns: call `foundry_config_artefact_type` with the cycle's output type (from `foundry_workfile_get`). The response includes `file-patterns` — glob patterns for this artefact type (e.g. `["haikus/*.md"]`).
+
+Run `git diff --stat main..HEAD` restricted to only those files by passing each glob as a pathspec:
+
+```
+git diff --stat main..HEAD -- haikus/*.md
+```
+
+Example output:
+
+```
+ haikus/sunburn.md  |  4 +++-
+ 1 file changed, 4 insertions(+), 1 deletion(-)
+```
+
+Also show the goal from `foundry_workfile_get` so the user knows what was being produced.
+
+### A.2 Ask the user
 
-     **Check for failed flow state.** If `foundry_workfile_get` returns `{status: "failed", reason: ...}`, STOP. Do not do any substantive work. Tell the user:
+Use the **question tool** (NOT a plain text prompt — the question tool pauses and waits for 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.
+```
+header: "Review changes"
+question: "The cycle finished with no unresolved feedback. Here are the changes:
 
-     Then call `foundry_stage_end({summary: 'Flow is failed; no human appraisal performed'})`, return control to the user, and stop.
-   - `foundry_artefacts_list({})` — this cycle's branch artefact changes as `[{ file, state }]` entries
-   - `foundry_feedback_list` — all existing feedback
-   - `foundry_history_list({cycle: <current-cycle>})` — what has happened so far
+<diff stat output>
 
-3. Read the artefact file(s) for this cycle.
+Goal: <goal from workfile>
 
-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)
-   - Ask the human to review, provide feedback, or approve
+What would you like to do?"
+options:
+  - label: "Approve"
+    description: "Looks good — close the cycle as done"
+  - label: "Provide feedback"
+    description: "Send feedback to forge for another iteration"
+```
 
-5. Wait for the human's response.
+### A.3 Act on 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}`. See "Feedback handling" below for the legal transitions and authority rules.
-   - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the repository no longer has a per-artefact status tool or table). 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 blocks the cycle on its own.
+- **Approve**: No feedback added. Call `foundry_stage_output({ verdict: "approved" })` then `foundry_stage_end()`. Sort will route to `done`.
+- **Provide feedback**: Ask the user what needs changing (the user types their feedback). Then call `foundry_feedback_add({ file: '<artefact-file>', text: '<user feedback>', tag: 'human' })`. Call `foundry_stage_end()`. Sort will route to forge.
 
-7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
+---
+
+## Mode B: Feedback review (unresolved feedback exists)
+
+The cycle has outstanding feedback from appraisers, quench, or prior human reviews. You present each item to the user for a verdict.
+
+### B.1 Summarise the state
+
+Briefly tell the user how many unresolved items exist and what the goal is.
+
+### B.2 Review each unresolved item
+
+Present each unresolved item **one at a time** using the **question tool**. For each item:
+
+```
+header: "Feedback N of M"
+question: "Feedback item:
+
+  File: <file>
+  Source: <source stage>
+  Tag: <tag>
+  Issue: <text>
+
+<if the item has a reason, show: "Reason: <reason>">
+
+Do you agree with this feedback?"
+options:
+  - label: "Agree"
+    description: "This needs fixing — let forge handle it"
+  - label: "Disagree"
+    description: "Override this item — resolve it"
+  - label: "Comment"
+    description: "Add my own note or context about this item"
+```
+
+After the user responds:
+
+- **Agree**: Do nothing — the item stays in its current state. Sort will route to forge to address it.
+- **Disagree**: Call `foundry_feedback_resolve({ id: '<item-id>', resolution: 'approved' })`. Optionally pass a `reason`.
+- **Comment**: Ask the user what they want to say. Then call `foundry_feedback_add({ file: '<file>', text: '<user comment>', tag: 'human' })`. The original item stays open so forge still addresses it alongside the human comment.
+
+Repeat for every unresolved item.
+
+### B.3 Final question
+
+After all unresolved items have been reviewed, ask one final question using the **question tool**:
+
+```
+header: "Any other feedback?"
+question: "All unresolved feedback items have been reviewed. Any other changes you want before the cycle continues?"
+options:
+  - label: "None — continue"
+    description: "Proceed with the current state"
+  - label: "Add more feedback"
+    description: "Provide additional notes for forge"
+```
+
+- **None — continue**: Call `foundry_stage_output({ verdict: "approved" })` then `foundry_stage_end()`.
+- **Add more feedback**: Ask the user what they want to add, then call `foundry_feedback_add({ file: '<file>', text: '<text>', tag: 'human' })`. Then call `foundry_stage_end()`.
+
+---
 
 ## Feedback handling
 
-As a human-appraise stage, you can add human feedback and resolve
-feedback items. **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.
+As a human-appraise stage, you can add human feedback and resolve feedback items. **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.
 
 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.** The repository no longer has a per-artefact
-  status tool or table. Status is owned by the cycle state machine through
-  sort and orchestrate routing.
+- **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.** The repository no longer has a per-artefact status tool or table. Status is owned by the cycle state machine through sort and orchestrate 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.
+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 item.** For items in
-   `{actioned, wont-fix}`, 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.
+2. **Resolve any non-resolved item.** For items in `{actioned, wont-fix}`, 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.
 
-**Reason rules.** `reason` is required when rejecting feedback
-(`resolution: 'rejected'`). Approved resolution via
-`foundry_feedback_resolve({ id, resolution: 'approved', reason? })` may
-omit `reason`.
+**Reason rules.** `reason` is required when rejecting feedback (`resolution: 'rejected'`). Approved resolution via `foundry_feedback_resolve({ id, resolution: 'approved', reason? })` may omit `reason`.
 
 ## What you do NOT do
 
@@ -119,6 +206,6 @@ omit `reason`.
 - 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})`.
+- You do not register artefacts — handled by `foundry_stage_end()`.
+- You do not present the full artefact file content — the human can inspect files themselves if curious. Show summaries only.

package/dist/skills/orchestrate/SKILL.md

@@ -82,7 +82,7 @@ module handles lifecycle internally.
 
 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})`.
+Invoke the `human-appraise` skill inline, passing `{cycle, token, context}`. The skill will prompt the user, collect feedback, and call `foundry_stage_output({ verdict: "approved" })` then `foundry_stage_end()`.
 
 When it returns, call `foundry_orchestrate({lastResult: {ok: true}})`.
 
@@ -117,7 +117,7 @@ Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<af
 
 The orchestrator manages forge feedback transitions directly. After each
 forge subagent completes, `enforceForgeStage` inspects the outcome — a
-version change or a WONT-FIX in the stage-end summary — and transitions the
+version change or a wont-fix status in the stage output — and transitions the
 feedback item to `actioned` or `wont-fix`. Forge subagents do not call
 `foundry_feedback_action` or `foundry_feedback_wontfix`; those are the
 orchestrator's responsibility. If you want to inspect feedback state for

package/dist/skills/quench/SKILL.md

@@ -19,7 +19,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 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})`.
+2. **Last:** `foundry_stage_end()`.
 
 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.
 
@@ -43,11 +43,11 @@ Quench makes **no disk writes**. You produce feedback via `foundry_feedback_add`
 4. For each artefact change:
     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.
+   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; 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 artefact change, add no new feedback.
-7. If the artefact list is empty, `foundry_stage_end({summary: 'SKIP: no files'})` and stop.
-8. `foundry_stage_end({summary})`.
+7. If the artefact list is empty, `foundry_stage_end()` and stop.
+8. `foundry_stage_end()`.
 
 ## Feedback handling
 
@@ -86,7 +86,7 @@ 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").
+Do NOT call `foundry_history_append` or `foundry_git_commit` — `foundry_orchestrate` handles those (the tools are not registered publicly).
 
 ## What you do NOT do
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.8.4",
+  "version": "3.9.0",
   "description": "A skill-driven framework for governed artefact generation with AI coding tools. Define your own artefact types, laws, and flows — Foundry handles the forge → quench → appraise pipeline with deterministic routing, quality gates, and iterative refinement.",
   "type": "module",
   "main": "dist/.opencode/plugins/foundry.js",