devflow-kit 3.4.0 → 3.6.0

package/src/assets/skills/docs-framework/SKILL.md

@@ -7,60 +7,58 @@ allowed-tools: Read, Bash, Glob
 
 # Documentation Framework
 
-The canonical source for documentation conventions in Devflow. All agents that persist artifacts must follow these standards.
+The canonical source for what Devflow names under `.devflow/docs/`. A command that writes or looks up a doc path follows it, and the one place a command differs is stated here as an exception, never left implicit.
 
 ## Iron Law
 
 > **ALL ARTIFACTS FOLLOW NAMING CONVENTIONS**
 >
-> Timestamps are `YYYY-MM-DD_HHMM`. Branch slugs replace `/` with `-`. Topic slugs are
-> lowercase alphanumeric with dashes. No exceptions. Inconsistent naming breaks tooling,
-> searching, and automation. Follow the pattern or fix the pattern for everyone.
+> A run directory is `YYYY-MM-DD_HHMM` in local time; a second run in the same minute takes
+> seconds (`YYYY-MM-DD_HHMMSS`). Branch slugs replace `/` with `-`. Topic slugs are lowercase
+> alphanumeric with single dashes, at most 50 characters. The exceptions are the ones listed
+> under Naming Conventions, and no others. Inconsistent naming breaks tooling, searching, and
+> automation. Follow the pattern or fix the pattern for everyone.
 
 ---
 
 ## Directory Structure
 
-All generated documentation lives under `.devflow/docs/` in the project root:
+All generated documentation lives under `.devflow/docs/` at the checkout's toplevel:
 
 ```
 .devflow/docs/
-├── reviews/{branch-slug}/              # Code review reports per branch
-│   ├── .last-review-head              # HEAD SHA of last completed review (for incremental)
-│   ├── {timestamp}/                   # Timestamped review directory (YYYY-MM-DD_HHMM)
-│   │   ├── {focus}.md                 # Review agent report (e.g., security.md, architecture.md)
-│   │   ├── review-summary.md          # Synthesize agent output
-│   │   └── resolution-summary.md      # Written by /resolve (if run)
-│   └── {timestamp}/                   # Second review (incremental)
-│       ├── {focus}.md
-│       └── review-summary.md
-├── bug-analysis/{branch-slug}/          # Bug analysis reports per branch
-│   ├── .last-analysis-head            # HEAD SHA of last analysis (for incremental)
-│   └── {timestamp}/                   # Timestamped analysis directory (YYYY-MM-DD_HHMM)
-│       ├── {focus}.md                 # Analyzer report (e.g., security.md, functional.md)
+├── reviews/{branch-slug}/              # /code-review, per branch
+│   ├── .last-review-head              # HEAD SHA of the last completed review (incremental)
+│   └── {timestamp}/                   # one directory per review
+│       ├── {focus}.md                 # Review agent report (security.md, architecture.md, ...)
+│       ├── review-summary.md          # Synthesize agent output
+│       ├── resolution-summary.md      # /resolve
+│       ├── evidence.md                # /resolve: appended test-plan claims
+│       └── stale-plan.md              # /resolve: stale test-plan lines
+├── bug-analysis/{branch-slug}/         # /bug-analysis, per branch
+│   ├── .last-analysis-head            # HEAD SHA of the last analysis (incremental)
+│   └── {timestamp}/
+│       ├── {focus}.md                 # Debug agent report
 │       ├── static-findings.md         # Raw static analysis tool output
 │       ├── bug-analysis-summary.md    # Synthesize agent output
-│       └── resolution-summary.md      # Written by /resolve (if run)
-├── design/                             # Design artifacts from /plan
-│   └── {ISSUE_ID}-{topic-slug}.{timestamp}.md  # Design document
-├── tickets/{slug}/                     # Ticket sets from /dynamic-tickets
-│   └── {YYYY-MM-DD_HHMM}/             # Timestamped ticket directory
-│       ├── {ticket-slug}.md            # Individual ticket files
-│       └── tracking-issue.md           # Tracking issue body (GitHub sync)
-├── waves/{slug}/                       # Wave run reports from /dynamic-build
-│   └── {YYYY-MM-DD_HHMM}/             # Timestamped wave directory
-│       └── wave-report.md              # Wave run summary and status
-├── research/{topic-slug}/              # Research artifacts per topic
-│   └── {YYYY-MM-DD_HHMM}/             # Timestamped research directory
-│       ├── {type}.md                  # Research agent outputs (codebase.md, external.md, etc.)
-│       └── research-summary.md        # Synthesize agent output
-├── status/                             # Development logs
-│   ├── {timestamp}.md
-│   ├── compact/{timestamp}.md
-│   └── INDEX.md
-└── swarm/                              # Swarm operation state
-    ├── state.json
-    └── plans/
+│       └── resolution-summary.md      # /resolve (evidence.md and stale-plan.md as in reviews)
+├── research/{topic-slug}/{timestamp}/  # /research
+│   ├── {type}.md                      # Research agent output (codebase.md, external.md, ...)
+│   └── research-summary.md            # Synthesize agent output
+├── design/
+│   ├── {ISSUE_ID}-{topic-slug}.{timestamp}.md  # /plan, one issue
+│   ├── multi-{topic-slug}.{timestamp}.md       # /plan, several issues (frontmatter issue: pending)
+│   ├── {topic-slug}.{timestamp}.md             # /plan, no issue
+│   └── {slug}/{timestamp}/            # /dynamic-plan run
+│       ├── {ticket-slug}-plan.md      # one plan per ticket
+│       └── DECISIONS-NEEDED.md
+├── tickets/{slug}/{timestamp}/         # /dynamic-tickets
+│   ├── {ticket-slug}.md
+│   └── tracking-issue.md
+├── waves/{slug}/{timestamp}/wave-report.md   # /dynamic-build
+├── handoff-{branch-slug}.md            # Code agent phase handoff; deleted once the PR exists
+├── evidence-{branch-slug}.md           # /implement test plan and claims; stays after the PR
+└── evidence-wave-{slug}.md             # /dynamic-build wave test plan and claims
 
 .devflow/memory/
 ├── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
@@ -71,47 +69,56 @@ All generated documentation lives under `.devflow/docs/` in the project root:
 └── pitfalls.md                         # Known pitfalls (PF-NNN format)
 ```
 
