@really-knows-ai/foundry 2.0.1 → 2.2.1

package/skills/refresh-agents/SKILL.md

@@ -16,11 +16,14 @@ Regenerate `.opencode/agents/foundry-*.md` files from the currently available mo
 
 ### Agent file format
 
-Filename: `.opencode/agents/foundry-<provider>-<model-key>.md`
+Filename: `.opencode/agents/foundry-<slug>.md`
 
-Where `<provider>-<model-key>` is the model ID with `/` replaced by `-`.
+Where `<slug>` is the model ID with **both** `/` and `.` replaced by `-`. This keeps filenames shell-safe and unambiguous.
 
-Example: model `opencode/claude-sonnet-4` produces `.opencode/agents/foundry-opencode-claude-sonnet-4.md`
+Examples:
+- `opencode/claude-sonnet-4` → `.opencode/agents/foundry-opencode-claude-sonnet-4.md`
+- `github-copilot/claude-sonnet-4.6` → `.opencode/agents/foundry-github-copilot-claude-sonnet-4-6.md`
+- `github-copilot/gpt-5.4` → `.opencode/agents/foundry-github-copilot-gpt-5-4.md`
 
 Content:
 

package/skills/sort/SKILL.md

@@ -6,7 +6,7 @@ description: Deterministic routing for a foundry cycle. Runs the foundry_sort to
 
 # Sort
 
-You are the central dispatcher for a foundry cycle. You call the `foundry_sort` tool to determine what stage to execute next, then invoke that stage's skill.
+You are the central dispatcher for a foundry cycle. You call `foundry_sort` to determine what stage to execute next, dispatch that stage to a fresh subagent, finalize the stage's disk output, and log history. You are the sole writer of history and git commits.
 
 ## Prerequisites
 
@@ -16,26 +16,96 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ## Protocol
 
-1. Call `foundry_sort` (optionally passing `cycleDef` if the cycle definition has a non-standard path). It returns `{route, model?, details?}`.
+1. Call `foundry_sort` (optionally passing `cycleDef`). It returns `{route, model?, token?, details?}`. For dispatchable routes (`forge|quench|appraise|human-appraise:*`) the tool mints a single-use, time-limited `token`.
 
-2. Call `foundry_history_append` with the current cycle, stage `"sort"`, and a comment explaining the routing decision in natural language. This is your audit trail — if something goes wrong, this comment is what someone will read to understand what happened.
+2. Call `foundry_history_append({cycle, stage: 'sort', comment, route})` — the `route` field records what sort decided, and **subsequent** `history_append` calls for non-sort stages are enforced to match this route. This is your audit trail.
 
 3. Act on the route:
-   - `forge:*` — dispatch the forge skill as a sub-agent. Use model dispatch (see below).
-   - `quench:*` — dispatch the quench skill as a sub-agent. Use model dispatch.
-   - `appraise:*` — dispatch the appraise skill as a sub-agent. Use model dispatch. Note: the appraise skill handles its own per-appraiser model resolution internally.
-   - `human-appraise:*` — invoke the human-appraise skill (no model dispatch — human stage)
-   - `done` — foundry cycle is complete, return to the cycle skill
-   - `blocked` — foundry cycle is blocked (iteration limit hit with unresolved feedback), return to the cycle skill
-   - `violation` — file modification or tag validation violation detected (see `details`). The cycle halts — call `foundry_artefacts_set_status` with status `"blocked"`, and return to the cycle skill
+   - `forge:*` / `quench:*` / `appraise:*` — **dispatch** (see §Dispatch).
+   - `human-appraise:*` — invoke the human-appraise skill inline (human stage, no subagent) but still pass the `token`; the skill must call `foundry_stage_begin` with it.
+   - `done` — cycle is complete, return to the cycle skill.
+   - `blocked` — iteration limit hit with unresolved feedback, return to the cycle skill.
+   - `violation` — a validation, file-modification, or missing-subagent violation was detected (see `details`). Halt the cycle: call `foundry_artefacts_set_status(file, 'blocked')` for each affected artefact, and return to the cycle skill. If `details` mentions a missing subagent, tell the user to run `refresh-agents` and restart.
 
