create-issflow 1.10.1 → 1.11.1

package/bin/cli.js

@@ -156,6 +156,19 @@ function adapterCursor() {
     '(mirror of `.issflow/commands/`). Caveman ULTRA mode; apply the `karpathy-guidelines`',
     'and `ux-design` skills. See `AGENTS.md` for the role/command/skill map.', '',
   ].join('\n'));
+  writeFile('.cursor/rules/issflow-gates.mdc', [
+    '---', 'description: iStartSoftFlow gates — STATE delivery + plan lock', 'alwaysApply: true', '---', '',
+    'Before any source Edit/Write:',
+    '1. Read `docs/STATE.md` — respect `delivery:` (ETA · WAITING · SLIP · DONE).',
+    '2. If PLAN approval is PENDING → do not edit source (rule 13).',
+    '3. Past `agent_eta` while AGENT_ACTIVE → report SLIP; do not silent-continue.',
+    '4. WAITING_ON_HUMAN / WAITING_STALE → do not pretend the agent is still building.',
+    '5. UI work: locked `design-direction` / `docs/design/tokens.css` — no freehand palette.',
+    '6. Near context gate → `/synthesize` (keep delivery:) + `/clear`, prefer over compact.',
+    '',
+    'Talk to the human as PM/SA. Subagents never address the user.',
+    '',
+  ].join('\n'));
   copyTemplateCommands('.cursor/commands');
   writeFile('.cursor/hooks.json', JSON.stringify({
     version: 1,
@@ -164,7 +177,7 @@ function adapterCursor() {
       subagentStop: [{ command: 'node .issflow/hooks/subagent-stop.js' }],
     },
   }, null, 2) + '\n');
-  warnings.push('cursor: PreCompact has no Cursor equivalent (snapshot ritual degrades to model-run); verify hooks.json against cursor.com/docs/hooks — the schema evolves.');
+  warnings.push('cursor: PreCompact has no Cursor equivalent (snapshot ritual degrades to model-run); plan-gate/context-guard are Claude-strongest — Cursor relies on issflow-gates.mdc + Tier A sessionStart. Verify hooks.json against cursor.com/docs/hooks.');
 }
 
 function adapterGemini() {
@@ -243,6 +256,15 @@ function agentsMd() {
     'Declare your stack (language, framework, infra, auth, test + E2E runner,',
     'planning source) once in `docs/OVERVIEW.md`. Every rule references *your declared',
     'stack* and hardcodes none.', '',
+    '## Host capability (enforcement)', '',
+    '| Host | Hooks | Notes |',
+    '|------|-------|-------|',
+    '| Claude Code | Full (SessionStart · PreToolUse · PreCompact · Stop) | Strongest plan-gate + context-guard |',
+    '| Cursor | sessionStart + subagentStop + `.cursor/rules` | Partial — model-run gates via `issflow-gates.mdc` |',
+    '| Codex / Gemini / Aider | model-run rituals | Run SESSION-OPEN Tier A by hand |',
+    '',
+    'You talk as **PM/SA**. Subagents never chat with you. Delivery ETA lives in',
+    '`docs/STATE.md` (`delivery:`). See `.issflow/models/MODEL-MATRIX.md` for model tips.', '',
   ].join('\n');
 }
 
