@really-knows-ai/foundry 3.8.3 → 3.8.5

package/dist/.opencode/plugins/foundry-tools/config-create-tools.js

@@ -133,6 +133,7 @@ function artefactTypeArgs(s) { return {
   name: s.string().describe('Human-readable display name (accepted at boundary, not persisted — id becomes frontmatter.name)'),
   filePatterns: s.array(s.string()).describe('Glob patterns defining forge write scope (written to frontmatter.file-patterns)'),
   description: s.string().describe('Prose description placed under ## Definition'),
+  example: s.string().optional().describe('Example artefact structure (markdown with code blocks). Written to example.md alongside definition.md. Guides forge agents on the expected output format.'),
   appraisers: s.object({
     count: s.number().optional().describe('Number of appraisers per cycle'),
     allowed: s.array(s.string()).optional().describe('Restrict to specific appraiser IDs'),

package/dist/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [3.8.5] - 2026-05-27
+
+### Changed
+
+- Human-appraise skill redesigned with two distinct review modes:
+  - **Clean review** (no unresolved feedback): Shows `git diff --stat` filtered to artefact type file-patterns, not full file content. Uses the question tool to offer Approve or Provide feedback.
+  - **Feedback review** (unresolved feedback exists): Presents each item individually via the question tool. User picks Agree (keep open for forge), Disagree (resolve with approved override), or Comment (add human feedback).
+  - All user interaction now uses the question tool (structured options) instead of free-text prompts.
+
+- Appraise consolidation now propagates finalize violations instead of swallowing them. If `finaliseStage` returns a violation (e.g. commit rejected), `consolidateAppraise` surfaces it rather than returning `{ ok: true }`.
+
+### Fixed
+
+- Sort violation details are now passed through to the terminal handler. Previously, `handleSortResult` destructured `sortResult` but didn't forward the `details` field to `resolveRouteResult`, causing all sort violations to show the default "sort returned violation" message.
+
+## [3.8.4] - 2026-05-27
+
+### Added
+
+- `foundry_config_create_artefact_type` now accepts an optional `example` arg. When provided, it writes `foundry/artefacts/<id>/example.md` alongside `definition.md`. The example file is a structure document — markdown with code blocks showing the expected output format, plus documentation for the forge agent.
+
+- The `add-artefact-type` skill now prompts users to provide an example artefact during the Understand phase, includes it in the Plan, and passes it to the create tool in Build.
+
+### Fixed
+
+- Human-appraise stage tokens no longer carry a subagent model scope. Previously, `sort.js` resolved a model for human-appraise routes (falling through to `defaultModel`), which got embedded in the token. `foundry_stage_begin` then rejected the token because the main Foundry agent is not the scoped subagent, causing the human-appraise stage to fail to start and user feedback to be lost. Human-appraise always runs inline by the Foundry agent.
+
 ## [3.8.3] - 2026-05-27
 
 ### Changed

package/dist/scripts/appraise-module.js

@@ -197,11 +197,16 @@ export async function consolidateAppraise(ctx, lastResults) {
 
   const summary = buildConsolidateSummary(consolidated.length);
 
-  await ctx.finalize({
+  return finalizeAndReturn(ctx, stageId, summary, baseSha);
+}
+
+async function finalizeAndReturn(ctx, stageId, summary, baseSha) {
+  const result = await ctx.finalize({
     lastStage: { stage: stageId, summary, baseSha },
     activeStage: ctx.activeStage,
   });
 
+  if (result && result.action === 'violation') return result;
   return { ok: true, summary };
 }
 

package/dist/scripts/lib/config-creators/artefact-type.js

@@ -50,7 +50,30 @@ const _create = makeCreator({
   validator: validate,
 });
 
+/**
+ * Assemble the markdown body for example.md from structured arguments.
+ *
+ * The example file is a structure document: markdown with code blocks showing
+ * the expected output format, plus documentation for the forge agent.
+ *
+ * @param {string} exampleContent - Raw markdown for example.md
+ * @returns {string} Trimmed content with trailing newline.
+ */
+export function assembleExampleMarkdown(exampleContent) {
+  return `${exampleContent.trim()}\n`;
+}
+
 export async function create(args) {
   const body = assembleArtefactTypeMarkdown(args);
+
+  if (args.example) {
+    const exampleDir = join('foundry', 'artefacts', args.id);
+    await args.io.mkdirp(exampleDir);
+    await args.io.writeFile(
+      join(exampleDir, 'example.md'),
+      assembleExampleMarkdown(args.example),
+    );
+  }
+
   return _create({ ...args, name: args.id, body });
 }

package/dist/scripts/orchestrate-phases.js

@@ -75,13 +75,13 @@ function isTerminalRoute(route) {
 export async function handleSortResult(sortResult, ctx) {
   const { route, model, token, reason } = sortResult;
   const routeBase = routeDispatch(route);
-  const result = await resolveRouteResult({ route, routeBase, model, token, ctx });
+  const result = await resolveRouteResult({ route, routeBase, model, token, ctx, sortResult });
   if (reason !== undefined) result.reason = reason;
   return result;
 }
 
-async function resolveRouteResult({ route, routeBase, model, token, ctx }) {
-  if (isTerminalRoute(route)) return handleTerminalRoute(route, { route }, ctx);
+async function resolveRouteResult({ route, routeBase, model, token, ctx, sortResult }) {
+  if (isTerminalRoute(route)) return handleTerminalRoute(route, sortResult, ctx);
   if (routeBase === 'quench' || routeBase === 'appraise') return violation(routeBase + ' route reached handleSortResult');
   if (routeBase === 'human-appraise') return humanAppraiseAction(route, token, ctx);
   return buildDispatchAction(route, model, token, ctx);

package/dist/scripts/sort.js

@@ -166,6 +166,7 @@ function resolveModelId(routeBase, models, defaultModel) {
 
 function pickModelId(route, frontmatter, defaultModel) {
   const routeBase = baseStage(route);
+  if (routeBase === 'human-appraise') return null;
   const resolved = frontmatter.models ? resolveModelId(routeBase, frontmatter.models, defaultModel) : null;
   return resolved || defaultModel || defaultForStage(routeBase);
 }

package/dist/skills/add-artefact-type/SKILL.md

@@ -38,7 +38,7 @@ Do not tell the user to call branch tools directly.
 
 When invoked with pre-filled fields matching the `foundry_config_create_artefact_type` tool args, skip questions for provided fields. Missing fields trigger clarifying questions.
 
-Context fields: `{id, name, filePatterns, description, appraisers?}`
+Context fields: `{id, name, filePatterns, description, example?, appraisers?}`
 
 When invoked with a context:
 - If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
@@ -48,6 +48,12 @@ When invoked with a context:
 
 Ask for each field one question at a time. Prefer multiple choice for `filePatterns`, deriving options from the artefact type name and common conventions (e.g. `haikus/*.md`, `haiku.md`, `output/haiku/*.md`). Ask about `appraisers` (optional) — either provide an existing appraiser ID or skip.
 
+After the core fields, ask about the example:
+
+> Would you like to provide an example artefact? An example shows forge agents the expected output structure — markdown with code blocks, plus any conventions, constraints, or required sections. Give a short example file that demonstrates what a valid output looks like.
+
+If the user provides an example, capture it verbatim. If the artefact type has no structured output (e.g. free-form prose with no required format), the user may skip this step.
+
 **Naming conflict check**: Read all existing artefact type definitions in `foundry/artefacts/*/definition.md`. Exact id match means a hard conflict — choose a different id. A semantically similar name or description triggers a warning:
 
 > An artefact type `<existing-id>` already exists that seems similar:
@@ -74,6 +80,7 @@ Present the definition to the user with these structured fields:
 - `name` (string) — human-readable label.
 - `filePatterns` (string[]) — glob patterns for files this type produces.
 - `description` (string) — prose description of what this artefact type is.
+- `example` (string, optional) — example artefact to guide forge agents on the expected output structure.
 - `appraisers` ({ count?: number, allowed?: string[] }, optional) — appraiser configuration.
 
 Ask: does this capture the artefact type correctly? Iterate until the user is satisfied.
@@ -86,7 +93,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 1. **Validate**: Call `foundry_config_validate_artefact_type({ name: "<id>", body: "<assembled markdown>" })`. Assemble the body from the fields using the frontmatter format the tool produces internally. If the result is `{ ok: false, errors: [...] }`, address each error and re-run until `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that do not exist yet.
 
-2. **Create**: Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>" })`. The tool re-validates the body (TOCTOU), writes `foundry/artefacts/<id>/definition.md`, and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
+2. **Create**: Call `foundry_config_create_artefact_type({ id: "<id>", name: "<name>", filePatterns: ["<pattern>"], description: "<description>", example: "<example>" })`. Include `example` only when the user provided one. The tool re-validates the body (TOCTOU), writes `foundry/artefacts/<id>/definition.md` (and `example.md` if provided), and produces one git commit on the current `config/*` branch. Show the user the resulting commit hash.
 
    If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing file, incorporate the user's requested changes into the current body, propose the merged result for review, then write and commit the updated file.
 

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

@@ -39,79 +39,166 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
 
 ## 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({summary: 'Flow is failed; no human appraisal performed'})`, 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_end({summary: 'Human approved — no issues'})`. 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({summary: 'Human requested changes'})`. 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_end({summary: 'Human reviewed — <count> item(s) agreed, <count> overridden'})`.
+- **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({summary: 'Human reviewed with additional feedback'})`.
+
+---
 
 ## 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 present the full artefact file content — the human can inspect files themselves if curious. Show summaries only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "3.8.3",
+  "version": "3.8.5",
   "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",