-4. After the subagent completes, call `foundry_history_append` with the current cycle, the **dispatched stage alias** (e.g., `forge:write-haiku`), and a comment summarizing what the subagent reported doing. This is critical — sort is the only reliable writer of stage history. Subagents must NOT write their own history entries.
+4. **After** the dispatched subagent returns, call `foundry_stage_finalize({cycle})`. Handle three outcomes:
+   - `{ok: true, artefacts: [...]}` — the tool has already registered output artefact rows in WORK.md. Proceed to step 5.
+   - `{error: 'unexpected_files', files: [...]}` — the subagent wrote outside the artefact type's `file-patterns`. Mark the cycle's target artefact `blocked` via `foundry_artefacts_set_status` and do **not** re-run the stage. Add a `violation` feedback item describing the offending files, then return to the cycle skill.
+   - Any other error — surface it to the user and halt.
 
-5. After logging the stage history, call `foundry_sort` again. Repeat from step 1 until it returns `done`, `blocked`, or `violation`.
+5. Call `foundry_history_append({cycle, stage: <dispatched-stage-alias>, comment})` summarizing what the subagent reported. The tool enforces that the stage alias matches the most recent sort's `route` — this is why step 2's `route` field matters.
+
+6. Call `foundry_git_commit({cycle, stage, description})` to record the stage's disk changes. **This is mandatory.** The next `foundry_sort` call will return `{route: 'violation', details: 'Uncommitted tool-managed files...'}` if WORK.md, WORK.history.yaml, or anything under `.foundry/` is dirty — the tool enforces one commit per stage.
+
+7. Return to step 1. Repeat until `done`, `blocked`, or `violation`.
+
+## Dispatch
+
+Every forge, quench, and appraise stage runs in a **fresh subagent**. Never inline the stage work in the orchestrator conversation — even if the chosen model matches the orchestrator's. The orchestrator's job is to route, dispatch, finalize, and log. Nothing else.
+
+### Choosing the subagent
+
+- If `foundry_sort` returned a `model` field, use it verbatim as `subagent_type`. It is already in `foundry-<slug>` form.
+- If no `model` field, dispatch to `general`.
+
+### Token handling
+
+The `token` returned by `foundry_sort` is an opaque signed string. Pass it through the dispatch prompt verbatim. **Never** invent, edit, or re-sign tokens. The subagent's first tool call must be `foundry_stage_begin({stage, cycle, token})` using this exact string; `stage_begin` verifies the signature, expiry, and single-use nonce.
+
+### Dispatch call shape
+
+Use the `task` tool:
+
+```
+task tool:
+  subagent_type: <model-slug-from-foundry_sort, or "general">
+  description: "Run <stage-alias> for <cycle-id>"
+  prompt: |
+    You are a Foundry stage agent. Invoke the <stage-base> skill and follow its instructions exactly.
+
+    Stage: <stage-alias>
+    Cycle: <cycle-id>
+    Token: <token-verbatim>
+    Working directory: <worktree>
+    File patterns (forge only): <file-patterns-list>
+
+    Your FIRST tool call MUST be foundry_stage_begin({stage, cycle, token}) using the values above.
+    Your LAST tool call MUST be foundry_stage_end({summary}).
+
+    When done, report back a brief summary. Do NOT call foundry_history_append, foundry_git_commit, or foundry_artefacts_add — the orchestrator handles all of those.
+```
+
+Substitute:
+- `<stage-alias>` — the full route string from `foundry_sort` (e.g., `forge:write-haiku`)
+- `<stage-base>` — the base of the alias
+- `<cycle-id>` — current cycle ID from WORK.md frontmatter
+- `<token-verbatim>` — exactly the `token` string from `foundry_sort` — no quoting transforms, no re-encoding
+- `<file-patterns-list>` — for forge stages, read via `foundry_config_artefact_type` and include so the subagent can avoid violations
+- `<worktree>` — current working directory
+
+### Missing subagent (fail-fast)
+
+`foundry_sort` verifies that `.opencode/agents/foundry-<slug>.md` exists before returning a `model`. If it doesn't, sort returns `{route: 'violation', details: 'Missing required subagent: ...'}`. Handle as in step 3 above.
+
+## Violation handling
+
+If `foundry_stage_finalize` returns `{error: 'unexpected_files', files}`:
+
+- The stage wrote outside its permitted `file-patterns`. This is unrecoverable within the current cycle.
+- Mark the target artefact `blocked`: `foundry_artefacts_set_status(file, 'blocked')`.
+- Add a feedback item describing the offense: `foundry_feedback_add(file, text: 'unexpected files: …', tag: 'violation')` (if permitted by your stage), or log in the history comment.
+- Do NOT attempt to re-run the stage — the subagent already consumed the stage slot.
+- Return to the cycle skill so the operator can intervene.
+
+If `foundry_sort` returns `{route: 'violation', details: 'Uncommitted tool-managed files...'}`:
+
+- A prior stage skipped step 6 (the micro-commit). The work is not lost — it's still in the working tree.
+- Call `foundry_git_commit({cycle, stage: <the-stage-that-just-ran>, description})` to record it.
+- Then call `foundry_sort` again. It should route normally.
+- If you genuinely don't know which stage produced the dirty files, read `WORK.history.yaml` — the most recent non-sort entry is the culprit.
 
 ## What you do NOT do
 