@@ -265,22 +287,25 @@ function flowConfig() {
   return JSON.stringify({
     context: {
       window: 0,
-      warnPct: 60,
-      gatePct: 78,
+      warnPct: 55,
+      gatePct: 70,
+      injectMaxLines: 25,
       _note: 'Context-budget watchdog (.issflow/hooks/context-guard.js, PreToolUse hook). '
         + 'window 0 = auto-detect from the model id (200000 for standard models). '
-        + 'Some 1M-context models report their id WITHOUT a [1m] tag, so auto-detect '
-        + 'assumes 200000 and may false-gate around 156k — if you run a 1M model, set '
-        + 'window:1000000 here by hand. warnPct = soft non-blocking nudge; gatePct = hard '
-        + 'block on NEW build work (Edit/Write to SOURCE files). Checkpoint paths '
-        + '(docs/**, STATE/ISSUES/snapshots) and all Bash are never blocked; Task '
-        + 'delegation is never gated (a subagent isolates noise and shrinks context).',
+        + 'warnPct soft nudge; gatePct hard block on NEW source Edit/Write. Prefer '
+        + '/synthesize + /clear (keep delivery:) over compact near gate. Checkpoint '
+        + 'docs/** never gated.',
+    },
+    delivery: {
+      staleAfterHours: 24,
+      phaseHours: { S: 2, M: 4, L: 8, XL: 16 },
+      assumptionBudgetPerPhase: 3,
+      _note: 'Agent-active ETA uses phaseHours by size. Waiting-on-human pauses ETA; '
+        + 'after staleAfterHours → WAITING_STALE.',
     },
     sprint: {
       defaultCapacity: 8,
-      _note: 'Sprint layer (/sprint). defaultCapacity = points committed to the FIRST '
-        + 'sprint before any velocity history exists; later sprints size to the rolling '
-        + 'completed-velocity average. Optional — /sprint falls back to 8 if absent.',
+      _note: 'Sprint layer (/sprint). defaultCapacity = points for first sprint.',
     },
   }, null, 2) + '\n';
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-issflow",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Scaffold the iStartSoftFlow AI-coding workflow into a project. Stack-agnostic, tool-agnostic (Claude Code, Codex, Cursor, Gemini, Aider), non-destructive.",
   "bin": {
     "create-issflow": "bin/cli.js"

package/template/.issflow/README.md

@@ -17,7 +17,10 @@ This directory is the **portable workflow kit** (tool-agnostic). Every
 | `skills/` | On-demand cookbooks (ux-design, ui-ux-pro-max, security, support-triage, …) |
 | `hooks/` | Lifecycle enforcement scripts |
 | `istartsoft-flow/` | METHODOLOGY.md — every hard rule lives here once |
-| `templates/` | Proposal / UX pack / architecture / CR / FEATURE / automation |
+| `templates/` | Proposal / UX pack / architecture / CR / FEATURE / design picker · platforms |
+| `models/` | MODEL-MATRIX.md — cross-host model guidance (aliases stay haiku/sonnet/opus) |
+| `routing/` | Advisory model router (fail-closed) |
+| `scripts/` | Portable helpers (e.g. token-lint.js) |
 
 ## Claude Code only
 

package/template/.issflow/agents/planner.md

@@ -79,7 +79,7 @@ token unambiguously. Do not put prose containing the word `approved` after a
 
 ## Sprint 1: <name>  [goal: <one-line user-visible increment>]   ← sprint headers optional; group a few phases
 
-## Phase 1: <name>  [5 pts]  [status: pending]
+## Phase 1: <name>  [5 pts]  [size: S|M|L|XL]  [lane: lite|full]  [status: pending]
 
 - slice: <what works end-to-end after this phase>
 - rationale: <why this slice, why now — the user / business value (from the PRD)>
@@ -88,11 +88,16 @@ token unambiguously. Do not put prose containing the word `approved` after a
 - acceptance (sharp, testable):
   - GIVEN <state> WHEN <action with concrete input> THEN <exact observable output>
   - edge/negative: <input> -> <expected handling>
+  - (UI) task check: primary user completes the job without guessing
 - impl notes: <constraints, gotchas, patterns to follow — so the implementer needs no extra digging>
 - qa focus: <what the tests must especially probe — abuse / edge cases>
 - external: <service name, or “none”>
   …
 
+Plan-Ready (orchestrator checks before human approve): every phase has testable
+acceptance · no TBD on auth/money/PII/primary surfaces · size+lane set · UI phases
+reference screen IDs or locked direction · dependencies clear.
+
 ## Phase N: <name — final code phase>  [status: pending]
 
 - slice: <what works + app is deployed and reachable>

package/template/.issflow/agents/synthesizer.md

@@ -17,14 +17,16 @@ Do NOT touch docs/ENDPOINTS.md — owned by implementer.
 ## Standard tasks (every phase — do all, in order)
 
 1. STATE.md — rewrite, do not append. Keep ONLY:
-   - current phase + status
+   - current phase + status + stage
    - what was just completed (1-3 bullets)
    - the immediate next action
    - any open blocker
    PRESERVE verbatim (never blank on rewrite): the `plan:` line (the PLAN-APPROVAL
-   sign-off record, hard rule 13) and the `sprint:` line (active-sprint marker) if
-   present — load-bearing gate/standup state, not transient progress.
-   Target: under 25 lines.
+   sign-off record, hard rule 13), the `sprint:` line if present, **and the entire
+   `delivery:` block** (agent_eta / status / waiting_* / slip) — load-bearing for
+   finish-date honesty. Also preserve `design-direction:`, `design:`, `architecture:`,
+   `surfaces:`, `timezone:` when present.
+   Target: under ~30 lines including delivery.
 
 2. ISSUES.md — dedup + compress:
    - merge duplicate / near-duplicate issues.

package/template/.issflow/commands/change-request.md

@@ -38,12 +38,18 @@ Also classify commercial lane:
   `/support` or `/quick` — not a billable CR unless the client expands scope.
 - **Billable CR** → continue below.
 
+**No full grill-me.** If the change hits surfaces / auth / UX / architecture:
+ask **1–3 mini questions** (brief-back with recommended answers), then continue.
+Deep design re-lock happens later via `/design` if rule 15 reopens.
+
 ## STEP 2 — IMPACT ANALYSIS
 Determine:
 - phases affected — **done phases are frozen** (their cost is already spent and
   counts); new / changed phases; cut phases (credit back the un-started effort).
 - knock-on effects — architecture, **UX pack**, **security (re-threat-model?)**,
-  tests, timeline. If UX or arch artifacts change, those gates re-open (rule 15).
+  tests, timeline, **design-direction / tokens**. If UX or arch artifacts change,
+  those gates re-open (rule 15). If direction must change, reset
+  `design-direction:` to PENDING (re-picker).
 - dispatch `researcher` (DESIGN or IMPL) if the change needs grounding in facts.
 
 ## STEP 3 — RE-ESTIMATE (the DELTA only)
@@ -52,10 +58,12 @@ Determine:
   estimate memo or chat-recorded answers.
 - If rate / contingency is missing → **ASK once** (same rule as `/propose`). Never
   invent a kit default rate; never commit personal rates into public kit files.
+- Report **two deltas** in chat: scope_effort Δ (axis A, drives money) and
+  agent_delivery Δ (axis B, calendar when AI may work). Price uses A only.
 - added effort × rate = added cost; cut effort = credit.
 - **net cost Δ** + **new total** vs the approved baseline — as a range.
 - Show rate math **in chat to the human only**.
-- **timeline Δ**. State what stays the SAME so the client sees the price is fair.
+- **timeline Δ** (B agent_delivery + human-gate buffer + new `demo_by`). Refresh STATE `delivery:` if mid-build. State what stays the SAME so the client sees the price is fair.
 
 ### CLIENT-DOC RULE
 Anything the client sees (CR summary, updated PROPOSAL.md / proposal.html) shows

package/template/.issflow/commands/design.md

@@ -1,5 +1,5 @@
 ---
-description: Post-proposal DESIGN + ARCHITECTURE gates — produce UX pack and architecture note, stop for human approve before /phase (hard rule 15).
+description: Post-proposal DESIGN + ARCHITECTURE gates — upgrade locked direction into UX pack + architecture, stop for human approve before /phase (hard rule 15).
 argument-hint: [optional: "ux" | "arch" | "both" · "dry-run"]
 ---
 
@@ -14,44 +14,59 @@ DRY-RUN: if `$ARGUMENTS` contains `dry-run`/`--dry-run`, outline what you'd writ
 and STOP. Write nothing.
 
 ## PRE-FLIGHT
-- Read `docs/OVERVIEW.md`, `docs/PLAN.md`, `docs/PROPOSAL.md` (if any), `docs/STATE.md`.
+- Read `docs/OVERVIEW.md`, `docs/PLAN.md`, `docs/PROPOSAL.md` (if any), `docs/STATE.md`,
+  `docs/design/DIRECTION.md`, `docs/design/tokens.css`.
 - PLAN must be approved (rule 13). If a proposal exists for quoted work, it should
   be signed off first (`/propose`) — otherwise warn and confirm they want design
   gates without a commercial proposal (internal projects may skip `/propose` and
   still run `/design`, or skip rule 15 entirely when STATE has `design: n/a` and
   `architecture: n/a` set deliberately for non-quoted work).
+- **Direction:** if UI in scope and `design-direction` is not locked → STOP; run
+  overview Direction Picker first. If locked → **do not** re-run `ui-ux-pro-max`
+  restyle unless the human explicitly asks to change look (then re-approve).
 
 Target: `$ARGUMENTS` → `ux` | `arch` | `both` (default **both**).
 
+## Design scale (pick one; say it out loud)
+
+| Scale | When | Artifact depth |
+|-------|------|----------------|
+| Spike | Feasibility only | Short answer — no UX-PACK |
+| Bounded | Small change to existing UI | Short design in chat or thin UX-PACK + approve |
+| Architectural | New product / subsystem / auth boundary / multi-surface | Full UX-PACK(s) + ARCHITECTURE |
+
 ## STEP 1 — UX PACK (if ux|both)
-1. Apply `ui-ux-pro-max` (visual direction): run the kit engine
-   `.issflow/skills/ui-ux-pro-max/scripts/search.py --design-system` from
-   OVERVIEW product + industry. Fold into UX-PACK tokens — do not create a
-   parallel `design-system/` SoT. If Python 3 is missing, ask me to install it
-   (do not install tools yourself).
-2. Apply `ux-design` skill (authoring mode): wireframe baseline + cookbook direction.
-   Catalogue output must still pass the cookbook (tokens, a11y, no emoji icons).
-3. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
-4. Fill flows, screen inventory, tokens/frame, a11y notes from OVERVIEW + PLAN.
-5. SHOW me UX-PACK.md. **STOP for approval.**
-6. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
+1. Scaffold or update `docs/UX-PACK.md` from `.issflow/templates/UX-PACK-template.md`.
+2. Fold **locked** DIRECTION + tokens — do not invent a second palette.
+3. Apply `ux-design` skill (authoring): wireframe baseline + cookbook. Screen inventory
+   must use stable IDs from propose appendix when present.
+4. Per primary screen: goal, primary CTA, empty/loading/error, <SM and ≥MD notes.
+5. If `surfaces` includes more than web: add `docs/design/<surface>/` notes (PWA /
+   line-oa / mobile packs — see templates under `.issflow/templates/design/platforms/`).
+6. Update `docs/design/inventory.md` — reuse only listed components.
+7. SHOW me UX-PACK.md. **STOP for approval.**
+8. On approve: stamp `> Approval: approved <date> v<n>`; set `design: approved <date>`
    in STATE.md; HISTORY line `design v<n> approved`.
-7. On change request: revise and re-show; header stays PENDING.
+9. On change request: revise and re-show; header stays PENDING.
+10. Quoted + UI: after approve, **regenerate** `docs/proposal.html` screen sheets from
+    the same screen IDs + tokens so the PDF matches what will be built.
 
 ## STEP 2 — ARCHITECTURE (if arch|both)
 1. Dispatch `researcher` (DESIGN) only if open unknowns remain; else use OVERVIEW.
 2. Scaffold or update `docs/ARCHITECTURE.md` from
    `.issflow/templates/ARCHITECTURE-template.md`.
-3. Apply `code-standards` architecture guidance; security trust boundaries via
+3. Include **Auth decision record** when users/login exist (provider, session model,
+   identity linking, roles) — grill briefly if still open.
+4. Apply `code-standards` architecture guidance; security trust boundaries via
    `security` skill when relevant.
-4. SHOW me ARCHITECTURE.md. **STOP for approval.**
-5. On approve: stamp header; set `architecture: approved <date>` in STATE.md;
+5. SHOW me ARCHITECTURE.md. **STOP for approval.**
+6. On approve: stamp header; set `architecture: approved <date>` in STATE.md;
    HISTORY line `architecture v<n> approved`. Optionally `/log-decision` for
    material pattern choices.
-6. On change request: revise and re-show.
+7. On change request: revise and re-show.
 
 ## STEP 3 — HANDOFF
 When both required gates are approved (or N/A for internal skip):
 - Tell me `/phase` is unblocked for rule 15.
-- Reminder: frontend phases still run the `ux-design` CLOSE check (rule 9);
-  architecture drift still needs `/log-decision` (rule 8).
+- Reminder: frontend phases still run the `ux-design` CLOSE check (rule 9) + task
+  check; architecture drift still needs `/log-decision` (rule 8).

package/template/.issflow/commands/feature.md

@@ -4,7 +4,12 @@ argument-hint: [path to Feature doc, e.g. docs/features/<slug>/FEATURE.md · "dr
 ---
 
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself. Subagents cannot talk to the user; only YOU can.
+you do NOT implement or debug yourself. Speak PM-style (ETA / stage / WAITING /
+DONE). Subagents cannot talk to the user; only YOU can.
+
+Before build slices: set STATE `delivery:` agent_eta from phase sizes; heartbeat
+stage lines; on human gates set WAITING_ON_HUMAN + waiting_since + stale_after.
+UI work must respect `docs/design/tokens.css` + inventory when present.
 
 Target doc: $ARGUMENTS  (default: the single `docs/features/*/FEATURE.md` whose
 `> Status:` reads `approved, pending` — zero or multiple candidates -> STOP and list them.)

package/template/.issflow/commands/overview.md

@@ -81,14 +81,30 @@ Store the round-1 answers as working context — do NOT write OVERVIEW.md yet.
 — the whole plan is built on these, so lock them first. Show a concise summary and
 STOP for sign-off (planning always asks, both modes):
 - **Tech stack** — language · framework · infra · auth · datastore · test + E2E runner
+- **Auth checklist** (if any login/user): provider · session vs token · social/LINE link · roles — must be answered or explicit `n/a`
+- **Surfaces** — default `web-responsive` if unset; also pwa / line-oa / mobile-app as needed
 - **Architecture** — the pattern (Feature-Based by default) + the folder layout
-- **UX direction** — design system / tokens + the wireframe baseline (the frame)
+- **UX direction** — see STEP 5c Direction Picker when UI is in scope
 - **Data & integrations** — core data model + external services + their limits
-- **Conventions** — naming idiom (`code-standards`) + autonomy mode (AUTO / GUIDED)
+- **Conventions** — naming idiom (`code-standards`) + autonomy mode (AUTO / GUIDED) — recommend AUTO for PM-mode builds
 - **Estimation config** — unit · rate card · currency · contingency (if quoting)
+- **Timezone** — for delivery ETA dates (default `Asia/Bangkok` when project language is th)
 On any "change X" → revise OVERVIEW.md and re-confirm. Only a signed-off foundation
 proceeds to the planner. (This is the planning confirmation gate.)
 
+### Direction Picker (when UI is in scope)
+
+5c. If the product has UI (default yes unless OVERVIEW says none):
+1. Copy `.issflow/templates/design/picker.html` → `docs/design/picker.html`.
+2. Fill placeholders only (names, swatches, fonts, blurbs, anti-patterns). Prefer
+   `ui-ux-pro-max` `--design-system` output; if Python 3 is missing, use the three
+   fallback presets in the template footer (Calm SaaS / Bold Commerce / Trust Fintech).
+   **Do not freehand redesign the HTML/CSS chrome.**
+3. SHOW me the picker path and STOP for choice (A/B/C).
+4. On choice: write `docs/design/DIRECTION.md` + `docs/design/tokens.css` from templates;
+   set STATE `design-direction: locked <id> <date>`; HISTORY line.
+5. Internal skip: only if UI truly out of scope — set `design-direction: n/a`.
+
 ### Plan
 
 6. Hand OVERVIEW.md + design-research findings to the `planner` subagent.
@@ -96,19 +112,33 @@ proceeds to the planner. (This is the planning confirmation gate.)
    - Start with Phase 0 (infra setup) only if infra is self-managed; with
      managed infra, Phase 0 is N/A and the plan starts at Phase 1.
    - End with a final code phase that contains the deploy task block.
+   - Tag each phase `size: S|M|L|XL` and `lane: lite|full` (lite only when no new
+     primary UI and not final/security-sensitive).
 
-7. Create docs/STATE.md:
+7. Create docs/STATE.md (keep ≤ ~25 lines at top; include delivery board):
 ```
-
 # STATE
 
 phase: 0 (pending)
 plan: PENDING
+design-direction: locked <id> <date> | PENDING | n/a
 design: PENDING
 architecture: PENDING
+surfaces: web-responsive
+timezone: Asia/Bangkok
+delivery:
+  package: bootstrap
+  agent_eta: none
+  phase_etas: []
+  status: WAITING_ON_HUMAN
+  waiting_for: plan approve
+  waiting_since: <ISO-date>
+  stale_after: <ISO-date+24h>
+  eta_paused: true
+  next_human_action: approve PLAN.md
+  slip_reason: none
 completed: project bootstrapped — design research done, double grill done
 blocker: none
-
 ```
 (For internal non-quoted work you may set `design: n/a` and `architecture: n/a`
 instead of PENDING so rule 15 does not block `/phase`.)
@@ -130,10 +160,17 @@ instead of PENDING so rule 15 does not block `/phase`.)
 11. The plan is the contract the whole AUTO dev loop builds against, so it ends with a
     human sign-off — the planning twin of the `/propose` commercial gate.
 
-    - SHOW me PLAN.md (and note any open risks the planner flagged). **STOP for approval.**
+    **Plan-Ready checklist** (must pass before you ask me to approve):
+    - Every phase has testable acceptance (no vague “make it good”)
+    - No TBD on auth / money / PII / primary surfaces
+    - If UI in scope: `design-direction` locked (or n/a) and screen IDs listed or stubbed
+    - Phase dependencies clear; size + lane tags present
+    - Open risks listed — material open questions block approve
+
+    - SHOW me PLAN.md + Plan-Ready result. **STOP for approval.**
     - On **approval**: record the sign-off in three places —
       1. stamp the PLAN.md header `> Approval: approved <YYYY-MM-DD> v1`;
-      2. set `plan: approved <YYYY-MM-DD>` in docs/STATE.md;
+      2. set `plan: approved <YYYY-MM-DD>` in docs/STATE.md; clear waiting_for / set delivery status AGENT_ACTIVE when build starts;
       3. append `<YYYY-MM-DD> plan v1 approved` to docs/HISTORY.md (date-first, to
          match the other HISTORY lines).
       Only now may `/phase` / `/sprint` run.
@@ -144,7 +181,9 @@ instead of PENDING so rule 15 does not block `/phase`.)
 
 Optional next steps (client / quoted work):
 1. `/propose` — proposal + estimate (asks rate in chat; client docs stay totals-only).
