@tacuchi/agent-workflow-cli 17.1.0 → 19.0.0

package/skills/w/loops/CODE-POLICIES.md

@@ -1,6 +1,6 @@
 # CODE-POLICIES — policies for code-editing loops
 
-They apply to **`plan-exec-loop`** (per plan phase) and **`quick-loop`** (the single task; **proportional** gate): each orders this doc read from its `## Inherits`, **together with the chassis** ([`CHASSIS.md`](CHASSIS.md)). The document loops (spec-refine, plan-new, plan-refine) edit no code and do **not** load this doc — that is why it lives apart from the chassis. These policies materialize the **DB scripts-only** and **safe git** invariants — which also stay summarized **inline** (1-2 lines) in each code-editing loop's `SKILL.md`, because advisory hosts do not follow Reads; the full normative text lives here.
+They apply to **`plan-exec-loop`** (per plan phase) and **`quick-loop`** (the single task; **proportional** gate): each orders this doc read from its `## Inherits`, **together with the chassis** ([`CHASSIS.md`](CHASSIS.md)). The document loops (spec-refine, plan-new, plan-refine) edit no code and do **not** load this doc — that is why it lives apart from the chassis. These policies materialize the **DB scripts-only** and **safe git** invariants — which also stay summarized **inline** (1-2 lines) in each code-editing loop's `LOOP.md`, because advisory hosts do not follow Reads; the full normative text lives here.
 
 ## Safe git — verified branch + proposed commits
 
@@ -31,4 +31,4 @@ Only with the gate green are the commits proposed.
 
 ## Location
 
-Same as the chassis: code-editing loops reference it as `../CODE-POLICIES.md` (normal install, `w/loops/` tree); in **flattened** installs it may sit as `CODE-POLICIES.md` **next to the loop's `SKILL.md`** (chassis § *Reference resolution*).
+Same as the chassis: code-editing loops reference it as `../CODE-POLICIES.md` — the `w/loops/` tree is installed intact on every host (chassis § *Reference resolution*).

package/skills/w/loops/README.md

@@ -8,7 +8,7 @@
 
 ## What a loop is
 
-A loop is a **skill** that teaches the AI *how to iterate* until it produces a deliverable. **It is not invocable by name** as a standalone skill (it is not registered as such; in Claude Code, by-name invocation is the `Skill` tool — its binding, not a universal): it is the body of its `/w:…` command, which **loads it by reading `<loop>/SKILL.md`** and executes it inline.
+A loop is an **operating manual** that teaches the AI *how to iterate* until it produces a deliverable. **It is not invocable by name** as a standalone skill — its file is deliberately named `LOOP.md`, **not** `SKILL.md`, so no harness indexes it as a user-facing skill (several scan skill roots recursively): it is the body of its `/w:…` command, which **loads it by reading `<loop>/LOOP.md`** and executes it inline.
 
 The 5 loops run the same **common engine**, whose canon lives in [`CHASSIS.md`](CHASSIS.md): persistent objective + verification-first, gap-driven convergent, single session per run with inline research, structured-choice + `flow` control (`Compactar`/`Cerrar`, always present), compact/resume, artifacts as a live log, convergence gate and the `docs/` boundary. Each loop is an **heir**: its `## Inherits` orders the chassis read before its deltas — nothing of the engine is repeated here.
 
