@really-knows-ai/foundry 1.0.0

package/skills/add-cycle/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: add-cycle
+type: atomic
+description: Creates a new foundry cycle within a foundry flow, specifying the output artefact type and any input artefact types.
+---
+
+# Add Cycle
+
+You help the user create a new foundry cycle and add it to an existing foundry flow. A foundry cycle produces one artefact type (read-write) and optionally reads from artefact types produced by earlier foundry cycles (read-only).
+
+## Protocol
+
+### 1. Identify the foundry flow
+
+From the user's prompt, identify which foundry flow this foundry cycle belongs to. If not specified, list available flows from `foundry/flows/` and ask.
+
+Verify the flow exists. If it doesn't, tell the user and ask if they want to create the foundry flow first (separate skill).
+
+### 2. Gather basics
+
+From the user's prompt, establish:
+- `id` — lowercase, hyphenated identifier for the foundry cycle
+- `name` — human-readable name
+- `output` — the artefact type this foundry cycle produces (must exist in `foundry/artefacts/`)
+- `inputs` — artefact types from earlier foundry cycles that this foundry cycle reads (may be empty)
+- A prose description of what this foundry cycle does
+
+If any of these are missing, ask.
+
+### 3. Gather model configuration
+
+For each stage in the cycle (forge, quench, appraise), ask the user if they want to specify a model:
+
+> Each stage can optionally run on a specific model for model diversity. Available models are registered as `foundry-*` agents by the Foundry plugin.
+>
+> For each stage, specify a model ID (e.g., `openai/gpt-4o`) or leave blank to use the session's default model:
+> - forge: ___
+> - quench: ___
+> - appraise: ___
+
+Only stages with an explicitly specified model are included in the `models` frontmatter map.
+
+### 4. Validate artefact types
+
+For `output` and each entry in `inputs`:
+- Verify the artefact type exists in `foundry/artefacts/<type>/definition.md`
+- If it doesn't, tell the user and ask if they want to create it first (separate skill)
+
+### 5. Validate against the foundry flow
+
+Read the flow definition from `foundry/flows/<flow-id>.md`. Check:
+
+- No existing foundry cycle in the foundry flow already outputs the same artefact type. Two foundry cycles producing the same type in one foundry flow is a conflict — the file modification enforcement can't distinguish which foundry cycle owns the files.
+- Each `input` artefact type is produced by an earlier foundry cycle in the foundry flow. If an input references an artefact type that no prior foundry cycle outputs, warn:
+
+> Input `<type>` is not produced by any earlier foundry cycle in this foundry flow. The artefact won't exist when this foundry cycle runs.
+>
+> Options:
+> 1. Add a foundry cycle that produces `<type>` before this one
+> 2. Remove `<type>` from inputs (this foundry cycle won't have that context)
+> 3. Proceed anyway (the artefact may exist from a previous foundry flow run)
+
+### 6. Check for id conflicts
+
+Read all existing cycle definitions in `foundry/cycles/*.md`.
+
+- Exact id match → hard conflict, must choose a different id
+
+### 7. Check for semantic overlap
+
+For foundry cycles already in this foundry flow, check whether the new foundry cycle overlaps in purpose:
+- Does another foundry cycle already transform the same inputs into a similar output?
+- Would the new foundry cycle's description make sense as a revision of an existing foundry cycle rather than a new one?
+
+If overlap is found, present it and ask the user to confirm the distinction is real.
+
+### 8. Draft the definition
+
+Present the foundry cycle definition to the user:
+
+```markdown
+---
+id: <id>
+name: <name>
+output: <artefact-type-id>
+inputs:
+  - <artefact-type-id>
+models:
+  appraise: <model-id>       # optional, only if specified
+---
+
+# <Name>
+
+<description — what this foundry cycle does, what it reads, what it produces>
+```
+
+Ask: does this capture the foundry cycle correctly?
+
+### 9. Determine position in foundry flow
+
+The foundry cycle needs a position in the foundry flow's ordered cycle list. Based on its inputs:
+- If no inputs: it can go first (or early)
+- If it reads from other foundry cycles: it must come after those foundry cycles
+
+Propose a position and confirm with the user:
+
+> This foundry cycle reads from `<inputs>`, which are produced by `<cycle-ids>`. It should go after those foundry cycles.
+>
+> Proposed order:
+> 1. <existing-cycle>
+> 2. <existing-cycle>
+> 3. <new-cycle> ← here
+>
+> Does this look right?
+
+### 10. Write files
+
+- Create `foundry/cycles/<id>.md` with the foundry cycle definition
+- Update `foundry/flows/<flow-id>.md` to add the foundry cycle at the agreed position
+
+### 11. Confirm
+
+Show the user the created/modified files and their contents.
+
+## What you do NOT do
+
+- You do not create foundry cycles that output an artefact type already produced by another foundry cycle in the same foundry flow
+- You do not write files without showing the user first
+- You do not skip artefact type validation
+- You do not create artefact types — that is a separate skill
+- You do not create foundry flows — that is a separate skill

package/skills/add-flow/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: add-flow
+type: atomic
+description: Creates a new foundry flow definition.
+---
+
+# Add Flow
+
+You help the user create a new foundry flow. A foundry flow is an ordered list of foundry cycles that transforms a request into finished artefacts.
+
+## Protocol
+
+### 1. Gather basics
+
+From the user's prompt, establish:
+- `id` — lowercase, hyphenated identifier
+- `name` — human-readable name
+- A prose description of what this foundry flow achieves end-to-end
+
+If any of these are missing, ask.
+
+### 2. Check for id conflicts
+
+Read all existing flow definitions in `foundry/flows/*.md`.
+
+- Exact id match → hard conflict, must choose a different id
+- Semantically similar name or description → warn and ask if the new foundry flow is genuinely distinct
+
+### 3. Determine foundry cycles
+
+Ask the user which foundry cycles this foundry flow should include, in order. List available cycles from `foundry/cycles/*.md` for reference.
+
+The user may:
+- Pick from existing foundry cycles
+- Describe foundry cycles that don't exist yet — note these and tell the user they'll need to create them with the add-cycle skill
+
+For each selected foundry cycle, verify it exists in `foundry/cycles/`. If it doesn't, note it as pending:
+
+> Foundry cycle `<id>` doesn't exist yet. I'll include it in the foundry flow definition, but you'll need to create it before running the foundry flow.
+
+### 4. Validate foundry cycle ordering
+
+Check that input dependencies are satisfied:
+- For each foundry cycle, its `inputs` must be produced as `output` by an earlier foundry cycle in the list
+
+If a dependency is unmet, warn:
+
+> Foundry cycle `<cycle-id>` reads from `<type>`, but no earlier foundry cycle produces it. Either reorder or add a foundry cycle that produces `<type>` first.
+
+### 5. Draft the definition
+
+Present the foundry flow definition to the user:
+
+```markdown
+---
+id: <id>
+name: <name>
+---
+
+# <Name>
+
+<description>
+
+## Cycles
+
+1. <cycle-id>
+2. <cycle-id>
+```
+
+Ask: does this capture the foundry flow correctly?
+
+### 6. Write the file
+
+Create `foundry/flows/<id>.md` with the agreed definition.
+
+### 7. Confirm
+
+Show the user the created file and its contents.
+
+## What you do NOT do
+
+- You do not create foundry cycles — that is a separate skill
+- You do not write files without showing the user first
+- You do not skip dependency validation

package/skills/add-law/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: add-law
+type: atomic
+description: Creates a new law, checking for conflicts with existing laws.
+---
+
+# Add Law
+
+You help the user create a new law. You ensure it's well-scoped, doesn't conflict with existing laws, and ends up in the right file.
+
+## Protocol
+
+### 1. Determine scope
+
+If the user specifies where the law applies:
+- "global law" → goes in `foundry/laws/` (ask which file, or create a new one)
+- "law for X artefacts" → goes in `foundry/artefacts/<type>/laws.md`
+
+If the user doesn't specify, ask:
+
+> Should this law apply globally to all artefact types, or to a specific type?
+
+If they name a type, verify it exists in `foundry/artefacts/`. If it doesn't, tell them and ask if they want to create the artefact type first.
+
+### 2. Draft the law
+
+Write the law following the standard format:
+
+```markdown
+## <law-id>
+
+<What this law checks — one or two sentences.>
+
+Passing: <What a passing artefact looks like.>
+Failing: <What a failing artefact looks like.>
+```
+
+The `law-id` (heading) should be:
+- Lowercase, hyphenated
+- Short but descriptive
+- Unique across all laws (global and type-specific)
+
+### 3. Check for conflicts
+
+Read all existing laws that would apply to the same artefact types:
+- All files in `foundry/laws/` (global)
+- `foundry/artefacts/<type>/laws.md` if the law is type-specific
+- If the law is global, also read all `foundry/artefacts/*/laws.md` since a global law applies everywhere
+
+For each existing law, check:
+- Does the new law contradict an existing law? (e.g., "must be formal" vs "must be conversational")
+- Does the new law duplicate an existing law? (same criterion, different wording)
+- Does the new law overlap with an existing law? (partially covers the same ground)
+
+If any conflict is found, present it to the user:
+
+> The new law `<new-id>` may conflict with existing law `<existing-id>`:
+> - New: <summary of new law>
+> - Existing: <summary of existing law>
+> - Conflict: <what the conflict is>
+>
+> Options:
+> 1. Proceed anyway (both laws will apply)
+> 2. Replace the existing law with the new one
+> 3. Rephrase the new law to avoid the conflict
+> 4. Cancel
+
+### 4. Refine with the user
+
+Present the drafted law to the user before writing it. Ask:
+
+> Here's the draft law:
+>
+> ## <law-id>
+>
+> <law content>
+>
+> Does this capture what you want, or should we adjust the wording?
+
+Iterate until the user is happy.
+
+### 5. Write the law
+
+Append the law to the appropriate file:
+- Global: the specified file in `foundry/laws/`, or a new file
+- Type-specific: `foundry/artefacts/<type>/laws.md`
+
+If the target file doesn't exist yet, create it with a top-level heading.
+
+### 6. Verify uniqueness
+
+After writing, confirm the law id is unique. If there's a collision, ask the user to rename.
+
+## What you do NOT do
+
+- You do not write the law without showing the user first
+- You do not skip the conflict check
+- You do not silently overwrite existing laws
+- You do not create artefact types — that is a separate skill

package/skills/appraise/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: appraise
+type: atomic
+description: Subjective evaluation of an artefact against laws via multiple independent appraisers.
+---
+
+# Appraise
+
+You orchestrate subjective appraisal of an artefact by dispatching independent sub-agent appraisers, then consolidating their feedback into WORK.md.
+
+## Appraiser configuration
+
+Appraiser personalities are defined in `foundry/appraisers/` (the appraiser directory). Each markdown file defines:
+- `id` — identifier
+- `model` — (optional) specific model ID to use for this appraiser, overriding the cycle-level appraise model
+
+The artefact type definition (`foundry/artefacts/<type>/definition.md`) controls how appraisers are assigned via its `appraisers` frontmatter:
+
+```yaml
+appraisers:
+  count: 3                              # how many appraisers (default: 3)
+  allowed: [pedantic, pragmatic]        # which personalities (default: all available)
+```
+
+### Appraiser selection
+
+1. Read the `appraisers` config from the artefact type definition
+2. If `allowed` is specified, filter to only those personalities. Otherwise use all in `foundry/appraisers/`.
+3. If `count` is omitted, default to 3
+4. Distribute evenly across available personalities for maximum diversity:
+   - 3 appraisers, 3 personalities → 1 of each
+   - 6 appraisers, 3 personalities → 2 of each
+   - 4 appraisers, 3 personalities → 2, 1, 1 (round-robin)
+5. If count > available personalities, wrap around (same personality, still independent sub-agents)
+
+Model diversity is configured at two levels: the cycle definition sets a default model for the appraise stage (which should differ from the forge model), and individual appraisers can optionally override with their own model. If no models are configured, the session's default model is used — personality diversity still adds value but model diversity is lost.
+
+## Protocol
+
+1. Read `WORK.md` — identify the artefact to appraise and its type
+2. Read all files in `foundry/laws/` — identify global laws
+3. Read `foundry/artefacts/<type>/laws.md` — identify type-specific laws (if it exists)
+4. Read `foundry/artefacts/<type>/definition.md` — for context and appraiser config
+5. Select appraisers (see Appraiser selection above)
+6. Dispatch each appraiser as a sub-agent (see Dispatch below)
+7. Collect results from all appraisers
+8. Consolidate:
+   - 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>`
+10. If no appraiser found any issues, the artefact clears appraisal
+
+## Dispatch
+
+Each appraiser is dispatched as an independent sub-agent. The sub-agent receives a prompt containing:
+- The appraiser's personality (from their definition file)
+- The artefact content
+- All applicable laws (global + type-specific)
+- Instructions to evaluate the artefact against each law and return issues as a structured list
+
+### Model resolution
+
+For each appraiser being dispatched, resolve the model in this order:
+1. **Appraiser `model` field** — if the appraiser definition specifies a `model`, use it
+2. **Cycle `models.appraise`** — if the cycle definition specifies a model for the appraise stage, use it (read from WORK.md frontmatter or the cycle definition)
+3. **Default** — use `subagent_type: "general"` (inherits the session's model)
+
+If a model is resolved (options 1 or 2), convert it to an agent name: `foundry-<provider-id>-<model-key>` (e.g., `openai/gpt-4o` → `foundry-openai-gpt-4o`). If no agent with that name exists, **hard fail** with an error:
+
+> Appraiser `<appraiser-id>` specifies model `<model-id>` but no matching agent `foundry-<agent-name>` is registered. Check your OpenCode provider config.
+
+### OpenCode dispatch
+
+Use the Task tool to dispatch each appraiser:
+
+```
+Task tool call for each appraiser:
+- subagent_type: "<resolved agent name>" or "general" if no model specified
+- prompt: contains personality, artefact, laws, evaluation instructions
+```
+
+Dispatch all appraisers in parallel (multiple Task calls in a single response).
+
+### Sub-agent prompt template
+
+```
+You are an appraiser. Your personality:
+
+<contents of foundry/appraisers/<id>.md>
+
+Evaluate the following artefact against each law below. For each law, either:
+- Note no issues (pass)
+- Describe the issue, quoting evidence from the artefact
+
+## Artefact
+
+<artefact content>
+
+## Laws
+
+<all applicable laws>
+
+## Output
+
+Return a list of issues. For each issue:
+- law: <law-id>
+- issue: <description>
+- evidence: <quote from artefact>
+
+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:
+
+- `[x]` actioned items: appraiser checks whether the change actually addresses the issue
+  - If yes: mark `| approved`
+  - If no: mark `| rejected: <reason>` (item is effectively re-opened)
+- `[~]` wont-fix items: appraiser reads the justification
+  - If the justification is sound: mark `| approved`
+  - If not: mark `| rejected` (item is effectively re-opened)
+
+## History
+
+After completing the appraisal consolidation, append an entry to `WORK.history.yaml`:
+
+```yaml
+- timestamp: "<ISO 8601 UTC>"
+  cycle: <current-cycle-id>
+  stage: <alias>
+  iteration: <current iteration from history>
+  comment: <brief summary, e.g., "3 issues found across 2 appraisers" or "No issues found, cycle complete">
+```
+
+## What you do NOT do
+
+- 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

package/skills/cycle/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: cycle
+type: composite
+description: Runs a foundry cycle by delegating all routing to the sort skill.
+composes: [sort, forge, quench, appraise, hitl]
+---
+
+# Cycle
+
+A foundry cycle reads its definition from `foundry/cycles/<cycle-id>.md`, sets up WORK.md for routing, then hands control to the sort skill which drives the forge → quench → appraise loop.
+
+## Cycle definition
+
+The cycle definition (`foundry/cycles/<cycle-id>.md`) specifies:
+- `output` — the artefact type this foundry cycle produces (read-write)
+- `inputs` — artefact types from previous foundry cycles that are read-only context
+- `stages` — (optional) explicit stage list with aliases in `base:alias` format (e.g., `[forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]`)
+- `hitl` — (optional) configuration for human-in-the-loop stages, including prompts
+- `models` — (optional) map of stage base names to model IDs for multi-model routing (e.g., `{ appraise: openai/gpt-4o }`). Stages not listed use the session's default model. If a specified model has no matching `foundry-*` agent, the cycle fails with an error.
+
+If `stages` is not provided, the cycle skill generates default aliases from the cycle id and artefact type.
+
+## Starting a foundry cycle
+
+1. Read the cycle definition from `foundry/cycles/<cycle-id>.md`
+2. Read the output artefact type definition from `foundry/artefacts/<type>/definition.md`
+3. Determine the stage route using `base:alias` format:
+   - Build the stages list from the cycle definition's `stages` field if present
+   - Otherwise, generate defaults: always `forge`, add `quench` if `foundry/artefacts/<type>/validation.md` exists, always `appraise`
+   - Cycle definitions can include `hitl` entries in the stages list for human-in-the-loop checkpoints
+   - Examples:
+     - `[forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]`
+     - `[forge:write-petition, appraise:evaluate-petition]`
+     - `[forge:draft-proposal, hitl:review-proposal, appraise:evaluate-proposal]`
+4. Update WORK.md frontmatter:
+   - Set `cycle` to the cycle id
+   - Set `stages` to the determined route (e.g., `[forge:write-haiku, quench:check-syllables, appraise:evaluate-quality]`)
+   - Set `max-iterations` (default 3, or from cycle definition if overridden)
+   - If the cycle definition has a `models` map, set `models` in WORK.md frontmatter (e.g., `models: { appraise: openai/gpt-4o }`)
+5. Invoke the sort skill
+
+## Sort drives everything
+
+Once sort is invoked, it runs `scripts/sort.js` to determine the next stage, invokes the corresponding skill, then runs sort again. This repeats until sort returns `done` or `blocked`.
+
+The cycle skill does not contain routing logic — sort owns all of that.
+
+## Completing a foundry cycle
+
+When sort returns `done`:
+- Update the artefact status in WORK.md to `done`
+- Return control to the foundry flow skill
+
+When sort returns `blocked`:
+- Update the artefact status in WORK.md to `blocked`
+- Return control to the foundry flow skill (the foundry flow decides how to handle it)
+
+## HITL stages
+
+Cycle definitions can include `hitl` entries in their stages list to pause for human input. The cycle definition's `hitl:` config section specifies prompts shown to the human at each hitl checkpoint.
+
+When sort routes to a `hitl` stage:
+- The hitl skill presents the configured prompt to the human
+- The human provides feedback, which is recorded in WORK.md and WORK.history.yaml
+- Sort then determines the next stage based on the feedback
+
+HITL stages follow the same file modification rules as quench/appraise — only WORK.md and WORK.history.yaml may be modified.
+
+## Micro commits
+
+Every stage must end with a micro commit. Commit message format: `[<cycle-id>] <base>:<alias>: <brief description>`
+
+Examples:
+- `[haiku-creation] forge:write-haiku: initial draft`
+- `[haiku-creation] quench:check-syllables: checked syllable pattern`
+- `[haiku-creation] forge:write-haiku: addressed validation feedback`
+- `[haiku-creation] hitl:review-draft: recorded human feedback`
+
+## File modification enforcement
+
+File modification enforcement is handled automatically by the sort script (`scripts/sort.js`). Before routing to the next stage, sort checks the git diff from the last commit against allowed file patterns:
+
+- After forge: output artefact file patterns + WORK.md + WORK.history.yaml
+- After quench/appraise/hitl: only WORK.md + WORK.history.yaml
+- Input artefact files are never allowed (read-only)
+
+Sort reads the cycle definition and artefact type definition to determine allowed patterns. If a violation is detected, sort returns `violation` (with details on stderr) and the cycle halts.
+
+A violation is a hard stop. The foundry cycle sets artefact status to `blocked` and surfaces the issue to the human.
+
+## Feedback states
+
+```
+open         - [ ] issue #tag                              → needs generator action
+actioned     - [x] issue #tag                              → needs approval
+wont-fix     - [~] issue #tag | wont-fix: <reason>         → needs approval (appraisal only)
+approved     - [x] issue #tag | approved                   → resolved
+approved     - [~] issue #tag | wont-fix: <reason> | approved → resolved
+rejected     - [x] issue #tag | rejected: <reason>         → re-opened
+rejected     - [~] issue #tag | wont-fix: <reason> | rejected → re-opened
+```
+
+Tag types: `#validation` (from quench), `#law:<law-id>` (from appraise), `#hitl` (from human) — indicates the source and category of feedback.
+
+## What you do NOT do
+
+- You do not make routing decisions — sort does that
+- You do not change the laws mid-cycle
+- You do not decide the artefact is "close enough" — it passes or it doesn't
+- You do not proceed past a file modification violation
+- You do not modify input artefacts — they are read-only

package/skills/flow/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: flow
+type: composite
+description: Orchestrates foundry cycles on a work branch, driven by a foundry flow definition.
+composes: [cycle]
+---
+
+# Flow
+
+A foundry flow reads a flow definition from `foundry/flows/`, creates a work branch, initialises WORK.md, and executes each foundry cycle in sequence.
+
+## Starting a foundry flow
+
+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
+   - Empty feedback section
+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
+
+## Completing a foundry flow
+
+When the foundry flow is complete, the branch contains:
+- The finished artefacts
+- The full git history of micro commits showing every stage
+
+The human decides whether to merge, open a PR, or discard.
+
+## What you do NOT do
+
+- You do not skip foundry cycles
+- You do not reorder foundry cycles
+- You do not modify artefacts directly — only foundry cycles modify artefacts
+- You do not delete or rewrite feedback history in WORK.md during the foundry flow

package/skills/forge/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: forge
+type: atomic
+description: Produces or revises an artefact, guided by WORK.md and the foundry cycle definition.
+---
+
+# Forge
+
+You produce or revise artefacts. You read WORK.md to understand the goal and feedback, and the foundry cycle definition to understand what you're producing and what inputs you can read.
+
+## Protocol
+
+### First generation (no artefact registered in WORK.md yet)
+
+1. Read `WORK.md` — understand the goal
+2. Read the foundry cycle definition from `foundry/cycles/<cycle-id>.md` — understand what to produce and what inputs are available
+3. Read the output artefact type definition from `foundry/artefacts/<type>/definition.md`
+4. Read all files in `foundry/laws/` for global laws
+5. Read `foundry/artefacts/<type>/laws.md` for type-specific laws (if it exists)
+6. If the foundry cycle has inputs, read the input artefacts (read-only context)
+7. Produce the artefact, respecting all applicable laws from the start
+8. Write the artefact to the location specified in the artefact type definition
+9. Register the artefact in the WORK.md artefacts table (file, type, cycle, status: draft)
+
+### Revision (feedback exists in WORK.md)
+
+1. Read `WORK.md` — find unresolved feedback items for the 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:
+   - Address it and mark as `[x]` (actioned)
+   - Mark as `[~]` with justification if you believe the feedback should not be actioned: `- [~] <issue> #law:<id> | wont-fix: <reason>`
+5. Update the artefact file
+6. Wont-fix is only available for `#law:` feedback (subjective appraisal). Validation feedback (`#validation`) must be actioned — deterministic rules are not negotiable.
+
+## Unresolved feedback
+
+An item is unresolved if it is:
+- `[ ]` — open, not yet addressed
+- `[x] ... | rejected: ...` — actioned but rejected by appraiser, effectively re-opened
+- `[~] ... | rejected` — wont-fix rejected by appraiser, effectively re-opened
+
+An item is resolved if it is:
+- `[x] ... | approved`
+- `[~] ... | approved`
+
+## History
+
+After completing your work (first generation or revision), append an entry to `WORK.history.yaml`:
+
+```yaml
+- timestamp: "<ISO 8601 UTC>"
+  cycle: <current-cycle-id>
+  stage: <alias>
+  iteration: <n>
+  comment: <brief description of what you did>
+```
+
+The `<alias>` is the full alias received from sort (e.g., `forge:write-haiku`). Use it exactly as given.
+
+The iteration number is one more than the count of existing `forge` entries for this cycle in the history.
+
+## Feedback tagged `#hitl`
+
+Feedback tagged `#hitl` (human-in-the-loop) is treated the same as any other open feedback. Address it or wont-fix it using the same rules as other feedback items.
+
+## What you do NOT do
+
+- You do not evaluate or score the artefact
+- You do not add feedback — that is the quench skill's and appraise skill's job
+- 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