+   Screen appendix MUST use locked `docs/design/tokens.css` + screen IDs.
 2. `/design` — UX pack + architecture approve gates (hard rule 15) before `/phase`.
+   Upgrade existing frames — do not re-roll direction if locked.
 
 Internal or personal projects may skip `/propose` and set `design: n/a` /
 `architecture: n/a` in STATE, then go to `/phase`.

package/template/.issflow/commands/phase.md

@@ -1,15 +1,19 @@
 ---
-description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Both with the debug circuit breaker and the regression guard at CLOSE.
-argument-hint: [phase number · "dry-run" to preview what the phase would do]
+description: Run one phase end-to-end. TDD phases run SCAFFOLD -> RED -> GREEN; non-TDD phases run IMPLEMENT -> TEST. Supports --lite. ETA + stuck/SLIP reporting required.
+argument-hint: [phase number · "lite" · "dry-run"]
 ---
 
 
 Caveman ULTRA mode. You are the ORCHESTRATOR. Route work to subagents —
-you do NOT implement or debug yourself.
+you do NOT implement or debug yourself. Speak to the human as **PM** (status /
+ETA / blockers) — not as a pair-programming developer.
 
 Note: subagents cannot talk to the user. Only YOU can.
 
 Target phase: $ARGUMENTS  (default: the phase marked pending in docs/PLAN.md)