-- You do not make routing decisions yourself — the tool decides
-- You do not skip calling `foundry_sort`
-- You do not override the tool's output
-- You do not skip the history entry — every sort invocation gets a `sort` entry, and every completed stage gets a stage entry (e.g., `forge:write-haiku`). You are the sole writer of history.
+- You do not inline forge/quench/appraise work — always dispatch.
+- You do not mint, modify, or cache tokens — they come from `foundry_sort` and go straight to `foundry_stage_begin`.
+- You do not skip `foundry_stage_finalize` — it is the only mechanism that registers artefacts and detects file-pattern violations.
+- You do not let subagents call `foundry_history_append`, `foundry_git_commit`, or `foundry_artefacts_add` (the last has been removed anyway).

package/skills/upgrade-foundry/SKILL.md

@@ -27,12 +27,17 @@ Read all configuration files:
 - `foundry/laws/*.md` — global laws
 - `foundry/appraisers/*.md` — appraiser definitions
 
+Also scan `.opencode/agents/foundry-*.md` for agent-filename migration (see §2).
+
 For each file, parse the frontmatter and body content.
 
 ### 2. Detect what needs migration
 
 Check each file against the current expected format:
 
+**Agent files (v2.1 migration):**
+- Any `.opencode/agents/foundry-*.md` filename containing a `.` character? → needs renaming to all-dashes format. The v2.1 naming convention replaces both `/` and `.` in the model ID with `-`. For example, `foundry-github-copilot-claude-sonnet-4.6.md` must become `foundry-github-copilot-claude-sonnet-4-6.md`. The inner `model:` frontmatter field is **not** changed — only the filename.
+
 **Flows:**
 - Has `starting-cycles` field? If not → needs DAG migration
 - Has ordered numbered list under `## Cycles`? → needs conversion to unordered list
@@ -41,7 +46,7 @@ Check each file against the current expected format:
 - Has `targets` field? If not → needs target routing
 - Has `inputs.type` (`any-of`/`all-of`)? If `inputs` is a plain list → needs contract type
 - Has `hitl` in stages or frontmatter? → needs human-appraise migration
-- Has `human-appraise` config? Check format is correct
+- Has nested `human-appraise: {enabled, deadlock-threshold}`? → v2.2.1 flat-keys migration (see §4b)
 - Has `models` map? Check format
 
 **Artefact types:**
@@ -84,7 +89,48 @@ Present a grouped summary of all issues found:
 
 If nothing needs migration, say so and stop.
 