@@ -16,11 +16,11 @@ The 5 loops run the same **common engine**, whose canon lives in [`CHASSIS.md`](
 
 | Loop (`name:`) | Flow | Started by | Reads | Writes |
 |---|---|---|---|---|
-| [`spec-refine-loop`](spec-refine-loop/SKILL.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (the spec itself) | `docs/specs/NNN-spec-<slug>.md` (in place) |
-| [`plan-new-loop`](plan-new-loop/SKILL.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
-| [`plan-refine-loop`](plan-refine-loop/SKILL.md) | PLAN | `/w:plan-refine` *(aux, optional)* | `docs/plans/PPP-plan-*.md` (the plan itself) | `docs/plans/PPP-plan-<slug>.md` (in place) |
-| [`plan-exec-loop`](plan-exec-loop/SKILL.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update); the rest via `export-*` |
-| [`quick-loop`](quick-loop/SKILL.md) | QUICK | `/w:quick` | — (prompt) | edits code + light session; **no** `docs/` |
+| [`spec-refine-loop`](spec-refine-loop/LOOP.md) | SPEC | `/w:spec-refine` | `docs/specs/NNN-spec*.md` (the spec itself) | `docs/specs/NNN-spec-<slug>.md` (in place) |
+| [`plan-new-loop`](plan-new-loop/LOOP.md) | PLAN | `/w:plan-new` | `docs/specs/NNN-spec-*.md` | `docs/plans/PPP-plan-<slug>.md` |
+| [`plan-refine-loop`](plan-refine-loop/LOOP.md) | PLAN | `/w:plan-refine` *(aux, optional)* | `docs/plans/PPP-plan-*.md` (the plan itself) | `docs/plans/PPP-plan-<slug>.md` (in place) |
+| [`plan-exec-loop`](plan-exec-loop/LOOP.md) | PLAN | `/w:plan-exec` | `docs/plans/PPP-plan-*.md` | `docs/plans/PPP-plan-<slug>.md` (update); the rest via `export-*` |
+| [`quick-loop`](quick-loop/LOOP.md) | QUICK | `/w:quick` | — (prompt) | edits code + light session; **no** `docs/` |
 
 > `/w:spec-new` has no loop (single-pass). Hence **6 commands / 5 loops**.
 
@@ -57,7 +57,7 @@ Loops compose **capabilities by role**, never concrete skills; the skill fulfill
 | `sql` | `sql` | research · `plan-exec-loop` · `quick-loop` |
 | `git` | `git` | `plan-exec-loop` · `quick-loop` |
 | `research` | `research` | every loop (inline research) |
-| `overview` | `workflow` | anyone (orientation) |
+| `overview` | `w` | anyone (orientation) |
 
 > **Ambient conventions (not roles):** code/testing/writing standards and `creating-tools` are standalone skills the host auto-discovers by `description` — the workflow neither binds nor depends on them. Full doctrine: [../roles/README.md](../roles/README.md).
 
@@ -67,8 +67,8 @@ Loops compose **capabilities by role**, never concrete skills; the skill fulfill
 
 - [`CHASSIS.md`](CHASSIS.md) — the common engine of the 5 loops (referenced doc; not a skill)
 - [`CODE-POLICIES.md`](CODE-POLICIES.md) — the code-editing loop policies (loaded only by plan-exec and quick)
-- [`spec-refine-loop/SKILL.md`](spec-refine-loop/SKILL.md)
-- [`plan-new-loop/SKILL.md`](plan-new-loop/SKILL.md)
-- [`plan-refine-loop/SKILL.md`](plan-refine-loop/SKILL.md) — aux, optional (refines the plan in place)
-- [`plan-exec-loop/SKILL.md`](plan-exec-loop/SKILL.md)
-- [`quick-loop/SKILL.md`](quick-loop/SKILL.md)
+- [`spec-refine-loop/LOOP.md`](spec-refine-loop/LOOP.md)
+- [`plan-new-loop/LOOP.md`](plan-new-loop/LOOP.md)
+- [`plan-refine-loop/LOOP.md`](plan-refine-loop/LOOP.md) — aux, optional (refines the plan in place)
+- [`plan-exec-loop/LOOP.md`](plan-exec-loop/LOOP.md)
+- [`quick-loop/LOOP.md`](quick-loop/LOOP.md)

package/skills/w/loops/plan-exec-loop/{SKILL.md → LOOP.md}

@@ -25,7 +25,7 @@ PLAN
 `/w:plan-exec` — **resumable** (same chassis mechanism; here resume keys off the plan-doc checkboxes + CHECKPOINT, see Delta 1).
 
 ## Reads
-`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument). It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/SKILL.md) — plan-refine is auxiliary, not mandatory; no gate requires it. If the plan includes UI, it also reads the **design SPECs** (`NNN-SPEC-<SLUG>.md`) its Tasks reference — artifacts of the plan-new/plan-refine session, read **read-only** as the design reference while implementing (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
+`docs/plans/PPP-plan-<slug>.md` (locate via the `docs/plans/PPP-plan-*.md` glob or the exact path from the command argument). It runs **any** plan, whether or not it passed through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) — plan-refine is auxiliary, not mandatory; no gate requires it. If the plan includes UI, it also reads the **design SPECs** (`NNN-SPEC-<SLUG>.md`) its Tasks reference — artifacts of the plan-new/plan-refine session, read **read-only** as the design reference while implementing (see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
 
 ## Writes
 - `docs/plans/PPP-plan-<slug>.md` (**read/update**, living doc: phase/task state, `Open questions`).

package/skills/w/loops/plan-new-loop/{SKILL.md → LOOP.md}

@@ -71,7 +71,7 @@ The plan absorbs the `TECHNICAL-NOTE` level **inline** (user decision) + the roa
 
 > **Scales with complexity:** the `(core)` sections go **always**; the `(opt.)` ones only when the plan warrants them — a small plan may omit `Dependencies`, AS-IS/TO-BE, `Risks`, `Assumptions`, `Estimated time`. Concise > exhaustive.
 
-> **Catalog implication:** `TECHNICAL-NOTE` stops being a session artifact and becomes **sections of the plan-doc**. Reconciled in [`plan-exec-loop`](../plan-exec-loop/SKILL.md): the single plan-exec session carries **no** `TECHNICAL-NOTE` nor its own `TASKS`; the technical detail and the progress live inline in the plan-doc (living).
+> **Catalog implication:** `TECHNICAL-NOTE` stops being a session artifact and becomes **sections of the plan-doc**. Reconciled in [`plan-exec-loop`](../plan-exec-loop/LOOP.md): the single plan-exec session carries **no** `TECHNICAL-NOTE` nor its own `TASKS`; the technical detail and the progress live inline in the plan-doc (living).
 
 ## Delta 2 — Gap taxonomy (of "plan")
 
@@ -95,7 +95,7 @@ The chassis' **inline** research specializes: mapping **code/impact** — affect
 
 ## Delta 4 — Design SPECs (when the plan includes UI)
 
-The **UI without design SPEC** gap is resolved by **composing** the **`ui-design`** capability (built-in default [`ui-spec`](../../roles/ui-spec/SKILL.md); rebindable via `.workflow/skills.toml`; `off` → degrades to human / `Open questions`):
+The **UI without design SPEC** gap is resolved by **composing** the **`ui-design`** capability (built-in default [`ui-spec`](../../roles/ui-spec/ROLE.md); rebindable via `.workflow/skills.toml`; `off` → degrades to human / `Open questions`):
 
 - It authors **one design SPEC per screen** as a session artifact: `NNN-SPEC-<SLUG>.md` (numbering local to the session — see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)).
 - It **derives** from the spec's `## UI spec` section when present (splits it per screen and raises it to executable detail); otherwise it authors from the `Requirement` (design system/theme/ambiguities via *structured-choice*, counts in the batch).
@@ -135,4 +135,4 @@ finalize: CHECKPOINT persisted (+ BACKLOG only if something is deferred) + close
 - Passes → `Guardar plan` (writes with confirmation if it exists) → `finalize`.
 - `Cerrar` at any time → `finalize` (persists `CHECKPOINT`; `BACKLOG` only if something is deferred; closes the session, reports).
 
-> **After generating:** the plan can go straight to `plan-exec`, or — if changes arise before executing (new requirements, scope adjustments) — pass through [`plan-refine-loop`](../plan-refine-loop/SKILL.md) (`/w:plan-refine`, auxiliary and **not mandatory**), which refines it in place.
+> **After generating:** the plan can go straight to `plan-exec`, or — if changes arise before executing (new requirements, scope adjustments) — pass through [`plan-refine-loop`](../plan-refine-loop/LOOP.md) (`/w:plan-refine`, auxiliary and **not mandatory**), which refines it in place.

package/skills/w/loops/plan-refine-loop/{SKILL.md → LOOP.md}

@@ -48,7 +48,7 @@ Full doctrine in the chassis (§ *Internal sessions* + *Numbering*). This loop's
 
 ## Delta 1 — Deliverable: the PLAN, edited in place
 
-The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/SKILL.md) produces (§ *Delta 1 — RICH PLAN*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** two trace sections:
+The plan uses the **same skeleton** [`plan-new-loop`](../plan-new-loop/LOOP.md) produces (§ *Delta 1 — RICH PLAN*: `Summary`/`Solution`/`Impacted`/`Phases`/`Tasks`/`Validations`/`Final behavior`/… with `(core)` sections always and `(opt.)` by complexity). plan-refine does **not** change the schema: it **completes/adjusts** the existing sections **in place** and **adds** two trace sections:
 
 ```markdown
 ## Refinement decisions   ← NEW (ADDED)
@@ -66,7 +66,7 @@ Every doubt asked to the human + the chosen answer.
 
 ## Delta 2 — Gap taxonomy (of "plan")
 
-Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-loop/SKILL.md) § *Delta 2*): vague Approach/Solution, components unidentified, AS-IS wiring unknown, phase too large, task not atomic, missing deps, spec criteria uncovered, unaddressed risks, UI without design SPEC. **Focus difference:** plan-new **builds** the plan from scratch; plan-refine **detects what changed** against the written plan (or against the spec, if the spec was re-refined) and closes **those** gaps — typically fewer and more localized. One extra re-refine gap:
+Reuses plan-new-loop's gap taxonomy **in full** ([`plan-new-loop`](../plan-new-loop/LOOP.md) § *Delta 2*): vague Approach/Solution, components unidentified, AS-IS wiring unknown, phase too large, task not atomic, missing deps, spec criteria uncovered, unaddressed risks, UI without design SPEC. **Focus difference:** plan-new **builds** the plan from scratch; plan-refine **detects what changed** against the written plan (or against the spec, if the spec was re-refined) and closes **those** gaps — typically fewer and more localized. One extra re-refine gap:
 
 | Gap | Signal | Resolved by |
 |---|---|---|
@@ -78,7 +78,7 @@ Same as plan-new (maps code/impact: FE/BE/DB components, AS-IS wiring, deps), bu
 
 ## Delta 4 — Design SPECs (when the refine touches UI)
 
-Same mechanism as [`plan-new-loop`](../plan-new-loop/SKILL.md) (§ *Delta 4*: the **`ui-design`** capability → per-screen `NNN-SPEC-<SLUG>.md`, see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **scoped to the delta**: only the screens **new or changed** by the refine get a design SPEC. The updated SPEC is written in **plan-refine's own session** (each loop manages ITS session's artifacts — it never edits plan-new's) and the plan **re-points** the UI Task reference to the current SPEC. Untouched screens keep their original SPEC.
+Same mechanism as [`plan-new-loop`](../plan-new-loop/LOOP.md) (§ *Delta 4*: the **`ui-design`** capability → per-screen `NNN-SPEC-<SLUG>.md`, see [`SPEC.md`](../../artifacts/artifacts-design/SPEC.md)), **scoped to the delta**: only the screens **new or changed** by the refine get a design SPEC. The updated SPEC is written in **plan-refine's own session** (each loop manages ITS session's artifacts — it never edits plan-new's) and the plan **re-points** the UI Task reference to the current SPEC. Untouched screens keep their original SPEC.
 
 ## Compact / resume
 

package/skills/w/loops/quick-loop/{SKILL.md → LOOP.md}

@@ -59,7 +59,7 @@ Read **[`../CHASSIS.md`](../CHASSIS.md)** — the loop's **full engine** — **a
   - **Anti-duplicate** (the `create_or_resume` spirit): if a spec whose `## Origin` references this same objective already exists (or an equivalent `*-spec-refine` session), the recommended option becomes **resuming that spec** (`/w:spec-refine` semantics) — never a second draft.
 - **Live transition to SPEC** (shared by the gate and mid-loop escalation). On acceptance, the work line **moves to the SPEC flow**: the explicit consent in the structured-choice **equals invoking the destination command** (*consented exception* — rule 3 of the *Continuity rule*, [`../../SKILL.md`](../../SKILL.md) § *Operating context*). On the SPEC side:
   1. **Materialize the draft** via the [`../../commands/spec-new.md`](../../commands/spec-new.md) procedure: `aw next-number docs/specs`, slug, schema, single-pass **NO RESEARCH**. `## Origin` = "escalated from `/w:quick`" + the original prompt (+ the origin quick session if it exists).
-  2. **Load and execute** [`../spec-refine-loop/SKILL.md`](../spec-refine-loop/SKILL.md) — flattened: `../w-spec-refine-loop/SKILL.md` — over that spec (trampoline pattern).
+  2. **Load and execute** [`../spec-refine-loop/LOOP.md`](../spec-refine-loop/LOOP.md) — over that spec (trampoline pattern).
   3. The run's session is that loop's **normal** `NNN-<slug>-spec-refine` (the CLI numbers it; its `## Origin` records the escalation). **Invariant 2 intact**: quick, while it is quick, never writes `docs/` — the draft is written by the SPEC flow, post-consent.
 - **Mid-loop escalation + handoff**: if the task grows (same gate signals) → propose moving up to **SPEC/PLAN** (structured-choice, recommendation first). If the user accepts:
   1. The **already-edited code stays** in the working tree (never reverted) and is **recorded** in `CHECKPOINT` + `BACKLOG`: "uncommitted changes in `<source>` — decide commit/discard on resume" (the "rejected commit" pattern, [`../CODE-POLICIES.md`](../CODE-POLICIES.md) § *Safe git*).
@@ -87,7 +87,7 @@ quick-loop(prompt):
     structured_choice(content: [Cambiar a SPEC (recommended), Seguir en quick, Recortar alcance],
                       flow: [Compactar, Cerrar])           # Cerrar here = abort (nothing created yet)
     Cambiar a SPEC   → live transition (see delta): draft (spec-new procedure) +
-                       load and execute ../spec-refine-loop/SKILL.md → END (no quick session)
+                       load and execute ../spec-refine-loop/LOOP.md → END (no quick session)
     Recortar alcance → objective = the proposed sub-task; the rest → BACKLOG when the session is created
     Seguir en quick  → continue
   s = create_or_resume("<slug>-quick")      # CLI prepends global NNN; always a light session

package/skills/w/loops/spec-refine-loop/{SKILL.md → LOOP.md}

@@ -27,7 +27,7 @@ SPEC
 ## Started by
 `/w:spec-refine` — **resumable**. Detects prior state (via CHECKPOINT) and starts accordingly (see *Compact / resume — SPEC keys*).
 
-It is also started by the **live escalation from `quick-loop`** (entry gate or mid-loop — see [`../quick-loop/SKILL.md`](../quick-loop/SKILL.md) § *QUICK delta*): quick materializes the draft (`spec-new` procedure) and **loads this loop** over that spec — same semantics as if the user had run `/w:spec-refine`.
+It is also started by the **live escalation from `quick-loop`** (entry gate or mid-loop — see [`../quick-loop/LOOP.md`](../quick-loop/LOOP.md) § *QUICK delta*): quick materializes the draft (`spec-new` procedure) and **loads this loop** over that spec — same semantics as if the user had run `/w:spec-refine`.
 
 ## Reads
 - `docs/specs/NNN-spec*.md` (glob — locates the spec by number; also catches the legacy `NNN-spec.md`), **or** the exact path passed as the command argument. **Always the spec itself**: this loop edits it in place; there is no separate "refined" file.
@@ -76,7 +76,7 @@ The spec is completed **in place**: the draft's sections get **completed** + two
 ## Assumptions            (declared)
 
 ## UI spec                (opt. — if UI is involved; via the ui-design capability / ui-spec skill)
-Structured Markdown description (screens → regions/components). See [`ui-spec`](../../roles/ui-spec/SKILL.md).
+Structured Markdown description (screens → regions/components). See [`ui-spec`](../../roles/ui-spec/ROLE.md).
 
 ## Refinement decisions   ← NEW (ADDED)
 What was defined while refining and why. Includes what inline research

package/skills/w/roles/README.md

@@ -12,12 +12,12 @@ All 6 roles, their built-in defaults, their tier, and which loops/exports compos
 
 | Role | Default built-in | Tier | Composed by |
 |---|---|---|---|
-| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` (per-screen design SPECs) |
+| `ui-design` | [`ui-spec`](ui-spec/ROLE.md) | must | `spec-refine-loop` (when requirement involves UI) · `plan-new-loop` / `plan-refine-loop` (per-screen design SPECs) |
 | `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
 | `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
-| `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
-| `diagrams` | [`diagrams`](diagrams/SKILL.md) | should | `export-diagrams` |
-| `overview` | `workflow` | should | any loop (orientation about the workflow itself) |
+| `research` | [`research`](research/ROLE.md) | should | all loops (on-demand investigation) |
+| `diagrams` | [`diagrams`](diagrams/ROLE.md) | should | `export-diagrams` |
+| `overview` | `w` | should | any loop (orientation about the workflow itself) |
 
 **Tiers:**
 - `must` — core to almost every session; built-in always active unless explicitly `off`.
@@ -61,7 +61,7 @@ built-in default
 # git              = "git"
 # research         = "research"
 # diagrams         = "diagrams"
-# overview         = "workflow"
+# overview         = "w"
 
 # Override examples:
 ui-design        = "acme/figma-spec"    # third-party skill installed via skills.sh
@@ -116,7 +116,7 @@ sql               sql                     built-in
 git               git                     built-in
 research          research                built-in
 diagrams          mermaid-only            global      (~/.workflow/skills.toml)
-overview          workflow                built-in
+overview          w                       built-in
 ```
 
 ---
@@ -124,13 +124,13 @@ overview          workflow                built-in
 ## Adding a new role
 
 1. Define the role in this README (name, default built-in, tier, composed by).
-2. Author the built-in skill under `roles/<name>/SKILL.md` following the schema.
+2. Author the built-in skill under `roles/<name>/ROLE.md` following the schema.
 3. Register it in the CLI resolver so `aw skills` lists it.
 4. Document the binding key in the `skills.toml` reference above.
 
 ## Authoring a built-in skill
 
-Each `SKILL.md` follows this schema:
+Each `ROLE.md` follows this schema:
 
 | Section | Content |
 |---|---|
@@ -143,4 +143,4 @@ Each `SKILL.md` follows this schema:
 | `## Output` | what it produces and where (if any) |
 | `## Source` | recycled from (if applicable) |
 
-See [`research/SKILL.md`](research/SKILL.md) as a reference implementation.
+See [`research/ROLE.md`](research/ROLE.md) as a reference implementation.

package/skills/w/roles/git/{SKILL.md → ROLE.md}

@@ -46,7 +46,7 @@ And **always** forbidden, even when the user asks for a commit: `--no-verify` (r
 
 ### Read-only operations (always allowed, no asking)
 
-`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (branch switch) is **not** read-only: it requires *structured-choice* (canonical rule: `../../loops/CHASSIS.md` § *Structured-choice*; per-harness binding: `../../harness/SKILL.md`) even though it is not destructive (see branch verification).
+`status` · `log` · `diff` · `branch --show-current` · `rev-parse` · `show`. `git checkout` (branch switch) is **not** read-only: it requires *structured-choice* (canonical rule: `../../loops/CHASSIS.md` § *Structured-choice*; per-harness binding: `../../harness/HARNESS.md`) even though it is not destructive (see branch verification).
 
 ### Branch verification (before editing)
 

package/skills/w/roles/research/{SKILL.md → ROLE.md}

@@ -25,7 +25,7 @@ The key discriminator:
 | The question... | Action |
 |---|---|
 | can be answered by reading repo / data (objective system facts) | **investigate** |
-| depends on the user's preferences, priorities or decisions | **ask the human** via *structured-choice* (canonical rule: `../../loops/CHASSIS.md` § *Structured-choice*; per-harness binding: `../../harness/SKILL.md`) |
+| depends on the user's preferences, priorities or decisions | **ask the human** via *structured-choice* (canonical rule: `../../loops/CHASSIS.md` § *Structured-choice*; per-harness binding: `../../harness/HARNESS.md`) |
 | is partly in the repo and partly user intent | investigate first, then ask only about the uncertain part |
 
 ## Composed by

package/skills/w/roles/ui-spec/{SKILL.md → ROLE.md}

@@ -27,12 +27,12 @@ Given a UI requirement, author a **structured Markdown description** of the scre
 
 Two levels, same capability:
 
-- **`spec-refine-loop`** (see `../../loops/spec-refine-loop/SKILL.md`) — resolving the **UI unspecified** gap (when the requirement involves UI): authors the spec's `## UI spec` section (the UI's *what*, coarse-grain screens).
-- **`plan-new-loop` · `plan-refine-loop`** (see `../../loops/plan-new-loop/SKILL.md` § *Delta 4*) — resolving the **UI without design SPEC** gap (when the **plan includes UI**): authors per-screen **design SPECs** (`NNN-SPEC-<SLUG>.md`) as **PLAN session artifacts** (see `../../artifacts/artifacts-design/SPEC.md`); they derive from `## UI spec` when it exists.
+- **`spec-refine-loop`** (see `../../loops/spec-refine-loop/LOOP.md`) — resolving the **UI unspecified** gap (when the requirement involves UI): authors the spec's `## UI spec` section (the UI's *what*, coarse-grain screens).
+- **`plan-new-loop` · `plan-refine-loop`** (see `../../loops/plan-new-loop/LOOP.md` § *Delta 4*) — resolving the **UI without design SPEC** gap (when the **plan includes UI**): authors per-screen **design SPECs** (`NNN-SPEC-<SLUG>.md`) as **PLAN session artifacts** (see `../../artifacts/artifacts-design/SPEC.md`); they derive from `## UI spec` when it exists.
 
 In both, the composing loop contributes:
 
-- **Asking the human** (design system, theme, screen ambiguities) via *structured-choice* (canonical rule: `../../loops/CHASSIS.md` § *Structured-choice*; per-harness binding: `../../harness/SKILL.md`).
+- **Asking the human** (design system, theme, screen ambiguities) via *structured-choice* (canonical rule: `../../loops/CHASSIS.md` § *Structured-choice*; per-harness binding: `../../harness/HARNESS.md`).
 - **Gap-driven iteration** until convergence.
 - Offering **variants** and **curating** the result.