+LANE: if args contain `lite` OR PLAN phase has `lane: lite` → LITE mode.
+  LITE forbidden when: final phase · new primary UI flow · auth/money/PII surface.
+  LITE still requires ETA + DoD + (if any UI touch) task check happy path.
 
 ---
 
@@ -55,14 +59,33 @@ c. PHASE STATE CHECK: Read docs/STATE.md and docs/PLAN.md.
 d. FINAL PHASE CHECK: Read docs/PLAN.md. Is this the last phase (no further
    pending phases after this one)? Record this as IS_FINAL_PHASE=true/false.
 
+e. DELIVERY / ETA BOARD (required before RESEARCH):
+   Update `docs/STATE.md` `delivery:` block:
+   - Set `status: AGENT_ACTIVE`, `eta_paused: false`, clear waiting_for if resuming.
+   - Set `agent_eta` and `phase_etas` using `flow-config.json` → `delivery.phaseHours`
+     by phase size (S/M/L/XL) and project timezone.
+   - Stage line: `stage: RESEARCH | next: … | blocker: none`
+   - Assumption budget: max `assumptionBudgetPerPhase` (default 3). Exceed → STOP
+     for `/replan` or human — do not keep guessing.
+   - If status was WAITING_ON_HUMAN and `stale_after` passed → set `WAITING_STALE`,
+     tell the human `next_human_action`, do not pretend AI is still building.
+   - If wall-clock past `agent_eta` while AGENT_ACTIVE → **SLIP**: report reason +
+     new ETA or BLOCKED. Never silently continue past ETA.
+
+f. LITE shortcuts (when LITE): skip dedicated researcher if unknowns are none;
+   skip browser E2E if no UI; CLOSE = regression + lint + secrets (and UI task
+   check if UI touched). Full path otherwise.
+
 
 ---
 
 ## 1. RESEARCH + TDD APPLICABILITY
 
