@really-knows-ai/foundry 2.3.0 → 2.3.2

package/skills/flow/SKILL.md

@@ -20,9 +20,10 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 1. Call `foundry_config_flow` with the flow ID — get the flow definition
 2. Call `foundry_git_branch` with the flow ID and a short description — create the work branch
 3. Determine the starting cycle:
-   - If only one starting cycle, use it
-   - If multiple starting cycles, check whether the user's request makes the choice obvious (e.g., "write a haiku" clearly maps to `create-haiku`)
-   - If ambiguous, prompt the user to choose
+   - Any cycle listed in the flow can be the starting cycle. The flow's `starting-cycles` list is a hint for when the user's request is ambiguous.
+   - Map the user's goal to a cycle by matching the requested output (e.g. "write a short story from the tennis haiku" → `create-short-story`; "write a haiku" → `create-haiku`).
+   - If the goal is ambiguous, prompt the user to choose from the flow's cycles, defaulting the recommendation to entries in `starting-cycles`.
+   - A cycle whose `inputs` contract cannot be satisfied from files already on disk should not be chosen as the starting cycle. If no other cycle matches, inform the user which input types are missing and offer to run a cycle that produces them first.
 4. Pre-check for an existing workfile (prevents silent data loss from an aborted prior session):
    a. Call `foundry_workfile_get`.
    b. If it returns `{error: ...}` (no WORK.md), proceed to step 5.
@@ -49,9 +50,10 @@ When a cycle completes (sort returns `done`):
    - Check input contracts for each
    - The user chooses which target to pursue (or which to pursue first)
 5. Set up the next cycle:
-   - Call `foundry_workfile_delete` to clear the completed cycle's WORK.md
+   - Call `foundry_workfile_delete` to clear the completed cycle's WORK.md.
    - Call `foundry_workfile_create` with **only** the flow ID, the next cycle ID, and the goal — do **not** pass `stages` or `maxIterations`. The orchestrate skill will detect `needsSetup` on its first call and bootstrap the rest of the frontmatter from the cycle definition.
-   - Execute the cycle by invoking the orchestrate skill
+   - Do **not** register the completed cycle's output as an input to the next cycle. The output file is on disk and the next cycle's forge discovers it through the input type's `file-patterns` — see the forge skill's input-discovery protocol.
+   - Execute the cycle by invoking the orchestrate skill.
 
 ## Completing a flow
 

package/skills/forge/SKILL.md

@@ -30,7 +30,11 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 3. `foundry_config_cycle` — understand what to produce and what inputs are available.
 4. `foundry_config_artefact_type` with the output type ID — get the artefact type definition, especially its `file-patterns`.
 5. `foundry_config_laws` — get all applicable laws (global + type-specific).
-6. If the cycle has inputs, read the input artefacts (read-only context).
+6. If the cycle declares `inputs`, discover input files by filesystem scan:
+   - For each type listed in `inputs`, call `foundry_config_artefact_type` to get its `file-patterns`.
+   - Glob the working tree against those patterns to enumerate candidate input files.
+   - Read the goal (from `foundry_workfile_get`) and select the files that are relevant to this run. If the goal names specific files or slugs, use those; if it describes a category ("all the auth tests"), select the matching subset; if it's open-ended, you may consume all candidates or ask the user when the set is clearly ambiguous.
+   - 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})`.
@@ -40,16 +44,22 @@ Forge runs inside an enforced stage. Your **first** and **last** tool calls are
 1. `foundry_stage_begin(...)`.
 2. `foundry_feedback_list` — find unresolved feedback for the artefact.
 3. Read the artefact file.
-4. If the cycle has inputs, read the input artefacts (read-only context).
+4. 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).
 5. For each unresolved feedback item, either:
    - Address it and call `foundry_feedback_action` (marks item `actioned`), or
    - Call `foundry_feedback_wontfix` with a justification — available only for `law:` / `human` tags (validation feedback must be actioned).
 6. Update the artefact file.
 7. `foundry_stage_end({summary})`.
 
-## File-pattern hygiene
+## Write invariant
 
-Writes during forge must match the output artefact type's `file-patterns`. Writing to any other path causes `foundry_stage_finalize` to return `{error: 'unexpected_files'}` and the orchestrator will mark the cycle's target artefact `blocked`. You will not get a retry. Plus `WORK.md` and `WORK.history.yaml` (managed by tools). Nothing else.
+Forge may only write to:
+- Files matching the output artefact type's `file-patterns`.
+- `WORK.md` and `WORK.history.yaml` (tool-managed).
+
+Everything else on disk — including files of the cycle's input types, files of unrelated artefact types, and files outside any artefact type — is read-only for this stage. This is not an honor-system rule: `foundry_stage_finalize` returns `{error: 'unexpected_files'}` and `sort`'s `checkModifiedFiles` routes a violation on the next call. Either outcome marks the cycle's target artefact `blocked` and you do not get a retry.
+
+When a cycle's output type overlaps with one of its input types (e.g. a `refine-haiku` cycle with input `haiku` and output `haiku`), the overlap is intentional: the cycle's job is to modify existing files of that type. The write invariant still holds — you may only touch files matching the output type's patterns, which in this case includes the files you read as inputs.
 
 ## Unresolved feedback
 
@@ -75,4 +85,4 @@ Feedback tagged `human` (from the human-appraise stage) takes absolute priority:
 - You do not evaluate or score the artefact.
 - You do not mark feedback as actioned unless you actually changed the artefact to address it.
 - You do not wont-fix validation feedback.
-- You do not modify input artefacts — they are read-only.
+- You do not write to any file outside the output artefact type's `file-patterns` (plus `WORK.md` / `WORK.history.yaml`). Input files are read-only unless the output type's patterns happen to cover them.