-### 4. Migrate flows
+### 4. Migrate agent files (v2.1)
+
+For each `.opencode/agents/foundry-*.md` file with a `.` in its filename:
+- Compute the new filename by replacing all `.` with `-` (keep the `.md` extension)
+- `git mv <old> <new>` to preserve history
+- Do **not** modify the file contents — the `model:` field inside retains its original dots
+
+After renaming, remind the user: **Restart OpenCode** for the new agent filenames to register.
+
+### 4a. v2.2.0 lifecycle upgrade
+
+Foundry v2.2.0 introduces a tool-enforced stage lifecycle (`stage_begin` / `stage_end` / `stage_finalize`) backed by a per-project state directory and HMAC-signed dispatch tokens. The upgrade is non-destructive — no WORK.md or artefact migration is required — but the project needs three small changes:
+
+1. **Create `.foundry/`** (if absent):
+   - `mkdir -p .foundry`
+   - The plugin auto-creates `.foundry/.secret` on first boot via `readOrCreateSecret`. You do not need to generate it by hand; just ensure the directory exists and is writable.
+2. **Gitignore `.foundry/`**:
+   - Ensure `.gitignore` contains a line `.foundry/` (append if missing; do not duplicate). The directory holds a per-worktree HMAC secret and transient active-stage state — neither should be committed.
+3. **Pre-existing state:** v2.2.0 is a fresh state system. There is no `active-stage.json` to migrate. If one happens to exist from a manually-aborted prior run, leave it alone — the new plugin treats its absence as "no active stage" and its presence as a legitimate in-flight stage.
+
+The `foundry_artefacts_add` tool has been removed in v2.2.0 — artefact registration now happens automatically via `foundry_stage_finalize`. No existing config references this tool, so there is nothing to migrate in `foundry/`.
+
+### 4b. v2.2.1 cycle-definition flat human-appraise keys
+
+v2.2.1 replaces the nested `human-appraise: {enabled, deadlock-threshold}` block in cycle definitions with three flat keys:
+
+```yaml
+human-appraise: <true|false>         # default: false — run human-appraise every iteration
+deadlock-appraise: <true|false>      # default: true — pull in human-appraise when LLM appraisers deadlock
+deadlock-iterations: <number>        # default: 5 — deadlock detection threshold
+```
+
+For each `foundry/cycles/*.md` whose frontmatter has the old nested form, migrate:
+
+- `human-appraise.enabled: true` → `human-appraise: true`
+- `human-appraise.enabled: false` (or missing) → `human-appraise: false`
+- `human-appraise.deadlock-threshold: N` → `deadlock-iterations: N`
+- Always add `deadlock-appraise: true` unless the user explicitly wants the stricter "no human ever" behavior (`deadlock-appraise: false` → deadlock marks the cycle `blocked`).
+
+The old nested form is no longer read. After migration, verify by asking: "cycle `<id>`: human-appraise every iteration? deadlock-appraise on? deadlock-iterations = N?".
+
+### 5. Migrate flows
 
 For each flow needing migration:
 - Show the current ordered cycle list
@@ -93,7 +139,7 @@ For each flow needing migration:
 - Present the proposed `starting-cycles` and confirm
 - Convert numbered `## Cycles` list to unordered
 
-### 5. Migrate cycles
+### 6. Migrate cycles
 
 For each cycle needing migration:
 
@@ -112,20 +158,20 @@ For each cycle needing migration:
 
 Remove `hitl` from stages and add `human-appraise` config if enabled.
 
-### 6. Migrate other config
+### 7. Migrate other config
 
 For artefact types, appraisers, laws, and validation with issues:
 - Present each issue with a suggested fix
 - Ask the user to confirm or adjust
 
-### 7. Present migration plan
+### 8. Present migration plan
 
 Before writing anything, show the complete list of changes:
 - Group by category
 - Show each file and the specific changes
 - Ask for confirmation
 
-### 8. Apply changes
+### 9. Apply changes
 
 - Update all affected files
 - Commit with message: `[foundry] upgrade: migrate to current format`