-Dispatch `researcher` in IMPL mode scoped to this phase.
+If LITE and no open unknowns: skip researcher; note "lite: research skipped" in STATE.
+Else dispatch `researcher` in IMPL mode scoped to this phase.
 Returns terse summary + path. Read the file only if needed.
 Unknowns block the phase -> re-dispatch narrowed. No guessing.
+After each major stage change, rewrite STATE `stage:` + one-line progress (heartbeat).
 
 SECURE SDLC (design): if this phase touches a TRUST BOUNDARY (auth, untrusted input,
 data store, money, PII), threat-model it now (`security` skill) and fold the abuse
@@ -114,13 +137,13 @@ NOT edit them). Fill to green. Budget 3, WARN@2, STUCK@3.
 
 ## 3c. TEST (e2e) — FRONTEND phases only
 
-If this phase ships UI: dispatch `e2e-runner` (BLIND) to write + run browser E2E
-for the slice using the declared E2E runner (it brings the test stack up/down
-itself). Then run the `ux-design` cookbook + wireframe check on the new UI
-(hard rule 9): the UI must match the wireframe frame and pass the cookbook
-(tokens, a11y/WCAG AA, states, breakpoints). A `ux-design` BLOCK is a GATE FAIL.
-Do not re-run `ui-ux-pro-max` `--design-system` here — the look is locked in the
-approved UX pack.
+If this phase ships UI:
+- FULL: dispatch `e2e-runner` (BLIND) for browser E2E of the slice.
+- LITE with UI touch: skip full E2E only if a **task check** still proves the
+  primary user job (scripted or manual-recorded happy path) — never skip both.
+- Always run the `ux-design` cookbook + wireframe check (hard rule 9). Tokens must
+  come from `docs/design/tokens.css` — raw hex/spacing in components = BLOCK.
+  Do not re-run `ui-ux-pro-max` `--design-system` here — look is locked.
 Non-frontend phase -> skip §3c.
 
 PHASE GATE (rule 5) -> go to §4/§5/§6 (see GATE below).
