@tacuchi/agent-workflow-cli 16.0.0 → 16.2.0

package/dist/application/templates/session.js

@@ -45,7 +45,7 @@ ${renderOriginSection(values.origin)}
 ${values.type}
 
 ## Success criteria
-<!-- Verification-first done-condition, seeded BEFORE executing: falsifiable [ ] items (tests for code, a by-inspection rubric for analysis/design). The loop persists until all are green. -->
+<!-- Verification-first done-condition, seeded BEFORE executing: falsifiable [ ] items (tests for code, a by-inspection rubric for analysis/design). The loop persists until all are green and flips each to [x] at the convergence gate; replace this comment when filling. -->
 - [ ]
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tacuchi/agent-workflow-cli",
-  "version": "16.0.0",
+  "version": "16.2.0",
   "description": "Agnostic runtime CLI for AI development workflows — a stages + loops + artifacts harness. Bundles the universal `w` skill set under `skills/w/` (slash commands `/w:*`: spec-new/spec-refine, plan-new/plan-exec, quick, workspace-init, export-*); `self install --target <host>` copies SKILL + commands + hooks into the host. Pluggable capability skills via `.workflow/skills.toml`. Multi-empresa parametrization via `profile.json` cascade. Namespace auto-detected from any `.<ns>/sessions/` dir in CWD; default `workflow`.",
   "type": "module",
   "bin": {

package/skills/w/artifacts/README.md

@@ -43,7 +43,7 @@ Sessions are created by the loops as needed — **one session per run**. The ses
 
 ## Common artifacts (any session)
 
-`SESSION` (descriptor: Objective / Origin / Type / **Success criteria** = verification-first done-condition, formerly research-only) · `CHECKPOINT` (resume) · `SCRIPTS.sql` (read-only queries **executable** + DDL/DML migrations **deliverable**, not executed) · `TASKS` · `BACKLOG` (only when there's something to defer).
+`SESSION` (descriptor: Objective / Origin / Type / **Success criteria** — the verification-first done-condition; the convergence gate flips them green) · `CHECKPOINT` (resume — **fixed headings, updated in place, never duplicated**; see its contract) · `SCRIPTS.sql` (read-only queries **executable** + DDL/DML migrations **deliverable**, not executed) · `TASKS` · `BACKLOG` (only when there's something to defer).
 
 ---
 

package/skills/w/artifacts/artifacts-core/CHECKPOINT.md

@@ -1,23 +1,25 @@
 # CHECKPOINT.md — session resume state (common)
 
 > What it is: the live resume state of a session — lets the loop resume exactly where it left off.
-> **Live log (artifact-first):** `Pending`/`Next` = the intent (what is about to be done, seeded BEFORE executing); `Completed` = the result (AFTER). Updated at every gap/phase boundary, not only on `Compactar`/`Cerrar`.
-> Owned by: **every session** (`refine` · `exec` · `quick`). Persisted **always** on close/compact (the resume key — invariant #6), unlike `BACKLOG` which is written only when something is deferred.
+> **Live log (artifact-first):** `Pending / Next` = the intent (what is about to be done, seeded BEFORE executing); `Completed` = the result (AFTER). Updated at every gap/phase boundary, not only on `Compactar`/`Cerrar`.
+> Owned by: **every session** (`refine` · `exec` · `quick`). Persisted **always** on close/compact (the resume key), unlike `BACKLOG`, which is written only when something is deferred.
 
-## Activity
-Summary of the activity done so far.
+## Contract (hard rules)
 
-## Critical context
-Key decisions / references to other artifacts or documents needed to continue.
+1. **Fixed headings, exactly these three**: `## Completed` · `## Pending / Next` · `## Open questions` (plus the optional ones below).
+2. **Update in place — NEVER duplicate a section.** Every update edits the existing section's content; appending a second `## <same heading>` is a contract violation.
+3. New entries go at the top of their section (most recent first) or extend an existing bullet — each section stays a single block.
 
 ## Completed
-Completed phases/tasks (ref: plan-doc `docs/plans/PPP-plan.md`; or `TASKS.md` if the session created its own breakdown).
+What already happened: finished phases/tasks/gaps with their outcome (ref: plan-doc `docs/plans/PPP-plan.md`, the spec's gaps, or `TASKS.md` if the session created its own split). Fold the key context a resume needs (settled decisions, discoveries) into these bullets.
 
-## Excluded
-Excluded phases/tasks (ref: plan-doc; or `TASKS.md`) with reason.
+## Pending / Next
+The intent: what remains and what comes immediately next (seeded BEFORE executing — artifact-first). A resume starts here.
 
-## Pending
-Pending phases/tasks (ref: plan-doc; or `TASKS.md`) still to do.
+## Open questions
+Live doubts not yet resolved (ideally "None"). Deferred ones move to the session's `BACKLOG` or the flow doc's `## Open questions`.
 
-## Next
-Next phase/task (ref: plan-doc; or `TASKS.md`) to continue from on resume.
+### Optional sections
+
+- `## Excluded` — phases/tasks explicitly excluded, with reason (the `aw status` dashboard reads it for the discarded list).
+- The `checkpoint-write` hook (PreCompact/SessionEnd) may write a **machine snapshot** with its own headings (`Last action`, `Next step`, `Files touched`, `Refs`, …) and `_[AI: …]_` placeholders — complete the placeholders; the loop-owned contract above still governs what the loop writes.

package/skills/w/artifacts/artifacts-core/SESSION.md

@@ -21,4 +21,4 @@ Session type, **set by the parent loop** (not the user). Authoritative catalog:
 > `research` is **not** a session type the loops create. Research is an **inline** activity: ANALYSIS-FILE / CONCLUSIONS are written into whatever session is active (`refine`/`exec`/`quick`) when it does investigation.
 
 ## Success criteria
-The run's **done-condition**, seeded at session creation: a checklist `[ ]` of **falsifiable** items. Executable deliverable → runnable tests/checks; non-executable → inspection rubric (the human ratifies it if subjective). Spec/plan sessions may **reference** the doc's acceptance criteria instead of duplicating them. Full doctrine: [`../../loops/CHASSIS.md`](../../loops/CHASSIS.md) § *Verification-first*.
+The run's **done-condition**, seeded at session creation: a checklist `[ ]` of **falsifiable** items. Executable deliverable → runnable tests/checks; non-executable → inspection rubric (the human ratifies it if subjective). Spec/plan sessions may **reference** the doc's acceptance criteria instead of duplicating them. The convergence gate **flips** each criterion to `- [x]` as it turns green — on close the checklist reflects the real final state. Full doctrine: [`../../loops/CHASSIS.md`](../../loops/CHASSIS.md) § *Verification-first*.

package/skills/w/commands/fix-git.md

@@ -11,7 +11,7 @@ allowed-tools:
 
 # fix-git — merge-conflict resolver (transversal)
 
-Single-pass, **no loop, no session**, **never writes `docs/`**. **Transversal** command (belongs to no SPEC / PLAN / QUICK flow). **Workspace-agnostic**: operates on any git repo — the given `<source>` (path or alias), or the cwd — without requiring `.workflow/`.
+Single-pass, **no loop, no session**, **never writes `docs/`**. **Transversal** command (belongs to no SPEC / PLAN / QUICK flow). **Workspace-agnostic**: operates on any git repo — the given `<source>` (path or alias), or the cwd — without requiring `.workflow/`. Everything user-facing (questions, proposals, the report) goes in the **user's language**.
 
 ## Run
 

package/skills/w/commands/plan-exec.md

@@ -14,6 +14,13 @@ allowed-tools:
 
 Starts or resumes `plan-exec-loop` (Layer 2), which executes the real work phase by phase. The plan (`docs/plans/PPP-plan-<slug>.md`) is a living document the loop keeps updated (phase and task state).
 
+> **Hard floor — applies even if you read nothing beyond this file:**
+>
+> 1. **Session first** — create/resume the run's session before touching code: `aw session-create --type exec --name <slug>-plan-exec`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 2. **Git/DB** — verify each source's expected branch before editing (`aw check-branch`); commits are **proposed**, never executed without approval; **never** `push`/`--amend`/`--no-verify`; never execute DML/DDL (SQL goes to the session's `SCRIPTS.sql`).
+> 3. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
+> 4. **Language** — everything user-facing (questions, option labels, reports) goes in the **user's language**.
+
 ## Run the loop
 
 `plan-exec-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:

package/skills/w/commands/plan-new.md

@@ -14,6 +14,13 @@ allowed-tools:
 
 SPEC → PLAN bridge. Turns the "what" (refined spec) into the "how" (plan). Delegates to `plan-new-loop` (Layer 2).
 
+> **Hard floor — applies even if you read nothing beyond this file:**
+>
+> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-plan-new`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
+> 3. **Write boundary** — this flow writes only `docs/plans/…` (with confirmation if it exists); nothing else lands in `docs/`.
+> 4. **Language** — everything user-facing (questions, option labels, the plan's content) goes in the **user's language**.
+
 ## Input resolution
 
 The skill evaluates `$ARGUMENTS` (specs live in place — `docs/specs/NNN-spec-<slug>.md`; locate via the `docs/specs/NNN-spec-*.md` glob or the exact path):

package/skills/w/commands/plan-refine.md

@@ -16,6 +16,13 @@ An **auxiliary, NOT mandatory** step of the PLAN flow: `spec-refine`'s twin, but
 
 This command does not refine the plan itself: it delegates to `plan-refine-loop` (Layer 2), which iterates, closes gaps and edits the plan **in place**.
 
+> **Hard floor — applies even if you read nothing beyond this file:**
+>
+> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-plan-refine`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
+> 3. **Write boundary** — this flow edits only `docs/plans/…` (in place, with confirmation); nothing else lands in `docs/`.
+> 4. **Language** — everything user-facing (questions, option labels, the plan's content) goes in the **user's language**.
+
 > **Not mandatory.** `plan-exec` runs **any** plan, refined or not — no gate requires passing through here. Use it only when the plan needs adjustments before executing.
 
 ## Input resolution

package/skills/w/commands/quick.md

@@ -14,6 +14,13 @@ allowed-tools:
 
 For scoped, direct tasks that do not justify going through SPEC or PLAN. Creates a light session (traceability + resume) — unless the **entry size gate** escalates to SPEC before starting. Delegates to `quick-loop` (Layer 2).
 
+> **Hard floor — applies even if you read nothing beyond this file:**
+>
+> 1. **Size gate BEFORE any session** — if the objective exceeds a quick (≥2 clear signals: needs architecture · ≥2 sources · several deliverables · large feature/refactor · ambiguous requirements), ask first with these verbatim options: `Cambiar a SPEC` *(recommended)* · `Seguir en quick` · `Recortar alcance`. If it escalates, create **no** quick session.
+> 2. **Session first** — otherwise, before touching code, create/resume the run's session: `aw session-create --type quick --name <slug>-quick`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 3. **Git/DB** — commits are **proposed**, never executed without approval; **never** `push`/`--amend`/`--no-verify`; never execute DML/DDL (SQL goes to the session's `SCRIPTS.sql`).
+> 4. **Language** — everything user-facing (questions, option labels, reports) goes in the **user's language**.
+
 ## Run the loop
 
 `quick-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:

package/skills/w/commands/spec-new.md

@@ -61,6 +61,7 @@ Pending doubts. ← the spec-refine-loop closes them.
 
 **Filling notes:**
 
+- The draft's **content** is written in the **user's language** (the schema headings stay as-is).
 - No `Type` field — `plan-new` infers the how.
 - `Scope` always carries `Out` (what stays out).
 - **Acceptance criteria = static testable criteria** (the "what"): `plan-exec` validates them, but progress is tracked in the PLAN (its Tasks), never by ticking these `- [ ]` in the spec; the spec never mutates by execution, only by a re-refine.

package/skills/w/commands/spec-refine.md

@@ -14,6 +14,13 @@ allowed-tools:
 
 This command does not refine the spec itself: it delegates to `spec-refine-loop` (Layer 2), which iterates, closes gaps and produces the refined spec.
 
+> **Hard floor — applies even if you read nothing beyond this file:**
+>
+> 1. **Session first** — create/resume the run's session before working: `aw session-create --type refine --name <slug>-spec-refine`; keep its `CHECKPOINT.md` updated (`## Completed` · `## Pending / Next` · `## Open questions`).
+> 2. **Ask, don't invent** — user-dependent decisions go through questions with a recommended option first (≤3 content questions + the `flow` control `Compactar`/`Cerrar`).
+> 3. **Write boundary** — this flow edits only `docs/specs/…` (in place, with confirmation); nothing else lands in `docs/`.
+> 4. **Language** — everything user-facing (questions, option labels, the doc's content) goes in the **user's language**.
+
 ## Run the loop
 
 `spec-refine-loop` is **not** a skill invocable by name — it is this command's operating manual (a sibling doc in the bundle). **Load it and execute it end to end**:

package/skills/w/loops/CHASSIS.md

@@ -60,6 +60,8 @@ The loop works **artifact-first**: the artifact is **seeded before** executing a
 
 > The artifact expresses the **intent** (Pending/Next, before) and then the **result** (Completed/DECISION, after), at **every** gap/phase boundary — not only on `Compactar`/`Cerrar`. Session artifacts are the run's live log; the spec/plan is the **guiding base**.
 
+> **Fixed form (hard rule):** an artifact keeps its template's `##` headings **exactly** and is updated **in place** — appending a **duplicate heading** is a contract violation. When a scaffolded section is filled, its `<!-- … -->` guidance comment is **replaced** by the real content. Canonical headings per artifact: its template under [`../artifacts/`](../artifacts/) (CHECKPOINT contract: `Completed` · `Pending / Next` · `Open questions`).
+
 ## Gap-driven convergent engine
 
 The common cycle — each heir instantiates it in its `## Sequence` with its own gap taxonomy:
@@ -144,7 +146,7 @@ Resume **keys off the `CHECKPOINT`** of the run's session, not the existence of
 
 ## Convergence / exit
 
-- **No material gaps** → **convergence gate** (read-only) = **`Success criteria` green** (*verification-first*). Whatever fails **comes back as a gap**; if it passes → the loop offers its closing action. The heirs are **instances** of the same gate: `spec-refine` = analyze gate, `plan-new` and `plan-refine` = plan coherence, `plan-exec` = final validation, `quick` = proportional spot validation.
+- **No material gaps** → **convergence gate** (read-only) = **`Success criteria` green** (*verification-first*). Whatever fails **comes back as a gap**; if it passes → the loop **flips the green criteria** in `SESSION.md` (`- [ ]` → `- [x]`) and offers its closing action. The checklist must reflect the real final state: a criterion left unchecked at `finalize` needs an explicit reason (`Open questions`/`BACKLOG`). The heirs are **instances** of the same gate: `spec-refine` = analyze gate, `plan-new` and `plan-refine` = plan coherence, `plan-exec` = final validation, `quick` = proportional spot validation.
 - `Cerrar` (the `flow` control, at any time) → `finalize`. **`finalize` always persists `CHECKPOINT.md`** (resumable) and, **only if something was deferred/follow-up**, writes `BACKLOG.md` (close reason + the deferred items); closes the session and reports. Progress survives even without a prior `Compactar`.
 
 ## docs/ boundary — no auto-export (hard rule)