@really-knows-ai/foundry 1.2.0 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@really-knows-ai/foundry",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "A structured framework for AI-driven artefact creation with deterministic routing, quality gates, and iterative refinement cycles.",
   "type": "module",
   "main": ".opencode/plugins/foundry.js",

package/skills/appraise/SKILL.md

@@ -54,8 +54,18 @@ Model diversity is configured at two levels: the cycle definition sets a default
    - Union of all issues — if any one appraiser flags it, it's feedback
    - De-duplicate: merge overlapping observations into a single feedback item
    - Preserve which appraiser(s) raised each issue (for traceability)
-9. Write consolidated feedback to WORK.md:
-   - `- [ ] <description of the issue> #law:<law-id>`
+9. Write consolidated feedback to WORK.md under the artefact's file heading:
+
+   Feedback MUST be scoped to the artefact file. Under `## Feedback`, create a `### <file-path>` sub-heading matching the artefact's File column from the artefacts table, then write feedback items beneath it:
+
+   ```markdown
+   ## Feedback
+
+   ### foundry/output/haiku/pissed-off-spaghetti.md
+   - [ ] The imagery lacks originality #law:vivid-imagery
+   ```
+
+   If the `## Feedback` section or the file sub-heading already exists (e.g., quench already wrote validation feedback there), append items under the existing heading. Never write feedback items without a file sub-heading — the sort script cannot parse them.
 10. If no appraiser found any issues, the artefact clears appraisal
 
 ## Dispatch
@@ -120,7 +130,7 @@ If there are no issues, return an empty list.
 
 ## Reviewing actioned and wont-fix feedback
 
-On subsequent passes, appraisers also evaluate previously actioned and wont-fix items:
+On subsequent passes, appraisers also evaluate previously actioned and wont-fix items under the artefact's `### <file-path>` heading:
 
 - `[x]` actioned items: appraiser checks whether the change actually addresses the issue
   - If yes: mark `| approved`
@@ -146,3 +156,4 @@ After completing the appraisal consolidation, append an entry to `WORK.history.y
 - You do not revise the artefact
 - You do not check deterministic rules — that is the quench skill's job
 - You do not filter out feedback because only one appraiser raised it — one is enough
+- You do not write feedback items without a file sub-heading under `## Feedback`

package/skills/flow/SKILL.md

@@ -19,11 +19,33 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 1. Read the flow definition from `foundry/flows/<flow-id>.md`
 2. Create a branch off main: `work/<flow-id>-<short-description>`
-3. Create `WORK.md` in the root following the spec in `docs/work-spec.md`:
-   - Set frontmatter: flow id, first cycle id, first stage
-   - Write the goal (from flow definition + human context)
-   - Empty artefacts table with all four columns: `| File | Type | Cycle | Status |`
-   - Empty feedback section
+3. Create `WORK.md` in the project root with this structure:
+
+   ```markdown
+   ---
+   flow: <flow-id>
+   cycle: <first-cycle-id>
+   stages: [<determined by cycle skill>]
+   max-iterations: 3
+   ---
+
+   # Goal
+
+   <goal from flow definition + human context>
+
+   ## Artefacts
+
+   | File | Type | Cycle | Status |
+   |------|------|-------|--------|
+
+   ## Feedback
+   ```
+
+   - `flow` — set once, never changes
+   - `cycle` — current cycle id, updated when each cycle starts
+   - `stages` — the ordered route for the cycle, set by the cycle skill. Each entry uses `base:alias` format (e.g. `forge:write-haiku`, `quench:check-syllables`). Determined from the artefact type: if `validation.md` exists, include `quench`; always include `forge` and `appraise`. `hitl` stages are optional.
+   - `max-iterations` — how many forge passes before the cycle is blocked (default: 3, can be overridden in cycle definition)
+   - Feedback is grouped under `### <file-path>` sub-headings matching the artefact's File column. See the quench and appraise skills for the format.
 4. Execute each foundry cycle in order by reading its definition from `foundry/cycles/<cycle-id>.md`
 5. Update the frontmatter cursor as each foundry cycle starts (set `cycle` to the new cycle id)
 6. When all foundry cycles are done, delete WORK.md — the artefacts and git history are the record

package/skills/forge/SKILL.md

@@ -30,7 +30,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ### Revision (feedback exists in WORK.md)
 
-1. Read `WORK.md` — find unresolved feedback items for the artefact
+1. Read `WORK.md` — find unresolved feedback items for the artefact. Feedback is scoped by file: look under `## Feedback` for the `### <file-path>` sub-heading that matches the artefact's File column in the artefacts table. Only items under that heading belong to this artefact.
 2. Read the artefact
 3. If the foundry cycle has inputs, read the input artefacts (read-only context)
 4. For each unresolved feedback item, either:

package/skills/quench/SKILL.md

@@ -26,10 +26,23 @@ This skill only runs if `foundry/artefacts/<type>/validation.md` exists. If ther
 4. For each validation entry:
    - Substitute `{file}` in the command with the artefact path
    - Run the command
-   - If exit code is non-zero: add feedback to WORK.md:
-     - `- [ ] <failure description from validation.md> #validation`
+   - If exit code is non-zero: add feedback to WORK.md under the artefact's file heading
 5. If all commands exit zero, add no new feedback
 
+## Feedback format
+
+Feedback MUST be scoped to the artefact file it applies to. Under `## Feedback`, create a `### <file-path>` sub-heading matching the artefact's File column from the artefacts table, then write feedback items beneath it:
+
+```markdown
+## Feedback
+
+### foundry/output/haiku/pissed-off-spaghetti.md
+- [ ] The haiku does not have exactly 3 lines. #validation
+- [ ] One or more lines do not match the 5-7-5 syllable pattern. #validation
+```
+
+If the `## Feedback` section or the file sub-heading already exists, append items under the existing heading. Never write feedback items without a file sub-heading — the sort script cannot parse them.
+
 ## Reviewing actioned feedback
 
 On subsequent passes, the quench skill re-runs the relevant command for previously actioned items:
@@ -59,3 +72,4 @@ After completing validation (whether issues were found or not), append an entry
 - You do not evaluate laws — that is the appraise skill's job
 - You do not invent validation rules — you only run commands from the validation file
 - You do not duplicate feedback that already exists in WORK.md
+- You do not write feedback items without a file sub-heading under `## Feedback`