-`{ISSUE_ID}` in the `design/` path is the filesystem-safe issue identifier the Git agent emits as `- **Issue ID**:` under `### Handoff Values`.
+`{ISSUE_ID}` is the filesystem-safe issue identifier the Git agent emits as `- **Issue ID**:` under `### Handoff Values`. A multi-issue batch fetch returns none, which is why that variant is named `multi-`.
 
 ---
 
 ## Naming Conventions
 
 ### Timestamps
-Format: `YYYY-MM-DD_HHMM` (sortable, readable)
+
+`YYYY-MM-DD_HHMM`, local time (sortable, readable), computed once per run and reused for every path of that run:
 ```bash
 TIMESTAMP=$(date +%Y-%m-%d_%H%M)  # Example: 2025-12-26_1430
 ```
+- **Same-minute collision.** `/code-review`, `/bug-analysis` and `/research` create their run directory themselves: when it already exists, the second run appends seconds (`2025-12-26_143005`). It sorts after its minute, so newest-first listings stay correct.
+- **Workflow runs** (`tickets/`, `design/{slug}/`, `waves/`) are stamped in local time by the workflow that creates them and take no collision suffix: a second run in the same minute writes into the first's directory.
+- A design document's timestamp is the suffix before `.md`, so a listing sorts by that suffix, not by the leading `{ISSUE_ID}`.
 
 ### Branch Slugs
-Replace `/` with `-`, sanitize special characters:
+
+The branch name with every `/` replaced by `-`; case, dots and underscores are kept. A detached HEAD has no name and uses `standalone`:
 ```bash
-BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
+BRANCH_SLUG=$(b=$(git branch --show-current 2>/dev/null); echo "${b:-standalone}" | sed 's/\//-/g')
 ```
+A slug builds a path or reaches a shell only when it matches `^[A-Za-z0-9._-]{1,200}$`. Every command derives `{branch_slug}` (the underscore spelling in `handoff-*` and `evidence-*`) this way, from the branch the work is on.
 
 ### Topic Slugs
-Lowercase, dashes, alphanumeric only, max 50 chars:
+
+One rule for every topic and initiative `{slug}`: lowercase; each run of characters outside `a-z0-9` becomes one `-`; leading and trailing `-` are trimmed; at most 50 characters (trim again after the cut); `untitled` when nothing is left:
 ```bash
-TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50)
+TOPIC_SLUG=$(s=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c1-50 | sed -E 's/-+$//'); echo "${s:-untitled}")
 ```
