@really-knows-ai/foundry 3.4.0 → 3.5.2

package/dist/skills/add-cycle/SKILL.md

@@ -40,6 +40,10 @@ When invoked with pre-filled fields matching the `foundry_config_create_cycle` t
 
 Context fields: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`
 
+`inputs` is optional. A source cycle that starts from the user's run goal and has no upstream artefact dependency omits `inputs` entirely. Empty input contracts are invalid: do not pass `inputs: {type: "any-of", artefacts: []}`.
+
+`models` is a map of stage names to model IDs. Preserve user-selected model overrides exactly, for example `{forge: "opencode-go/deepseek-v4-flash", appraise: "opencode-go/qwen3.6-plus"}`.
+
 When invoked with a context:
 - If all required fields are present, skip the Understand phase and proceed to Plan → Confirm → Build.
 - If only some fields are present, ask only for the missing ones.
@@ -80,7 +84,7 @@ If the parent flow or required artefact type is missing and the user's goal clea
 
 **Optional clusters** — After each cluster, ask whether the user wants to configure it; if not, skip:
 
-- **Routing**: `inputs` (input contract: `{type: "any-of"|"all-of", artefacts: string[]}`), `targets` (cycle IDs to route to after completion), `maxIterations` (maximum iterations before forced progression)
+- **Routing**: `inputs` (input contract: `{type: "any-of"|"all-of", artefacts: string[]}`; omit for source cycles with no upstream artefact dependency), `targets` (cycle IDs to route to after completion), `maxIterations` (maximum iterations before forced progression)
 - **Human-appraise**: `humanAppraise` (boolean, default false) — human reviews every iteration; `deadlockAppraise` (boolean, default true) — human is pulled in when LLM appraisers deadlock; `deadlockIterations` (number, default 5) — deadlock threshold. Only applies when either appraise is enabled.
 - **Memory and models**: `assay` (assay configuration), `memory` (memory configuration), `models` (stage-specific model overrides, e.g. `{forge: "openai/gpt-4o", appraise: "openai/gpt-4o"}`). For models, offer each stage (forge, quench, appraise) individually. If the user has no preference, omit the `models` map and use the session defaults.
 
@@ -98,7 +102,7 @@ Ask: "Proceed with this plan?" — wait for user answer before building. If the
 
 1. **Validate**: Call `foundry_config_validate_cycle({ 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_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", inputs: ..., targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. The tool:
+2. **Create**: Call `foundry_config_create_cycle({ id: "<id>", name: "<name>", outputType: "<type>", description: "<description>", targets: ..., humanAppraise: ..., deadlockAppraise: ..., deadlockIterations: ..., maxIterations: ..., assay: ..., memory: ..., models: ... })`. Include `inputs` only when the cycle reads upstream artefacts, and include `models` whenever the user selected stage-specific model overrides. The tool:
    - re-validates the body (TOCTOU);
    - writes `foundry/cycles/<id>.md`;
    - produces one git commit on the current `config/*` branch.

package/dist/skills/add-flow/SKILL.md

@@ -69,7 +69,7 @@ Create missing dependencies in validation order:
 
 3. **Appraisers** (may reference models): For each new appraiser, gather `id`, `name`, `description`, and optional `model` preference. Context object: `{id, name, description, model?}`.
 
-4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`.
+4. **Cycles** (reference artefact types, laws, appraisers): For each new cycle, gather `id`, `name`, `outputType`, `description`, and any optional settings (inputs, targets, appraise, assay, memory, models). Context object: `{id, name, outputType, description, inputs?, targets?, humanAppraise?, deadlockAppraise?, deadlockIterations?, maxIterations?, assay?, memory?, models?}`. For a source cycle that starts from the user's run goal and has no upstream artefact dependency, omit `inputs` entirely; never pass `inputs` with an empty `artefacts` array.
 
 For the haiku example, default to a `haiku` artefact type, `haikus/*.md` file pattern, laws for form, imagery, and mood, a deterministic syllable validator where project dependencies allow it, two or three distinct appraisers, one cycle, and one flow.
 
@@ -92,6 +92,7 @@ Flow: <id> — <name>
     · <id> — <description>
   Cycles:
     · <id> → <outputType> — <description>
+      inputs/models: <omitted or explicit settings>
 ```
 
 Ask "Proceed with this plan?" — do not build anything until the user confirms.
@@ -121,9 +122,11 @@ Build order (dependency order):
 
 4. **Cycles**: For each new cycle, invoke the `add-cycle` protocol with the captured context.
 
-   > Invoke the add-cycle protocol with context: `{id: "haiku-cycle", name: "Haiku Cycle", outputType: "haiku", description: "Generates haiku poems"}`.
+   > Invoke the add-cycle protocol with context: `{id: "haiku-cycle", name: "Haiku Cycle", outputType: "haiku", description: "Generates haiku poems", models: {forge: "opencode-go/deepseek-v4-flash", appraise: "opencode-go/qwen3.6-plus"}}`.
    > If all required fields are present, proceed directly to Build. Otherwise ask for missing required fields only.
 
+   Preserve every user-selected stage model in the cycle context. If the cycle has no upstream artefact input, leave `inputs` absent from the context.
+
 **Build-only mode**: When all required fields for a sub-skill are present in the context, the sub-skill skips Understand, Plan, and Confirm — proceeding directly to validate → create → commit. When only some required fields are present, the sub-skill enters its Understand phase to ask only for those missing required fields, then proceeds to Build (still skipping Plan and Confirm since the parent's combined plan already handled confirmation). Optional fields that are missing are silently skipped.
 
 **Error handling during build**: If a sub-skill's Build phase fails (validation error or tool error), surface the error to the user:

package/dist/skills/appraise/SKILL.md

@@ -40,9 +40,9 @@ Appraise makes **no disk writes**. Feedback output flows through `foundry_feedba
      >   3. Investigate and fix the root cause of the failure before restarting.
 
      Then return control to the user and stop.
-   - `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate this cycle's artefacts. Always pass the `cycle` filter; omitting it returns stale rows from prior sessions. Skip rows whose status is `done` or `blocked`.
-   - For each remaining row, gather its type-specific context:
-     - `foundry_config_laws` with the row's type — applicable laws (global + type-specific)
+   - `foundry_artefacts_list({})` — enumerate the current cycle's branch artefact changes as `[{ file, state }]` entries.
+   - For each artefact change, gather its type-specific context:
+     - `foundry_config_laws` with the cycle's output type — applicable laws (global + type-specific)
      - `foundry_config_artefact_type` with the type ID — the artefact type definition
      - `foundry_appraisers_select` with the type ID — selected appraiser personalities with their raw model IDs
 

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

@@ -23,7 +23,7 @@ Human-appraise runs inside an enforced stage. Your **first** and **last** tool c
 
 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.
 
-Human-appraise **cannot** call `foundry_feedback_action`, `foundry_feedback_wontfix`, or `foundry_artefacts_set_status` — the tools reject those calls during a human-appraise stage (action/wontfix are forge-only forward transitions; set-status requires no active stage). See "Feedback handling" below for the legal transitions available to human-appraise.
+Human-appraise **cannot** call `foundry_feedback_action` or `foundry_feedback_wontfix` — the tools reject those calls during a human-appraise stage (action/wontfix are forge-only forward transitions). See "Feedback handling" below for the legal transitions available to human-appraise.
 
 ## Input
 
@@ -54,7 +54,7 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
      >   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.
-   - `foundry_artefacts_list({cycle: <current-cycle>})` — this cycle's artefact files and status (always pass the `cycle` filter; omitting it returns stale rows from prior sessions)
+   - `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
 
@@ -75,7 +75,7 @@ Your LAST tool call must be `foundry_stage_end({summary: '<one-sentence descript
    - **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, deadlocked}`. See "Feedback handling" below for the legal transitions and authority rules.
-   - **Abort** — human-appraise cannot directly mark the artefact `blocked` (the `foundry_artefacts_set_status` tool refuses calls during an active stage). 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 marks the artefact blocked on its own.
+   - **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.
 
 7. `foundry_stage_end({summary})` — describe what the human decided so sort can log it.
 
@@ -96,10 +96,9 @@ What human-appraise can NOT do:
   `{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.** `foundry_artefacts_set_status` requires
-  no active stage; it refuses calls while human-appraise is open. Status
-  promotion to `done`/`blocked` is owned by sort/orchestrate based on
-  routing.
+- **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:
 

package/dist/skills/orchestrate/SKILL.md

@@ -87,21 +87,20 @@ When it returns, call `foundry_orchestrate({lastResult: {ok: true}})`.
 
 Payload: `{cycle, artefact_file, next_cycles}`.
 
-1. Call `foundry_artefacts_set_status({file: artefact_file, status: 'done'})`.
-2. Report to the user: "Cycle `<cycle>` complete. Output: `<artefact_file>`. Next cycles available: `<next_cycles>`."
-3. Return control to the flow skill.
+1. Report to the user: "Cycle `<cycle>` complete. Output: `<artefact_file>`. Next cycles available: `<next_cycles>`."
+2. Return control to the flow skill.
 
 ### `blocked`
 
 Payload: `{cycle, artefact_file, reason}`.
 
-Report to the user: "Cycle `<cycle>` blocked on `<artefact_file>`: `<reason>`." Return control to the flow skill. The artefact has already been marked blocked.
+Report to the user: "Cycle `<cycle>` blocked on `<artefact_file>`: `<reason>`." Return control to the flow skill. The cycle is blocked.
 
 ### `violation`
 
 Payload: `{details, affected_files}`.
 
-Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<affected_files>`." Return control to the flow skill. Affected artefacts have already been marked blocked.
+Report to the user: "Cycle halted (violation): `<details>`. Affected files: `<affected_files>`." Return control to the flow skill. The cycle is halted by the violation; no per-artefact status is written.
 
 ## What you do NOT do
 

package/dist/skills/quench/SKILL.md

@@ -39,14 +39,14 @@ Quench makes **no disk writes**. You produce feedback via `foundry_feedback_add`
    >   3. Investigate and fix the root cause of the failure before restarting.
 
    Then return control to the user and stop.
-3. `foundry_artefacts_list({cycle: <current-cycle>})` — enumerate the artefacts produced by **this** cycle. Always pass the `cycle` filter; omitting it returns rows from prior sessions and validates stale files. Skip rows whose status is `done` or `blocked`.
-4. For each remaining row:
+3. `foundry_artefacts_list({})` — enumerate the current cycle's branch artefact changes as `[{ file, state }]` entries.
+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.
 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 row, add no new feedback.
-7. If the artefact table has no rows for this cycle, `foundry_stage_end({summary: 'SKIP: no artefacts registered for this cycle'})` and stop.
+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})`.
 
 ## Feedback handling

package/package.json

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