froid-loop 0.11.1__py3-none-any.whl

froid_loop/data/skills/froid-loop-resolve/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: froid-loop-resolve
+description: 'Interactive escalation-resolution workflow for the froid-loop orchestrator. A froid-loop run paused on a CRITICAL escalation (a contradiction or gap a dev/review session could not safely resolve alone); you and the human disambiguate the frozen spec so the story can be re-driven. Invoked as /froid-loop-resolve <story-key>. Unlike the automated dev/review sessions this session is interactive — a human is present and you SHOULD ask.'
+---
+
+# froid-loop Escalation Resolution
+
+A `froid-loop` run drove a story through dev → review, a session raised a
+**CRITICAL escalation** (work could not proceed safely — usually a contradiction
+or an unanswered question in the _frozen spec_), and the orchestrator paused the
+whole run for a human. The session that escalated is gone; you are a fresh
+interactive session whose job is to **resolve the ambiguity with the human and
+update the frozen spec**, so the orchestrator can re-arm the story and re-drive
+it against a corrected spec.
+
+This is **interactive**: a human IS present. Ask questions, present options,
+recommend — but the human makes the call. (`$FROID_LOOP_MODE` is intentionally
+unset for this session; the never-ask automation rules do NOT apply.)
+
+## Identity & I/O contract
+
+These environment variables are set:
+
+- `$FROID_LOOP_RUN_DIR` — the paused run's directory.
+- `$FROID_LOOP_STORY_KEY` — the escalated story key (also your invocation argument).
+- `$FROID_LOOP_RESOLVE_CONTEXT` — path to a `context.json` written for you.
+
+**Read `$FROID_LOOP_RESOLVE_CONTEXT` FIRST.** Its schema:
+
+```json
+{
+  "story_key": "6-4-cli-list-command",
+  "run_id": "20260613-111429-6a14",
+  "spec_file": "/abs/path/to/_froid-output/implementation-artifacts/spec-<story>.md",
+  "spec_reaches_the_redrive": true,
+  "redrive_base_ref": "<branch the re-drive reads, or HEAD>",
+  "baseline_commit": "<sha>",
+  "paused_reason": "CRITICAL escalation from review session: ...",
+  "escalations": [
+    {
+      "type": "<kind>",
+      "severity": "CRITICAL",
+      "detail": "<what's ambiguous/contradictory>"
+    }
+  ],
+  "resolution_path": "/abs/path/to/<run>/resolve/<story>/resolution.json"
+}
+```
+
+**`spec_reaches_the_redrive` says whether your edit has a future.** The re-drive
+reads one tree; `spec_file` may name another. Under worktree isolation the run's mount
+is discarded before the re-drive reads anything, so a spec inside that mount is
+destroyed with it. When this field is `false`, every write to `spec_file` still
+SUCCEEDS and is then thrown away — worse than not editing at all, because the session
+looks resolved. `null` means the task has no spec on record: there is nothing to edit
+and step 4 does not apply.
+
+**`redrive_base_ref` tells you which of the two remedies applies.** Read it before you
+tell the human anything: a branch name and `HEAD` mean opposite things.
+
+Do not skip the edit when it is `false` — the corrected spec is what gets carried
+over, and it is the clearest statement of what you and the human agreed. Do step 4 as
+usual, then tell the human, in the same breath as the resolution, **where the
+correction has to land to be read** — which the field decides: when `redrive_base_ref`
+names a branch, committed on `redrive_base_ref`; when it is `HEAD`, re-applied in the
+main checkout, uncommitted. The two paragraphs below carry each arm.
+
+Be precise about this, because the two obvious moves both fail silently:
+
+- Committing from the **main checkout** cannot include the file you edited — it lives
+  in a linked unit worktree, which is a separate working tree.
+- Committing on the **unit's own branch** does not reach the re-drive either. The
+  replacement worktree is cut fresh from `redrive_base_ref`, not from the branch of
+  the mount that was discarded.
+
+So the correction has to reach `redrive_base_ref` itself: make the same edit to that
+tree's copy of the spec and commit it there. The orchestrator names the same ref when
+it re-arms; say it here so they hear it before they close the session rather than
+after.
+
+**When `redrive_base_ref` is `HEAD`, do not tell them to commit anything.** That means
+the re-drive runs in the **main checkout** and reads its WORKING TREE, so an edit there
+is read as-is. `spec_reaches_the_redrive: false` beside a `HEAD` base is the opposite
+problem from the one above: `spec_file` points into a worktree this run has STOPPED
+using, because its isolation policy changed while the story sat escalated. The remedy
+is to make the same edit to the main checkout's copy of the spec — no commit, no
+branch. Telling them to commit here sends them to a tree the re-drive does not read,
+which is the same lost work in the other direction.
+
+In **stories mode** (folder+id dispatch) the context also carries a `stories`
+block — the manifest intent for this story, so you can see WHAT it is meant to do
+without hunting for it:
+
+```json
+{
+  "stories": {
+    "spec_folder": "_froid-output/epic-1",
+    "story": {
+      "id": "6-4-cli-list-command",
+      "title": "CLI list command",
+      "description": "…",
+      "spec_checkpoint": false,
+      "done_checkpoint": false,
+      "invoke_dev_with": "…free-text planner→dev note, or ''…"
+    },
+    "sentinel": {
+      "kind": "unresolved",
+      "path": ".../stories/6-4-cli-list-command-unresolved.md",
+      "blocking_condition": "…the reason planning halted…"
+    }
+  }
+}
+```
+
+The `sentinel` sub-block is present ONLY when the escalated story is a **sentinel**
+(see the stories-mode section below); an ordinary escalation omits it.
+
+Your **output marker** is the file at `resolution_path`. Writing it is the LAST
+action of a successful resolution. Schema:
+
+```json
+{
+  "story_key": "<key>",
+  "decision": "<one or two sentences: the rule you and the human chose>",
+  "spec_file": "<the spec you edited>",
+  "spec_updated": true,
+  "restore_patch": "<optional: path to a saved intent-gap patch to re-apply>"
+}
+```
+
+`restore_patch` is **optional** and used only for the intent-gap patch-restore
+case below — omit it entirely for an ordinary resolution.
+
+## What you MUST do
+
+1. **Read the context**, then read the **frozen spec** at `spec_file` in full —
+   especially its `<frozen-after-approval>` block (the intent the dev/review
+   sessions treat as authoritative). The escalation is almost always that this
+   block is silent on, or contradicts, a case the implementation hit.
+2. **Present the escalation plainly** to the human: what is ambiguous or
+   contradictory, why it blocks safe implementation, and **2–4 concrete
+   resolution options** with a clear recommendation and its trade-offs. Keep it
+   tight — quote the relevant spec lines.
+3. **Get the human's decision.** Ask follow-ups if the choice is unclear. Do not
+   invent requirements; if the human is unsure, help them reason, don't guess.
+4. **Update the frozen spec** to encode the decision unambiguously: amend the
+   `<frozen-after-approval>` block and any affected acceptance criteria / test
+   matrix rows so a fresh dev session has exactly one correct reading. Make the
+   smallest change that removes the ambiguity. You MAY use the `froid-spec` or
+   `froid-correct-course` skills if a larger spec change is warranted. **If
+   `spec_reaches_the_redrive` is `false`, make the same edit and then say plainly
+   that this copy is not the one the re-drive reads, and name the remedy that
+   `redrive_base_ref` selects: on a branch, the correction must be
+   committed on `redrive_base_ref`; on `HEAD`, it must be re-applied in the main
+   checkout, uncommitted** — an unflagged edit here is lost work, and a commit in the
+   wrong tree or on the wrong branch is lost work that looks done.
+5. **Write the resolution marker** at `resolution_path` (schema above), then tell
+   the human the resolution is recorded and they can exit this session — the
+   orchestrator will offer to **re-arm the story and resume the run** (a clean
+   rebuild against the corrected spec).
+
+## Special case: a review-stage `intent gap` with a saved patch
+
+When the escalation came from the **review step** halting on an `intent gap`, the
+dev session first **saved its attempted change as a patch file** (in the
+implementation-artifacts folder) before reverting the tree — the escalation
+`detail` and the spec's `## Review Triage Log` reference the patch path. That
+patch is concrete evidence: it shows exactly which reading of the intent the run
+implemented.
+
+**First check `restore_supported` in the context file.** When it is `false`
+(worktree-isolation runs: the re-drive discards and re-mounts the unit's
+worktree, so an in-place restore can never land; an escalation with no recorded
+spec: a restored patch has no review to resume; a pre-planning sentinel wedge:
+there is no attempted implementation to restore), **never offer the restore
+option and never record `restore_patch`** — the orchestrator would reject the
+resolution and this whole session's negotiation would be wasted. The patch is
+still available as evidence.
+
+Use the patch two ways:
+
+- **As evidence.** Read the patch (and the diff it represents) to see what the
+  guessed reading produced — often clearer input for writing the clarification
+  than the questions alone.
+- **When the attempted reading was actually correct.** Sometimes the run's guess
+  is the right one and only the _intent_ was silent. Present this as an explicit
+  option to the human: _"the implementation read it as X, which is in fact what we
+  want — amend the intent to say X, and resume **review** on the already-written
+  change instead of re-implementing it."_ If the human chooses this:
+  1. Still **amend the intent** in the spec so it unambiguously says X (step 4
+     above is unchanged — the frozen intent must match the restored code).
+  2. Add **`"restore_patch": "<the saved patch path>"`** to `resolution.json`
+     (copy the path verbatim from the escalation detail / triage log).
+
+  The orchestrator then re-arms the spec to `in-review`, re-applies the patch onto
+  the baseline, and re-dispatches — the session resumes at the review step on the
+  restored diff. **Do NOT `git apply` the patch yourself and do NOT set the spec
+  status** — the orchestrator does both deterministically at re-arm.
+
+  **The restore must not overlap resolution commits.** Re-arm advances the
+  re-drive's baseline to the branch's post-resolve HEAD, but the saved patch was
+  diffed from the ORIGINAL baseline — so if this session left commits that touch
+  the patch's own files, the restore's `git apply` fails and the story
+  re-escalates (loudly, by design: the orchestrator never silently merges the
+  resolution with the stale attempt). If the resolution work already includes or
+  supersedes the attempted change, **omit `restore_patch`** — the commits survive
+  re-arm as the re-drive's starting point, so a from-scratch re-drive builds
+  directly on them.
+
+If the attempted reading was wrong (the common case), omit `restore_patch`
+entirely: the orchestrator re-drives from scratch against the corrected intent.
+
+## What you MUST NOT do
+
+- **Do NOT** write the orchestrator's `result.json` — that is a dev/review
+  artifact; this is not one of those sessions.
+- **Do NOT** change `sprint-status.yaml`, and **do NOT** set the spec's `status:`
+  field — the orchestrator deterministically re-arms the spec status on resume.
+  Edit spec **content** only.
+- **Do NOT** implement the story, write feature code, run tests, or commit. Your
+  job ends at a corrected spec + the resolution marker. That holds when
+  `spec_reaches_the_redrive` is `false` too: landing the corrected spec where the
+  re-drive reads it is the HUMAN's step — committing it on `redrive_base_ref` when that
+  names a branch, re-applying it in the main checkout when it is `HEAD`. Tell them it
+  is required, and which one; do not do it yourself.
+- **Do NOT** widen scope. Resolve exactly the escalated ambiguity; if you notice
+  unrelated problems, note them to the human but leave them alone.
+
+## Stories mode: sentinels and the preserved copy
+
+In stories mode a story that could not even be **planned** — the dev session hit
+a contradiction or gap before it could write a real spec — leaves a fixed-slug
+**sentinel** file instead of a frozen spec: `<id>-unresolved.md` (the intent was
+too ambiguous to plan) or `<id>-ambiguous.md` (more than one story spec matched
+the id). The context's `stories.sentinel` block names it and carries the
+`blocking_condition` the session recorded.
+
+A sentinel is **not a spec you edit** — there is no plan or `<frozen-after-approval>`
+block inside it. So for a sentinel:
+
+- **Do not try to amend a frozen spec** (step 4's "edit the frozen spec" does not
+  apply — there isn't one). Instead resolve the _upstream_ ambiguity so a fresh
+  planning pass can succeed: usually that means clarifying `SPEC.md` (the epic
+  spec) or this story's entry in `stories.yaml` — the `title` / `description` /
+  `invoke_dev_with` the planner reads — with the human.
+- **`redrive_base_ref` decides where that upstream edit has to land, exactly as it
+  does for a spec.** `spec_reaches_the_redrive` does not answer this — it is about
+  `spec_file`, which for a sentinel is the file being deleted. The artifacts you
+  actually edit are `SPEC.md` / `stories.yaml`, and they face the same question: when
+  `redrive_base_ref` names a **branch**, the re-drive mounts a fresh worktree and
+  re-plans from that branch's COMMITTED tree, so an uncommitted edit is invisible and
+  the re-plan mints the same sentinel again — tell the human it has to be committed
+  there. When it is `HEAD`, the re-drive re-plans in the main checkout's working tree
+  and the edit is read as-is — do not tell them to commit. The orchestrator re-arms on
+  the same rule and will hold the resume until the branch carries it.
+- On **re-arm** the orchestrator does NOT flip the sentinel to `ready-for-dev`
+  (there is no plan to route to). It **preserves a copy** of the sentinel under
+  `{run}/sentinels/<id>-<kind>.md` as a breadcrumb, **deletes** the sentinel, and
+  the next dispatch re-plans the story from scratch (leg 1 again for a
+  `spec_checkpoint` story). You do not touch the sentinel file yourself.
+- Write the resolution marker as usual once the human has decided how to
+  disambiguate; set `spec_file` to whatever you edited (e.g. `SPEC.md`), or omit
+  it if the fix was entirely in `stories.yaml`.
+
+### Not a sentinel: more than one file matches the id
+
+Distinct from the single-file `<id>-ambiguous.md` sentinel above: when **more
+than one** file in `stories/` matches `<id>-*.md` (say `3-login.md` AND
+`3-signup.md`), the id itself is ambiguous _on disk_ and the orchestrator wedges
+the story without picking either file. You can recognize this state by the
+escalation reason (`ambiguous story file match: <names>`) and by what the
+context does NOT have: no `stories.sentinel` block and no single spec path.
+
+The auto-clear above does **not** apply — there is no sentinel to preserve and
+delete, and re-arming alone just re-wedges on the same duplicates. The
+resolution IS the cleanup: with the human, decide which file is the story's real
+spec and remove or rename the other (merge content first if both carry real
+work; renaming must move it out of the `<id>-*` pattern or to another id).
+Exactly one match re-dispatches that spec; zero matches re-plans from scratch.
+Then write the resolution marker as usual — re-arm + resume takes it from there.
+
+## If you cannot resolve it
+
+If the human defers, the information needed is genuinely unavailable, or the
+right fix is out of scope for a spec edit (e.g. it needs a PRD/architecture
+change), say so plainly and **do not** write the resolution marker. Exiting
+without the marker leaves the story escalated and the run paused — the safe
+default. The orchestrator will not re-arm a story with no recorded resolution.

froid_loop/data/skills/froid-loop-setup/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: 'froid-loop-setup'
+description: Sets up FROID Loop Skills module in a project. Use when the user requests to 'install froid-loop module', 'configure FROID Loop Skills', or 'setup FROID Loop Skills'.
+---
+
+# Module Setup
+
+## Overview
+
+Installs, configures, **and upgrades** the froid-loop module in a project.
+
+This module is unusual: alongside its automation skills it relies on the **froid-loop orchestrator tool** — the Python program that actually drives the loop — installed as the `froid-loop` package from its public Git repository. The skills do nothing on their own.
+
+**The FROID installer owns `_froid/` registration; this skill does not.** When froid-loop is installed through the FROID installer (`npx froid-plane install`), the installer stages the skills under `_froid/froid-loop/`, writes that module's own config and help files, records it in `_froid/_config/` (manifest, skill manifest, files manifest), and rebuilds the `/froid-help` catalog. It regenerates the central `_froid/config.toml` on every run, so nothing outside the installer should write there.
+
+So this skill's job is the part the installer structurally **cannot** do:
+
+1. Install **or upgrade** the orchestrator tool (the installer copies skill directories only — it cannot carry a Python package).
+2. Run `froid-loop init` to register the per-CLI hooks, lay down the bundled skills, and write `.froid-loop/policy.toml` + gitignore entries.
+3. Preflight with `froid-loop validate` and point the user at per-role adapter config.
+
+It also refreshes one file — `_froid/froid-loop/module-help.csv` — so the module's help entries are present even on a project that installed the tool directly rather than through the FROID installer. Nothing else under `_froid/` is written or deleted.
+
+Module identity (name, code, version) comes from `./assets/module.yaml`.
+
+`{project-root}` is a **literal token** in FROID config _values_ — never substitute it there. **This does not apply to the filesystem path _arguments_ in the commands below**: those are real paths, so resolve `{project-root}` to the actual project root before running.
+
+## On Activation
+
+1. Read `./assets/module.yaml` for module metadata (the `code` field is the module identifier).
+2. Check whether `{project-root}/_froid/` exists. If it does not, this project has no FROID install — say so, and note that the automation skills expect one. Setup can still install the orchestrator tool.
+3. Check whether `{project-root}/_froid/froid-loop/` exists. If it does, the module was installed by the FROID installer and is already registered. If it does not, tell the user the module is not registered with FROID, and that installing it via `npx froid-plane install` (selecting **froid-loop**) adds it to `/froid-help`. Do **not** gate setup on this — continue either way.
+
+**Decide fresh-install vs upgrade.** This drives whether the tool is upgraded and whether the per-project skills are refreshed. Treat it as an **upgrade** when either holds:
+
+- The user asked for one in their arguments — `upgrade`, `update`, `upgrade tool and skills`, or similar.
+- The orchestrator tool is already installed under uv: run `uv tool list` and look for a `froid-loop` entry. (A bare `froid-loop --version` is **not** sufficient on its own — it can be satisfied by a source checkout or unrelated virtualenv; see step 1 below.)
+
+Otherwise it is a **fresh install**. State the decision to the user before proceeding — e.g. "Detected an existing froid-loop install — running an upgrade: tool + skills" or "No existing install detected — running a fresh setup".
+
+If the user provides arguments (e.g. `accept all defaults`, `--headless`, `upgrade`), use them and skip interactive prompting. Still display the full confirmation summary at the end.
+
+## Register Help Entries
+
+Refresh the module's help entries. This is the only file this skill writes under `_froid/`, and it is exactly what the FROID installer itself places there — so it is a no-op on an installer-installed project and idempotent on every re-run.
+
+```bash
+mkdir -p "{project-root}/_froid/froid-loop"
+cp ./assets/module-help.csv "{project-root}/_froid/froid-loop/module-help.csv"
+```
+
+`/froid-help` reads the assembled catalog at `_froid/_config/froid-help.csv`, which the FROID installer rebuilds from every `_froid/<module>/module-help.csv`. So on a project that never ran the FROID installer, these entries become visible the next time it runs — not immediately. Say that plainly in the Confirm step rather than claiming the help system was updated.
+
+Skip this step entirely if `{project-root}/_froid/` does not exist.
+
+## Install the Orchestrator Tool
+
+The orchestrator is what spawns fresh coding CLI sessions through the selected adapter(s) to invoke `froid-build-auto` (the upstream dev primitive; `froid-dev-auto` on pre-rename releases) for the dev pass — then re-invokes it on the `done` spec for the follow-up review pass — and `froid-loop-sweep`, watches their hook signals, and verifies their artifacts. Installing it is therefore part of setup, not an optional extra.
+
+> **Why from Git?** The FROID installer copies only skill directories into a project — it does not carry sibling files, so the tool can't ride along in the skill folder. The canonical source is <https://github.com/cordya-ai/froid-loop>. (The reverse holds, though: the tool's wheel **bundles** the skills, so `froid-loop init` lays them down into a project's skill trees on its own — see step 3.)
+
+Unless the user explicitly asked to skip it (e.g. `skills only` / `--no-tool`), install **or upgrade** and bootstrap now. Resolve `{project-root}` to the real project path before running.
+
+1. **Check what's already on PATH:** run `froid-loop --version`. A version printing here does **not** mean this project is set up — it only means _some_ `froid-loop` is importable in the current environment. Before trusting it, run `uv tool list` and look for `froid-loop`: if it's absent (the on-PATH copy comes from a source checkout or an unrelated virtualenv), warn the user that the active environment is shadowing a clean install and that the project would be relying on that checkout. Unless the user explicitly declines, install/upgrade from the canonical source below so the project doesn't depend on an incidental dev environment.
+
+2. **Install or upgrade from the Git repository** (the `[tui]` extra pulls in the Textual dashboard so `froid-loop tui` works). `uv tool install` puts `froid-loop` in uv's own managed environment, so there's no PEP 668 externally-managed conflict and no need for `--user`, an activated virtualenv, or `--break-system-packages`.
+
+   - **Fresh install** (no uv-managed `froid-loop`):
+
+     ```bash
+     uv tool install "froid-loop[tui] @ git+https://github.com/cordya-ai/froid-loop.git"
+     ```
+
+     Pin a release tag for reproducibility by appending `@v<X.Y.Z>` to the Git URL.
+
+   - **Upgrade** (uv already manages `froid-loop`):
+
+     1. Record the current version first so you can report the delta: `froid-loop --version`.
+     2. Default — follow `main` (or the currently pinned tag):
+
+        ```bash
+        uv tool upgrade froid-loop --reinstall
+        ```
+
+        The `--reinstall` is **required** for a Git source: a plain `uv tool upgrade` reuses the cached commit and won't pull new code. Then **offer to pin a release tag** for reproducibility — if the user wants a specific version, move to it with:
+
+        ```bash
+        uv tool install --force "froid-loop[tui] @ git+https://github.com/cordya-ai/froid-loop.git@v<X.Y.Z>"
+        ```
+
+     3. Re-run `froid-loop --version` and note the before → after for the confirmation step.
+
+3. **Bootstrap the project** — install the coding-CLI hooks, the bundled `froid-loop-*` skills, the `.froid-loop/policy.toml` template, and the gitignore entry (idempotent).
+
+   First decide **which coding CLI(s)** the orchestrator should drive. The supported adapters are `claude` (default), `codex`, `gemini`, `copilot`, and `antigravity` (Google's `agy`). Hooks are registered per CLI, so the choice matters — register every CLI you intend to use for dev/review/triage. Ask the user (unless they already specified it in their setup args, e.g. `cli: claude, codex`, or accepted defaults — then default to `claude` only):
+
+   > "Which coding CLI(s) should the orchestrator drive — `claude`, `codex`, `gemini`, `copilot`, and/or `antigravity`? You can pick more than one. [claude]"
+
+   Build the command with one `--cli <name>` per selected CLI (the flag is repeatable). **On an upgrade, append `--force-skills`** so the per-project skill copies are actually refreshed — without it `init` skips every existing skill dir and the project keeps stale skills against the upgraded tool. On a fresh install, omit it.
+
+   ```bash
+   # fresh install, claude only (default)
+   froid-loop init --project "{project-root}" --cli claude
+
+   # fresh install, multiple, e.g. claude + codex + gemini
+   froid-loop init --project "{project-root}" --cli claude --cli codex --cli gemini
+
+   # upgrade — refresh the bundled skills in place
+   froid-loop init --project "{project-root}" --cli claude --force-skills
+   ```
+
+   Names must be exactly `claude`, `codex`, `gemini`, `copilot`, or `antigravity` — `init` errors on an unknown profile and lists the valid ones. `init` prints any one-time first-run notes per CLI (e.g. start `claude` once in the project and accept the workspace-trust + hooks-approval dialogs before `froid-loop run` — spawned sessions can't answer first-run dialogs). Relay those notes to the user.
+
+   **Skills are installed automatically:** `init` lays the bundled `froid-loop-*` skills into the right tree for each selected CLI — `.claude/skills/` for `claude`, `.agents/skills/` for `codex`/`gemini`/`copilot`/`antigravity`. On a fresh install, existing skill dirs are left untouched; on an upgrade, `--force-skills` overwrites them with the bundled copies from the upgraded tool (use `--no-skills` to skip the step and manage skills yourself).
+
+   > **Note:** `--force-skills` also overwrites `froid-loop-setup` itself (it ships in the same bundle). That's expected and safe — the freshly laid-down setup skill takes effect on the **next** invocation, and your `_froid/custom/*.toml` overrides (keyed by skill directory name) are untouched.
+
+4. **Preflight** — verify config, sprint-status, git, tmux, and the coding CLI:
+
+   ```bash
+   froid-loop validate --project "{project-root}"
+   ```
+
+   `validate` exits non-zero when the project isn't fully ready (e.g. no `sprint-status.yaml` yet, or `froid-sprint-planning` hasn't run). On a fresh project that is **expected** — report its findings to the user as a readiness checklist, not as an install failure.
+
+5. **Point the user at per-role adapter config.** `--cli` in step 3 only registers _hooks_ for each CLI. Which CLI actually **runs** each stage is governed by `{project-root}/.froid-loop/policy.toml`, written from a template by `init`. The `[adapter] name` (default `claude`) applies to every stage; optional `[adapter.dev]`, `[adapter.review]`, and `[adapter.triage]` tables override individual stages (each takes its own `name` and `extra_args`). So a mixed setup — e.g. `claude` for dev, `codex` for review — needs both the hooks registered (step 3) **and** the role pointed at that CLI in `policy.toml`:
+
+   ```toml
+   [adapter]
+   name = "claude"        # default for all stages
+
+   [adapter.review]
+   name = "codex"         # review runs on codex instead
+   ```
+
+   Tell the user where the file is and that any CLI named in `policy.toml` must also have been registered with `--cli` in step 3 (re-run `froid-loop init --cli <name>` to add one later). Leave `policy.toml` untouched if they only use a single CLI — the default is correct.
+
+## Confirm
+
+Report:
+
+- **Fresh install:** the installed `froid-loop --version`, that `froid-loop init` registered hooks, installed the `froid-loop-*` skills, and wrote policy/gitignore for the selected coding CLI(s) (name each one — e.g. "hooks + skills installed for claude, codex").
+- **Upgrade:** the before → after `froid-loop --version` (e.g. "upgraded 0.3.1 → 0.3.2", or "already current at 0.3.2"), and that the `froid-loop-*` skills were **refreshed** (not skipped) with `--force-skills` in each CLI tree.
+
+Also report:
+
+- The `froid-loop validate` preflight result (pass, or the readiness checklist of what's still missing).
+- That `_froid/froid-loop/module-help.csv` was refreshed. If `_froid/froid-loop/` did not exist before this run (i.e. the FROID installer never installed the module), say that the help entries will appear in `/froid-help` after the FROID installer next runs, and that installing the module via `npx froid-plane install` registers it properly.
+- That this skill wrote nothing else under `_froid/` — module registration, `config.toml`, and the help catalog are owned by the FROID installer.
+
+Then display the `module_greeting` from `./assets/module.yaml` to the user.
+
+## Outcome
+
+Use the user's configured name and language for the remainder of the session. Read them from FROID's central config via its own resolver (four-layer TOML merge; needs FROID v6.10+ and Python 3.11+):
+
+```bash
+uv run "{project-root}/_froid/scripts/resolve_config.py" --project-root "{project-root}" --key core
+```
+
+Take `user_name` and `communication_language` from the `core` table. If the script is absent or exits non-zero, fall back to addressing the user neutrally in English — do not write or repair any config file.

froid_loop/data/skills/froid-loop-setup/assets/module-help.csv

@@ -0,0 +1,3 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+FROID Loop Skills,froid-loop-setup,Setup Loop Module,SA,Install or update FROID Loop module config and help entries.,configure,{-H: headless mode},anytime,,,false,{project-root}/_froid,config.yaml entries
+FROID Loop Skills,froid-loop-sweep,Sweep Triage,ST,Read-only triage of the deferred-work ledger into a machine-readable partition. Automation-only; froid-loop sweep invokes it.,triage,{--feedback path},anytime,,,false,implementation_artifacts,result.json triage plan

froid_loop/data/skills/froid-loop-setup/assets/module.yaml

@@ -0,0 +1,19 @@
+code: froid-loop
+name: FROID Loop Skills
+description: "Automation-mode skills driven by the froid-loop orchestrator: interactive escalation resolution (froid-loop-resolve) and deferred-work sweep triage (froid-loop-sweep) — the inner dev primitive (which self-reviews and commits) is the upstream froid-build-auto skill (froid-dev-auto on pre-rename releases)"
+module_version: 0.11.1
+default_selected: false
+module_greeting: >
+  FROID Loop installed — both the automation skills and the
+  froid-loop orchestrator tool (the Python program that drives the loop). Setup
+  installed the `froid-loop` package from its Git repository with
+  `uv tool install`, ran `froid-loop init` (skills + hooks + policy + gitignore),
+  and `froid-loop validate`
+  (preflight). The skills
+  are invoked by the orchestrator and must stay installed together — the
+  froid-loop-sweep skill normalizes and migrates the deferred-work ledger per its
+  own deferred-work-format.md. They require the Froid Plane (bmm) module:
+  _froid/bmm/config.yaml and a sprint-status.yaml from froid-sprint-planning. Run
+  `froid-loop run` to start, `froid-loop tui` for the dashboard. To upgrade later,
+  just re-run `/froid-loop-setup` (or `/froid-loop-setup upgrade`) — it upgrades the
+  orchestrator tool and refreshes the per-project skills for you.

froid_loop/data/skills/froid-loop-sweep/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: froid-loop-sweep
+description: 'Triage the deferred-work ledger for the froid-loop orchestrator: verify every open entry against the actual codebase and return a machine-readable partition (bundles, already-resolved, blocked, skip, human decisions). Also migrates legacy pre-DW-format ledgers when invoked with --migrate. Automation-only — invoked by froid-loop sweep runs, not by humans.'
+---
+
+# Deferred-Work Sweep Triage
+
+**Goal:** Classify every open entry in `{implementation_artifacts}/deferred-work.md`
+into a machine-readable triage plan the orchestrator can validate and execute.
+
+This workflow is **read-only and automation-native**: it runs only inside a
+`froid-loop` sweep session. You never edit the ledger, never edit code, never
+ask questions. Your sole output is the result file. (The one exception is
+migration mode, which edits exactly one file — the ledger.)
+
+## On Activation
+
+### Step 0: Automation Check & Mode Dispatch
+
+Run: `echo "${FROID_LOOP_MODE:-}"`
+
+If the output is not `1`, state that this skill only runs inside a froid-loop
+sweep and end your turn. Otherwise read `./automation-mode.md` fully — its
+rules and result schema govern this entire run.
+
+If the invocation carries `--migrate <manifest-path>`, this is a **migration
+session**, not triage: read `./migration-mode.md` and follow it instead of
+Steps 1–4 below.
+
+### Step 1: Locate the ledger
+
+Read `{project-root}/_froid/bmm/config.yaml` to resolve `implementation_artifacts`,
+then read `{implementation_artifacts}/deferred-work.md` in full. Open entries
+are `### DW-<n>:` blocks whose `status:` line is `open`. If the ledger is
+missing or unreadable, escalate `CRITICAL` (`type: missing-ledger`) per
+automation-mode.md and end your turn.
+
+An entry carrying an `archived:` line keeps only a stub here — its full body
+lives in the sibling `deferred-work-archive.md`, keyed by the same DW- id; read
+it there before classifying that entry. An `archived-body:` line says the same
+of an entry that was archived and later reopened: it is live work again, but the
+body it carried before that close is still in the archive file, in the block
+stamped with the date the line carries.
+
+If the invocation carries `--feedback <path>`, read that file FIRST — it lists
+the deterministic validation errors your previous attempt's result.json failed
+on. Fix exactly those defects in this attempt's output.
+
+### Step 2: Verify every open entry against the code
+
+Ledger statuses are known-unreliable: entries are often resolved by later work
+but never marked done. For EACH open entry:
+
+1. Read its `location:` (file/component) in the current tree.
+2. Check whether the described issue still exists — read the code, grep for
+   the symptom, check `git log` for commits that touched the area since the
+   entry's `origin:` date.
+3. Record concrete evidence either way. "Probably fixed" is not evidence;
+   a file:line or commit hash is.
+
+Use sub-agents for parallel verification when available; never ask permission.
+
+### Step 3: Partition
+
+Classify each open entry into exactly ONE category:
+
+- **already_resolved** — the issue no longer exists in the code. Requires
+  concrete `evidence` (file:line that now handles it, or the commit that fixed
+  it). The orchestrator closes the ledger entry deterministically.
+- **bundles** — buildable now: every file the fix needs already exists and no
+  future story has to land first. Group entries that share a touchpoint (same
+  file, same subsystem, same validator pattern) into cohesive single-goal
+  bundles sized for one dev session; an entry that stands alone is a
+  one-entry bundle. `name` matches `^[a-z0-9][a-z0-9-]{1,39}\Z` (kebab-case,
+  at most 40 characters; e.g. `unicode-string-hardening`), and `intent` is
+  2–6 sentences describing the one cohesive goal.
+- **blocked** — the fix is only meaningful (or meaningfully easier) after a
+  named future story/epic lands. Name the blocker verbatim.
+- **skip** — superseded, moot, or tied to a scenario the project explicitly
+  excludes. Give the reason.
+- **decisions** — a human must choose. ALWAYS a decision, never a bundle:
+  renegotiating anything inside a spec's `<frozen-after-approval>` block,
+  reversing a deliberate human-approved scope decision, API-shape changes that
+  ripple to unbuilt consumers, and entries deferred with reason
+  "auto-mode: needs human decision". Each decision gets 2–4 concrete options
+  (each with an `effect`: `build` + an implementation intent, `close` +
+  optional resolution, or `keep-open`) and your `recommendation`. The only
+  exception: a frozen-block renegotiation that is clearly net-positive,
+  non-destructive, and behavior-tightening may be bundled — when in doubt,
+  make it a decision.
+
+Every open entry appears in exactly one category. The orchestrator validates
+this deterministically; a missed or double-counted entry fails the whole
+result and burns a retry.
+
+### Step 4: Write the result and end your turn
+
+Write the result.json per `./automation-mode.md` and state in one line how
+many entries went to each category. End your turn. Do not edit any file other
+than the result file.