+`/plan` and `/research` take `{topic-slug}` from it. `/dynamic-tickets` uses it for the initiative `{slug}`, and `/dynamic-plan` reuses the `{slug}` of the ticket set it plans (`wave` for any other source).
+
+### Exceptions
+
+- **`{ticket-slug}`** (`tickets/…/{ticket-slug}.md`, `design/…/{ticket-slug}-plan.md`): the ticket title lowercased with each run outside `a-z0-9` as one `-`, nothing trimmed and no length cap. `/dynamic-tickets` matches a ticket file by this name when it amends the ticket, so trimming would rename a file its own amend phase already wrote.
+- **Wave `{slug}`** (`waves/`, `evidence-wave-{slug}.md`): the part of the integration branch after `wave/`, at most 60 characters, not derived by the topic rule. It makes `evidence-wave-{slug}.md` the `evidence-{branch-slug}.md` of the branch `wave/{slug}`.
 
 ### File Naming Patterns
 
 | Type | Pattern | Example |
 |------|---------|---------|
 | Special indexes | `UPPERCASE.md` | `WORKING-MEMORY.md`, `INDEX.md` |
-| Review reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` |
-| Review summary | `review-summary.md` in timestamped dir | `2025-12-26_1430/review-summary.md` |
-| Resolution summary | `resolution-summary.md` in timestamped dir | `2025-12-26_1430/resolution-summary.md` |
-| Review head marker | `.last-review-head` | Plain text file with SHA |
+| Reports and summaries | `{focus}.md`, `review-summary.md`, `bug-analysis-summary.md`, `research-summary.md`, `static-findings.md`, `resolution-summary.md` in the run directory | `2025-12-26_1430/security.md` |
+| Head markers | `.last-review-head`, `.last-analysis-head` | Plain text file with SHA |
 | Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
 | Design documents | `{ISSUE_ID}-{topic-slug}.{timestamp}.md` | `42-jwt-auth.2026-04-07_1430.md` |
-| Research outputs | `{type}.md` in timestamped dir | `2025-12-26_1430/codebase.md` |
-| Research summary | `research-summary.md` in timestamped dir | `2025-12-26_1430/research-summary.md` |
-| Bug analysis reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` |
-| Bug analysis summary | `bug-analysis-summary.md` in timestamped dir | `2025-12-26_1430/bug-analysis-summary.md` |
-| Static findings | `static-findings.md` in timestamped dir | `2025-12-26_1430/static-findings.md` |
-| Analysis head marker | `.last-analysis-head` | Plain text file with SHA |
+| Design (several issues) | `multi-{topic-slug}.{timestamp}.md` | `multi-jwt-auth.2026-04-07_1430.md` |
+| Design (no issue) | `{topic-slug}.{timestamp}.md` | `jwt-auth.2026-04-07_1430.md` |
+| Per-ticket plan | `{ticket-slug}-plan.md` in `design/{slug}/{timestamp}/` | `design/wave/2026-04-07_1430/add-login-plan.md` |
+| Handoff, evidence | `handoff-{branch-slug}.md`, `evidence-{branch-slug}.md`, `evidence-wave-{slug}.md` | `evidence-feat-jwt-auth.md` |
 
 ---
 
@@ -121,8 +128,9 @@ Define these inline, in the Bash call that needs them, for consistent naming. `.
 
 ```bash
 get_timestamp() { date +%Y-%m-%d_%H%M; }