@@ -193,6 +216,12 @@ REGRESSION GATE (before closing — Feature 3):
 - IF IS_FINAL_PHASE: additionally run `scripts/regression.sh --real` (full real
   corpus). A failure blocks close.
 
+UI TASK CHECK (if this phase touched UI — required even in LITE):
+- Happy path: primary user can complete the phase's user-visible job without guessing.
+- Viewport: primary breakpoint (≥MD) + <SM if mobile is primary.
+- Tokens: no raw hex / off-grid spacing — prefer `node scripts/token-lint.js` when present.
+- Fail → FIX; do not close.
+
 CODE-STANDARDS GATE (rule 12): the formatter + linter are clean (the language's
 standard tool); names follow the language's own idiom; the code conforms to the
 declared architecture (Feature-Based by default). Lint/format errors or idiom
@@ -206,6 +235,8 @@ SECURITY GATE (rule 11 — Secure SDLC build stage):
 - Open HIGH/CRITICAL findings BLOCK the close -> route to FIX. Deploying to prod
   with open high/critical findings is a hard-stop (human sign-off).
 
+DELIVERY UPDATE: set this phase's `phase_etas` entry done; refresh next phase
+`agent_eta` or set `delivery.status: DONE` if package complete. Clear waiting_*.
 Mark phase `done` in docs/PLAN.md.
 
 SPRINT STANDUP (if a sprint is active — STATE.md shows `sprint: <n> (active)`):
