@really-knows-ai/foundry 3.8.4 → 3.8.5

package/dist/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 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

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/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/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.4",
+  "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",