-get_branch_slug() { git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone"; }
-get_topic_slug() { echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50; }
+get_run_stamp() { local t; t=$(get_timestamp); [ -e "$1/$t" ] && t=$(date +%Y-%m-%d_%H%M%S); echo "$t"; }  # $1: parent of the run directory
+get_branch_slug() { local b; b=$(git branch --show-current 2>/dev/null); echo "${b:-standalone}" | sed 's/\//-/g'; }
+get_topic_slug() { local s; s=$(echo "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c1-50 | sed -E 's/-+$//'); echo "${s:-untitled}"; }
 get_docs_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
 ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
 ```
@@ -131,38 +139,29 @@ ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
 
 ## Agent Persistence Rules
 
-### Agents That Persist Artifacts
-
-| Agent | Output Location | Behavior |
-|-------|-----------------|----------|
-| Review agent | `.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir |
-| Synthesize agent (review) | `.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md` | Creates new in timestamped dir |
-| Resolve cmd | `.devflow/docs/reviews/{branch-slug}/{timestamp}/resolution-summary.md` | Written by /resolve orchestrator (Phase 5) |
-| Code-review cmd | `.devflow/docs/reviews/{branch-slug}/.last-review-head` | Overwrites with HEAD SHA |
-| Working Memory | `.devflow/memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
-| Decisions | `.devflow/learning/decisions.md` | Rendered from `decisions-ledger.jsonl` (active ADR-NNN entries in full; inactive ones listed in its Inactive table) |
-| Pitfalls | `.devflow/learning/pitfalls.md` | Rendered from `decisions-ledger.jsonl` (active PF-NNN entries in full; inactive ones listed in its Inactive table) |
-| Design agent (via /plan) | `.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{timestamp}.md` | Creates new design artifact |
-| Research agent | `.devflow/docs/research/{topic-slug}/{timestamp}/{type}.md` | Creates new in timestamped dir |
-| Synthesize agent (research) | `.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md` | Creates new in timestamped dir |
-| Diagnose agent | `.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir |
-| Synthesize agent (bug-analysis) | `.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/bug-analysis-summary.md` | Creates new in timestamped dir |
-| Bug-analysis cmd | `.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head` | Overwrites with HEAD SHA |
+### Who Writes What
+
+- **Reviews**: the Review agents and the Synthesize agent (review mode) write into `reviews/{branch-slug}/{timestamp}/`; `/resolve` adds `resolution-summary.md` (Phase 5); `/code-review` overwrites `.last-review-head` with the HEAD SHA.
+- **Bug analysis**: the Debug agents and the Synthesize agent (bug-analysis mode) write into `bug-analysis/{branch-slug}/{timestamp}/`; `/bug-analysis` overwrites `.last-analysis-head` with the HEAD SHA.
+- **Research**: the Research agents write `{type}.md`, and the Synthesize agent (research mode) writes `research-summary.md` through `RESEARCH_BASE_DIR`, both into `research/{topic-slug}/{timestamp}/`.
+- **Design**: `/plan` writes the design document; `/dynamic-plan` writes `design/{slug}/{timestamp}/`, `/dynamic-tickets` `tickets/{slug}/{timestamp}/`, `/dynamic-build` `waves/{slug}/{timestamp}/` and `evidence-wave-{slug}.md`.
+- **Handoff and evidence**: `/implement` writes `evidence-{branch-slug}.md`, which stays after the PR, and the handoff file, to which each Code agent appends one phase section and which is deleted once the PR exists.
+- **Memory and learning**: the Stop hook overwrites `.devflow/memory/WORKING-MEMORY.md`; `decisions.md` and `pitfalls.md` are rendered from `decisions-ledger.jsonl` (active entries in full, inactive ones in an Inactive table).
 
 ### Agents That Don't Persist
 
 - Git (fetch-issue: read-only, post-review-summary: consolidated review comment only)
-- Code agent (commits to git, no .devflow/docs/ output)
+- Code agent (commits to git; its only file is the handoff section it appends when `HANDOFF_FILE` is given)
 
 ---
 
 ## Implementation Checklist
 
-When creating or modifying persisting agents:
+When creating or modifying persisting agents or commands:
 
-- [ ] Use standard timestamp format (`YYYY-MM-DD_HHMM`)
-- [ ] Sanitize branch names (replace `/` with `-`)
-- [ ] Sanitize topic names (lowercase, dashes, alphanumeric)
+- [ ] Use the run-directory timestamp (`YYYY-MM-DD_HHMM`, local time, seconds on a same-minute collision)
+- [ ] Derive the branch slug (replace `/` with `-`) and gate it before it builds a path
+- [ ] Derive topic slugs with the one rule (lowercase, single dashes, at most 50)
 - [ ] Create directory with `mkdir -p .devflow/docs/{subdir}`
 - [ ] Document output location in agent's final message
 - [ ] Follow special file naming (UPPERCASE for indexes)
@@ -174,12 +173,10 @@ When creating or modifying persisting agents:
 ## Integration
 
 This framework is used by:
-- **Review agents**: Creates review reports
-- **Bug analysis agents**: Creates bug analysis reports
+- **`/plan` and `/research`**: load it at the step that names the document, and build the path by its rules
+- **Commands that hand paths to agents** (`/code-review`, `/bug-analysis`, `/implement`, `/resolve`, the `/dynamic-*` commands): follow it, with the exceptions above
 - **Working Memory hooks**: Auto-maintains `.devflow/memory/WORKING-MEMORY.md`
-- **Learning agent**: background LLM agent (spawned via the session-start directive) promotes observations to ADRs/PFs via `assign-anchor`, which renders `decisions.md` / `pitfalls.md`
-
-All persisting agents should load this skill to ensure consistent documentation.
+- **Curate agent**: background LLM agent (spawned via the session-start directive) promotes observations to ADRs/PFs via `assign-anchor`, which renders `decisions.md` / `pitfalls.md`
 
 ---
 

package/src/assets/skills/docs-framework/references/patterns.md

@@ -19,11 +19,8 @@ Correct patterns for Devflow documentation artifacts with templates and helper f
 │   └── {timestamp}/                # Incremental review
 │       └── ...
 ├── design/                         # Implementation plans
-│   └── {topic-slug}.{timestamp}.md
-├── status/                         # Development logs
-│   ├── {timestamp}.md
-│   ├── compact/{timestamp}.md
-│   └── INDEX.md
+│   ├── {ISSUE_ID}-{topic-slug}.{timestamp}.md   # /plan (multi-{topic-slug} / {topic-slug} without an issue)
+│   └── {slug}/{timestamp}/         # /dynamic-plan: {ticket-slug}-plan.md, DECISIONS-NEEDED.md
 └── CATCH_UP.md                     # Latest summary (overwritten)
 ```
 
@@ -32,8 +29,6 @@ Correct patterns for Devflow documentation artifacts with templates and helper f
 **Minimal (new project):**
 ```
 .devflow/docs/
-├── status/
-│   └── INDEX.md
 └── CATCH_UP.md
 ```
 
@@ -51,9 +46,6 @@ Correct patterns for Devflow documentation artifacts with templates and helper f
 │       ├── regression.md
 │       ├── tests.md
 │       └── review-summary.md
-├── status/
-│   ├── 2025-01-05_1430.md
-│   └── INDEX.md
 └── CATCH_UP.md
 ```
 
@@ -71,8 +63,6 @@ Correct patterns for Devflow documentation artifacts with templates and helper f
 │       ├── security.md
 │       ├── ...
 │       └── review-summary.md
-├── status/
-│   └── INDEX.md
 └── CATCH_UP.md
 ```
 
@@ -89,7 +79,7 @@ Format: `YYYY-MM-DD_HHMM` (sortable, readable)
 TIMESTAMP=$(date +%Y-%m-%d_%H%M)
 # Output: 2025-01-05_1430
 
-# With seconds (only if needed for uniqueness)
+# With seconds (a run directory that already exists: a second run in the same minute)
 TIMESTAMP_SEC=$(date +%Y-%m-%d_%H%M%S)
 # Output: 2025-01-05_143025
 ```
@@ -99,7 +89,7 @@ TIMESTAMP_SEC=$(date +%Y-%m-%d_%H%M%S)
 Replace `/` with `-`, provide fallback for detached HEAD.
 
 ```bash
-BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
+BRANCH_SLUG=$(b=$(git branch --show-current 2>/dev/null); echo "${b:-standalone}" | sed 's/\//-/g')
 
 # Examples:
 # feature/auth          -> feature-auth
@@ -111,15 +101,15 @@ BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "st
 
 ### Topic Slugs
 
-Lowercase, dashes, alphanumeric only, max 50 chars.
+Lowercase, each run of characters outside `a-z0-9` becomes one dash, no leading or trailing dash, max 50 chars, `untitled` when nothing is left.
 
 ```bash
-TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50)
+TOPIC_SLUG=$(s=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | cut -c1-50 | sed -E 's/-+$//'); echo "${s:-untitled}")
 
 # Examples:
 # "JWT Authentication"       -> jwt-authentication
 # "Fix User Login Bug"       -> fix-user-login-bug
-# "OAuth 2.0 Integration"    -> oauth-20-integration
+# "OAuth 2.0 Integration"    -> oauth-2-0-integration
 # "Database Migration v2"    -> database-migration-v2
 ```
 
@@ -171,12 +161,11 @@ get_branch_slug() {
 
 # Convert topic to slug format
 get_topic_slug() {
-    local topic="$1"
-    echo "$topic" | \
-        tr '[:upper:]' '[:lower:]' | \
-        tr ' ' '-' | \
-        sed 's/[^a-z0-9-]//g' | \
-        cut -c1-50
+    local slug
+    slug=$(echo "$1" | tr '[:upper:]' '[:lower:]' | \
+        sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' | \
+        cut -c1-50 | sed -E 's/-+$//')
+    echo "${slug:-untitled}"
 }
 
 # The checkout's toplevel, else the working directory outside git
@@ -351,11 +340,11 @@ get_branch_slug  # Returns: standalone
 
 ### Special Characters in Topics
 
-All special characters stripped:
+Every run of special characters becomes one dash:
 
 ```bash
 get_topic_slug "Bug: User can't login (v2.0)"
-# Returns: bug-user-cant-login-v20
+# Returns: bug-user-can-t-login-v2-0
 ```
 
 ### Long Topic Names

package/src/assets/skills/docs-framework/references/violations.md

@@ -13,9 +13,9 @@ Common violations of documentation conventions with detection patterns and fixes
 | Unsanitized branch slug | `feature/auth` | `feature-auth` | Replace `/` with `-` |
 | Wrong case for artifacts | `Status-2025-01-05.md` | `2025-01-05_1430.md` | Use lowercase except special indexes |
 | Wrong case for indexes | `index.md` | `INDEX.md` | UPPERCASE for special indexes |
-| Files outside .docs | `docs/status.md` | `.devflow/docs/status/2025-01-05_1430.md` | Use `.devflow/docs/` root |
+| Files outside .docs | `docs/status.md` | `.devflow/docs/reviews/feat-auth/2025-01-05_1430/review-summary.md` | Use `.devflow/docs/` root |
 | Missing INDEX.md | Status files without index | Create `INDEX.md` | Every directory needs index |
-| Special chars in slug | `oauth-2.0-auth` | `oauth-20-auth` | Strip non-alphanumeric except `-` |
+| Special chars in slug | `oauth-2.0-auth` | `oauth-2-0-auth` | Replace each non-alphanumeric run with one `-` |
 
 ---
 
@@ -34,7 +34,7 @@ project/
 
 ```
 .devflow/docs/
-├── logs/                   # Should be status/
+├── logs/                   # Should be reviews/{branch-slug}/
 ├── reports/                # Should be reviews/{branch-slug}/
 └── notes.md                # Should be in appropriate subdir
 ```
@@ -90,8 +90,8 @@ BRANCH_SLUG=$(git branch --show-current | sed 's/\//-/g')
 BRANCH_SLUG=$(git branch --show-current)
 # Result: empty string -> broken path
 
-# RIGHT - with fallback
-BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
+# RIGHT - with fallback (the fallback goes before the sed: a pipeline's status is sed's)
+BRANCH_SLUG=$(b=$(git branch --show-current 2>/dev/null); echo "${b:-standalone}" | sed 's/\//-/g')
 # Result: (detached HEAD) -> standalone
 ```
 
@@ -106,8 +106,8 @@ BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "st
 TOPIC="Bug: Can't login (v2.0)"
 SLUG="Bug:-Can't-login-(v2.0)"
 
-# RIGHT - stripped and normalized
-SLUG="bug-cant-login-v20"
+# RIGHT - special runs normalized to one dash
+SLUG="bug-can-t-login-v2-0"
 ```
 
 ### Not Truncating Long Names

package/src/assets/skills/gap-analysis/SKILL.md

@@ -103,22 +103,6 @@ Detect ordering constraints and shared resource conflicts across issues.
 
 **Evidence trigger:** Any issue that references state, contracts, or resources that may be in flux due to another issue in the batch.
 
-### 7. Compliance (when the compliance lens is on)
-
-Detect regulatory gaps that security doesn't cover. Load `devflow:compliance` before analyzing, then `references/{id}.md` only for the ids in `COMPLIANCE_FRAMEWORKS` (`none`: generic controls only).
-
-**Detection patterns:**
-- Missing audit trails on regulated mutations — writes to financial records, PHI, PCI-scoped data without durable logging
-- PII flows without retention/erasure specification — data collected but deletion/expiry policy absent
-- Missing encryption requirements — regulated data at rest or in transit without specified encryption control
-- Sensitive data in observability — PII or credentials leaking into logs, traces, or metrics
-- IaC exposure — infrastructure definitions without required security controls (open ports, unencrypted storage, missing IAM boundaries)
-- Self-approval flows — change requires segregation of duties (SOX/SOC 2 CC8.1) but single-actor path exists in the design
-
-**Explicit scope note:** Do NOT duplicate §3 Security's checks (secrets, injection, authZ). Compliance focus is on regulatory control requirements — retention periods, erasure rights, audit completeness, and segregation of duties — not general application security.
-
-**Evidence trigger:** Any regulated-data flow or infrastructure element in the design that does not specify a required control (retention policy, encryption spec, audit log destination, approval workflow).
-
 ---
 
 ## Extended References

package/src/assets/skills/gap-analysis/references/compliance.md

@@ -0,0 +1,19 @@
+# Gap Analysis: Compliance Focus
+
+The compliance focus's detection patterns. D-COMPLIANCE-INJECT: the `Design` agent's preload does not carry them. The `/plan` compliance-focus spawn names this file and the agent Reads it by path, so a lens-off run never loads it.
+
+## Compliance (when the compliance lens is on)
+
+Detect regulatory gaps that security doesn't cover. Load `devflow:compliance` before analyzing, then the compliance skill's `references/{id}.md` only for the ids the spawn's compliance directive names (`none`: generic controls only).
+
+**Detection patterns:**
+- Missing audit trails on regulated mutations — writes to financial records, PHI, PCI-scoped data without durable logging
+- PII flows without retention/erasure specification — data collected but deletion/expiry policy absent
+- Missing encryption requirements — regulated data at rest or in transit without specified encryption control
+- Sensitive data in observability — PII or credentials leaking into logs, traces, or metrics
+- IaC exposure — infrastructure definitions without required security controls (open ports, unencrypted storage, missing IAM boundaries)
+- Self-approval flows — change requires segregation of duties (SOX/SOC 2 CC8.1) but single-actor path exists in the design
+
+**Explicit scope note:** Do NOT duplicate §3 Security's checks (secrets, injection, authZ). Compliance focus is on regulatory control requirements — retention periods, erasure rights, audit completeness, and segregation of duties — not general application security.
+
+**Evidence trigger:** Any regulated-data flow or infrastructure element in the design that does not specify a required control (retention policy, encryption spec, audit log destination, approval workflow).

package/src/assets/skills/qa/SKILL.md

@@ -109,7 +109,7 @@ When implementation includes web-facing changes (.tsx, .jsx, .html, routes, page
 
 | Level | Meaning | Action |
 |-------|---------|--------|
-| **BLOCKING** | Acceptance criterion violated — feature does not work as requested | Report FAIL — Code agent must fix |
+| **BLOCKING** | Acceptance criterion violated — feature does not work as requested | Report FAIL — Fix agent must fix |
 | **WARNING** | Edge case concern — feature works but edge behavior is unexpected | Report PASS with warnings — note for improvement |
 
 ---

package/src/assets/skills/quality-gates/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Read, Grep, Glob, Edit, Write, Bash
 
 # Self-Review Framework
 
-Systematic self-review for the Scrutinize agent. Evaluate implementation against 9 pillars. **Fix issues, don't just report them.**
+Systematic self-review for the Harden agent. Evaluate implementation against 9 pillars. **Fix issues, don't just report them.**
 
 Based on [Google Engineering Practices](https://google.github.io/eng-practices/review/reviewer/looking-for.html).
 
@@ -26,7 +26,7 @@ Based on [Google Engineering Practices](https://google.github.io/eng-practices/r
 |----------|--------|---------|
 | **P0** | MUST fix | Design, Functionality, Security |
 | **P1** | SHOULD fix | Complexity, Error Handling, Tests |
-| **P2** | FIX if straightforward | Documentation (Naming and Consistency belong to the Simplify agent: report them as SKIP) |
+| **P2** | FIX if straightforward | Documentation (Naming and Consistency belong to the Polish agent: report them as SKIP) |
 
 ### P0 - Design
 Does the implementation fit the architecture? Follows existing patterns, respects layer boundaries, dependencies injected.
@@ -49,7 +49,7 @@ Errors handled explicitly? No swallowed exceptions, helpful messages, resources
 New code tested? Covers happy path, errors, edges. Tests behavior, not implementation.
 
 ### P2 - Naming and Consistency
-Owned by the Simplify agent, which applies the project's naming and style standards. Report both as SKIP; do not judge or fix them here.
+Owned by the Polish agent, which applies the project's naming and style standards. Report both as SKIP; do not judge or fix them here.
 
 ### P2 - Documentation
 Will others understand? Complex logic commented, public APIs documented, no outdated comments.
@@ -96,7 +96,7 @@ Check Design, Functionality, Security. If issues found and fixable, fix immediat
 Check Complexity, Error Handling, Tests. Fix issues found.
 
 ### Step 4: Evaluate P2 Pillars
-Check Documentation and fix it if straightforward. Naming and Consistency are the Simplify agent's: SKIP.
+Check Documentation and fix it if straightforward. Naming and Consistency are the Polish agent's: SKIP.
 
 ### Step 5: Generate Report
 Document status of each pillar, fixes applied, and overall readiness.
@@ -119,8 +119,8 @@ Document status of each pillar, fixes applied, and overall readiness.
 - Tests: PASS/FIXED
 
 ### P2 Pillars
-- Naming: SKIP (Simplify agent)
-- Consistency: SKIP (Simplify agent)
+- Naming: SKIP (Polish agent)
+- Consistency: SKIP (Polish agent)
 - Documentation: PASS/FIXED
 
 ### Summary
@@ -144,6 +144,6 @@ For complete report templates and examples:
 ## Integration
 
 Used by:
-- **Scrutinize agent**: Dedicated self-review in fresh context after the Code agent completes
+- **Harden agent**: Dedicated self-review in fresh context after the Code agent completes
 
 The self-review ensures implementations meet quality standards before external review, catching issues early.

package/src/assets/skills/quality-gates/references/report-template.md

@@ -48,8 +48,8 @@ Use this template when generating your self-review report.
 
 | Pillar | Status | Notes |
 |--------|--------|-------|
-| Naming | SKIP | Simplify agent |
-| Consistency | SKIP | Simplify agent |
+| Naming | SKIP | Polish agent |
+| Consistency | SKIP | Polish agent |
 | Documentation | PASS/FIXED | {details if fixed} |
 
 **Fixes Applied** (if any):
@@ -109,8 +109,8 @@ Add user profile update endpoint
 
 | Pillar | Status | Notes |
 |--------|--------|-------|
-| Naming | SKIP | Simplify agent |
-| Consistency | SKIP | Simplify agent |
+| Naming | SKIP | Polish agent |
+| Consistency | SKIP | Polish agent |
 | Documentation | PASS | JSDoc on public methods |
 
 ---
@@ -169,8 +169,8 @@ Implement order cancellation flow
 
 | Pillar | Status | Notes |
 |--------|--------|-------|
-| Naming | SKIP | Simplify agent |
-| Consistency | SKIP | Simplify agent |
+| Naming | SKIP | Polish agent |
+| Consistency | SKIP | Polish agent |
 | Documentation | FIXED | Added JSDoc explaining cancellation rules |
 
 **Fixes Applied**:
@@ -237,7 +237,7 @@ before implementing refund feature.
 |--------|--------|------------------------|
 | PASS | No issues found for this pillar | No change was needed |
 | FIXED | Issue found and resolved | Fixes were committed and every P0 and P1 is fixed |
-| SKIP | Naming and Consistency only - owned by the Simplify agent | - |
+| SKIP | Naming and Consistency only - owned by the Polish agent | - |
 | BLOCKED | Cannot fix - requires escalation | A P0 cannot be fixed in scope |
 
 ---

package/dist/skills/git/references/pr/ensure-pr-ready.md

@@ -1,24 +0,0 @@
-## Operation: ensure-pr-ready
-
-Load for `ensure-pr-ready` under every tracker provider.
-
-**PR mechanics held here:** every step but step 4b's tracker half, which is the provider reference's.
-
-### Process
-
-1. Verify on feature branch (not main/master/develop/integration/trunk/release/*/staging/production) - error if not
-2. Check for uncommitted changes - if any, create atomic commit using `devflow:git` patterns
-3. Check if branch pushed to remote - if not, push with `-u` flag. If that push is refused and the branch's open PR is cross-repository with maintainer edits off (`gh pr view --json isCrossRepository,maintainerCanModify`), emit `TRACEABILITY: DEGRADED (cannot push to fork)` and go to 4a (4a–4c edit only the PR).
-4a. Check if PR exists - if not, create PR using guidance from (in priority order): (a) `PR_DESCRIPTION_GUIDANCE` if given and not `(none)`, (b) generated from branch context. Compose the PR body via the `devflow:git` template to `$DEVFLOW_BODY_RAW` (a D11 sink: it publishes at repo visibility), then append the caller blocks. Apply the Comment-sink scrub (D11) — a failed one posts neither block; on success: `gh pr create … --body-file "$DEVFLOW_BODY"`.
-   - **Caller blocks**, in order: `PR_WAVE_BLOCK` (`check wave`), then `PR_TEST_PLAN_BLOCK` (`check block`), each when given and not `(none)`. Write it byte for byte to a fresh `mktemp` file with the Write tool, never via a shell string, and run `node "$HOME/.devflow/scripts/verify-evidence.cjs" check <wave|block> <file>; echo "exit=$?"`. Only `exit=0` admits it, verbatim; else omit it, never repaired or partly pasted, and emit `TRACEABILITY: DEGRADED (wave block does not match its grammar)` or `TRACEABILITY: DEGRADED (test-plan block does not match its grammar)` with steps 4b/4c's lines. An admitted wave block is the body's only `## Related Issues`: skip 4b.
-4c. Retitle, only when `APPLY_CONVENTIONS` is `true`: if the PR title breaks the convention in the PR Titles section of `.devflow/conventions.md`, retitle it; skip silently when that file is absent. Two rules, because the title derives from third-party PR titles:
-   - **Validate before use.** Skip the retitle (leave the PR title as-is, no error) if the composed title contains any of `` $ ` \ " ' ; | & < > `` or a newline.
-   - **Pass as argv, never as command text.** Bind it to a shell variable and pass that variable: `gh pr edit {PR_NUMBER} --title "$DEVFLOW_PR_TITLE"`. Never interpolate it: `$(...)`, backticks and `${...}` all expand inside double quotes.
-
-   On any 4xx/5xx from `gh pr edit`: emit `TRACEABILITY: DEGRADED ({reason})` and continue — a failed retitle never blocks the PR.
-5. Get base branch from PR
-6. Derive branch-slug (replace `/` with `-`)
-
-### Step 4b's PR-host half
-
-The provider reference's step 4b publishes its section only through this: find the open PR with `gh pr list --head {branch} --state open --limit 1`; compose the existing body plus the `## Related Issues` section to `$DEVFLOW_BODY_RAW` — the existing body is third-party-editable, so never interpolate it into a command string; apply the Comment-sink scrub (D11); on success: `gh pr edit {PR_NUMBER} --body-file "$DEVFLOW_BODY"`.