@@ -256,10 +287,16 @@ After each step, update docs/STATE.md:
 phase: <n> (in progress)
 plan: approved <date>          ← carry forward; never drop the rule-13 sign-off record
 tdd: <true|false>
+stage: <RESEARCH|SCAFFOLD|RED|GREEN|TEST|FIX|CLOSE>
 completed: <steps done so far>
 next: <exact next step>
 blocker: <none or open issue>
+delivery:                      ← preserve + update; never drop
+  agent_eta: <date>
+  status: AGENT_ACTIVE | WAITING_ON_HUMAN | WAITING_STALE | BLOCKED | SLIP | DONE
+  …
 
 ```
-Keep STATE.md small — overwrite, do not append. Preserve the `plan:` line on every
-overwrite (the PLAN-APPROVAL record, hard rule 13); do not blank it.
+Keep STATE.md small — overwrite, do not append. Preserve `plan:` and `delivery:`
+on every overwrite. When entering WAITING_ON_HUMAN: set waiting_for, waiting_since,
+stale_after (+24h), eta_paused: true, next_human_action (one sentence).

package/template/.issflow/commands/propose.md

@@ -24,6 +24,11 @@ and its `> Approval:` header still reads `PENDING` (or is missing), STOP and rou
 to the `/overview` PLAN-APPROVAL gate before quoting — pricing an unapproved plan
 re-prices on every revision.
 
+DIRECTION CHECK (UI in scope): STATE `design-direction:` must be `locked …` (or
+explicit `n/a` if no UI). Still PENDING → STOP and run overview STEP 5c Direction
+Picker first. Screen appendix must use `docs/design/tokens.css` colors — never invent
+a parallel palette.
+
 ## STEP 1 — SCOPE
 List the deliverables (features / epics) from OVERVIEW / PRD. Mark each
 **in-scope** or **out-of-scope** explicitly — naming out-of-scope items now is what
@@ -32,9 +37,15 @@ prevents silent scope creep (and grounds change-order re-pricing later).
 ## STEP 2 — PHASE BREAKDOWN (internal)
 Derive the vertical-slice phases (or read `docs/PLAN.md` if it exists). Size each:
 - complexity: **S | M | L | XL**
-- effort: an ideal-days RANGE (e.g. 2–3d), + story points if your team uses them
+- **scope_effort** (axis A): ideal-days RANGE for commercial value (human-equivalent)
+- **agent_delivery** (axis B): agent-active hours/days from `flow-config.json` →
+  `delivery.phaseHours` (S/M/L/XL) — wall-clock when AI may work, **excluding**
+  waiting-on-human gates
 - risk / unknowns: what could move the estimate
 
+Show **both axes in chat to the human** every time. Client price uses **A only**.
+Client timeline may show B as “AI-assisted delivery (if approvals are timely)”.
+
 Keep this sizing for the **chat math**. Do **not** dump every PLAN phase onto the
 client table — collapse into packages in STEP 5.
 
@@ -109,9 +120,12 @@ production is up within the scope on this quote. **Never** construction wording
 ## Scope        — in-scope: … | out-of-scope: …
 ## Packages     — table: package | cost
                 — or package | estimated | billed | cost  (only if hours columns requested)
-## Total        — <low>–<high>   ← totals only; no “incl. X% contingency”
-## Timeline     — <estimate>, dependency order
-## Assumptions  — …
+## Delivery clocks (internal + chat; client page may show demo dates only)
+                — per package: scope_effort (A · pricing) | agent_delivery (B · agent-active)
+                  | demo_by (calendar, assuming human gates ≤ staleAfterHours)
+## Total        — <low>–<high>   ← totals only from A; no “incl. X% contingency”
+## Timeline     — demo_by per package + dependency order (B pauses while waiting on humans)
+## Assumptions  — … (if human gates slower than SLA, demo_by slips — not an agent hang)
 ## Exclusions   — … (hosting/database: client pays provider, if that was the answer)
 ## Payment      — software delivery events + the asked split (if any)
 ## Screens      — docs/proposal.html pages 2–N (or “none — no UI in scope”)
@@ -149,14 +163,18 @@ production is up within the scope on this quote. **Never** construction wording
    **Screen appendix (required when UI is in scope)** — same `docs/proposal.html`,
    not a second signable file. After page 1's page-break, emit `.sheet.screens`
    into `{{SCREEN_SHEETS}}`:
-   - Build frames from **PLAN + OVERVIEW** modules/capabilities (empty chrome is
-     fine). Do **not** wait for UX-PACK (that gate is after sign-off).
+   - Build frames from **PLAN + OVERVIEW** with stable **screen IDs** (`S-01`…).
+   - Apply locked **token colors** from `docs/design/tokens.css` into the template
+     CSS variables / inline token slots — same direction the build will use.
    - Cover **every** in-scope module and capability — not a 4–8 frame sampler.
    - Group sheets by package; module bar on each sheet; numbered short captions
      under frames.
-   - Label: not pixel-binding. Sign on page 1 only. **No emoji as icons.**
+   - Label: structure-binding via screen IDs; visuals follow locked direction (still
+     not pixel-perfect). Sign on page 1 only. **No emoji as icons.**
    - Use the template's desk/phone/sidebar/card/table CSS. Do not invent a
      parallel stylesheet.
+   - Per package row (internal + chat): `scope_effort` · `agent_delivery` ·
+     `demo_by` (calendar date assuming human gates answer within staleAfterHours).
 
    Print-ready (Ctrl/Cmd-P → A4 → Save as PDF). Keep PROPOSAL.md and proposal.html
    in sync.

package/template/.issflow/commands/quick.md

@@ -26,6 +26,8 @@ Steps:
    One cheap turn beats redoing a misunderstood edit. (Already confirmed in this
    conversation? say so and proceed — don't re-ask the same understanding.)
 1. grep docs/ISSUES.md for anything related.
+1b. If the change touches UI: read `docs/design/tokens.css` + inventory when present.
+    Use semantic tokens only — no raw hex/spacing literals in components.
 2. Make the change. Smallest diff that works.
 3. Run it — lint/typecheck/smoke. Show me result.
 4. REGRESSION GUARD: run `scripts/regression.sh` (mock corpus). No corpus in this

package/template/.issflow/flow-config.json

@@ -1,12 +1,19 @@
 {
   "context": {
     "window": 1000000,
-    "warnPct": 60,
-    "gatePct": 78,
-    "_note": "window = this session's real context window. THIS repo runs Opus 4.8 [1m] but the transcript records model id as 'claude-opus-4-8' (no [1m] tag), so auto-detect (window:0) would wrongly assume 200000 and false-gate around 156k. Set it explicitly here. Kit template default stays 200000 — override per your model. warnPct = soft non-blocking nudge. gatePct = hard PreToolUse block on NEW build work (Edit/Write to SOURCE files). Checkpoint paths (docs/**, STATE/ISSUES/snapshots) and all Bash (git) are never blocked; Task delegation is never gated (a subagent isolates noise and shrinks orchestrator context)."
+    "warnPct": 55,
+    "gatePct": 70,
+    "injectMaxLines": 25,
+    "_note": "window = session context. Template default for new installs should be 200000 unless overridden. warnPct soft nudge; gatePct hard block on NEW source Edit/Write. Prefer /synthesize + /clear (handoff) over compact near gate. Checkpoint docs/** never gated."
+  },
+  "delivery": {
+    "staleAfterHours": 24,
+    "phaseHours": { "S": 2, "M": 4, "L": 8, "XL": 16 },
+    "assumptionBudgetPerPhase": 3,
+    "_note": "Agent-active ETA uses phaseHours by size tag. Waiting-on-human pauses ETA; after staleAfterHours status becomes WAITING_STALE."
   },
   "sprint": {
     "defaultCapacity": 8,
-    "_note": "Sprint layer (/sprint). defaultCapacity = points committed to the FIRST sprint before any velocity history exists; later sprints size to the rolling completed-velocity average. Optional — /sprint falls back to 8 if this block is absent."
+    "_note": "Sprint layer (/sprint). defaultCapacity = points for first sprint before velocity exists."
   }
 }