@really-knows-ai/foundry 3.8.5 → 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,7 +35,7 @@ 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
 
@@ -54,7 +54,7 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
    >   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.
+   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.
@@ -118,8 +118,8 @@ options:
 
 ### A.3 Act on response
 
-- **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.
+- **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.
 
 ---
 
@@ -178,8 +178,8 @@ options:
     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'})`.
+- **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()`.
 
 ---
 
@@ -207,5 +207,5 @@ What human-appraise CAN do:
 - You do not modify the artefact.
 - You do not skip the pause — the human must respond before continuing.
 - 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.5",
+  "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",