devflow-kit 3.3.0 → 3.5.0

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/feature-knowledge/SKILL.md

@@ -102,16 +102,20 @@ updated: {ISO date}
 
 # {Feature Area Name}
 
+## Rules
+- **KB-AP-1** [one-line anti-pattern or gotcha: what to avoid, and the consequence]
+- **KB-INV-1** [one-line invariant that must hold]
+
 ## Overview
 [1-2 paragraphs: what this knowledge covers and why it matters for this codebase]
 
 ## [Main Sections — vary by category, see Category Templates below]
 
 ## Anti-Patterns
-[What to avoid and why — with explanation of consequences]
+[The longer explanation of each anti-pattern, headed by its ID — never a restatement of the Rules bullet]
 
 ## Gotchas
-[Non-obvious behaviors, edge cases, things that break silently]
+[Non-obvious behaviors, edge cases, things that break silently — headed by the ID of the Rules bullet each explains]
 
 ## Key Files
 [Most important files with one-line descriptions]
@@ -120,6 +124,23 @@ updated: {ISO date}
 [Links to other feature knowledge entries and key source files — never an ADR/PF ID]
 ```
 
+### Rules Section
+
+`## Rules` comes first, after the title: the anti-patterns, gotchas and invariants of the feature area as one-line bullets, in about 3–5K characters. A bullet fits one line and never starts with `## `.
+
+- **IDs**: anti-pattern and gotcha bullets take `KB-AP-n`; invariant bullets take `KB-INV-n`. Numbers are unique within a KB. A bullet keeps its ID across rewrites; a removed bullet's ID is retired and never reused. A citation names the slug and the ID together, as `{slug} KB-AP-n`; a bare ID is never cited.
+- **Explanations**: `## Anti-Patterns` and `## Gotchas` stay below Rules as the longer explanations, each headed by the IDs it explains.
+- **No volatile numbers**: a volatile number is a count, size, line number, version or threshold that changes when the code changes. Where a value matters, name the test or constant that pins it. Bullet IDs are not volatile numbers.
+- **Legacy KBs**: a KB without `## Rules` is valid until curated. Readers take one to three entries from its Anti-Patterns or Gotchas, cited by section name, with the KB path and heading index.
+
+### Size Budget
+
+Per KB: target 30,000 characters, ceiling 40,000. An index line is at most 300 characters and a description at most 220, so slug, areas and description fit one line. **Curate, never truncate**: reword or consolidate, and nothing is cut or dropped to meet the budget. Split into focused sub-knowledge bases (each with its own index entry) only when curation cannot bring a KB under the ceiling.
+
+### Refreshing an Existing KB
+
+When `EXISTING_KB` is provided, change only the sections the new work touches, and add or update Rules bullets for what changed. Never renumber, and never rewrite untouched sections to meet the budget. A KB still above the ceiling after a refresh is written as it stands, and the final message says so.
+
 ### Category Templates
 
 Use the matching template as your main sections. Anti-Patterns, Gotchas, Key Files, and Related are shared across all categories.
@@ -159,6 +180,7 @@ The `description` field is how this feature knowledge entry gets discovered. It
 - Start with "Use when"
 - Name specific scenarios where this knowledge applies
 - Include keywords a developer would search for
+- Stay within 220 characters
 
 Good: `"Use when adding a new vendor integration, implementing API clients, or connecting to external services. Keywords: integration, vendor, API client, webhook."`
 Bad: `"Integration stuff"`
@@ -205,7 +227,7 @@ Never include bare code snippets without context.
 | No code examples at all | Insufficient actionable guidance |
 | Examples without inline comments | Missing required context |
 | "In the future, we might..." | Speculative — remove it |
-| 500+ lines in a single file | Should be split into focused files |
+| Over 40,000 characters, or volatile numbers in Rules | Curate it; name the pinning test or constant instead of a count |
 | No cross-references in Related | Isolated knowledge island |
 
 ---
@@ -228,7 +250,8 @@ Run through this before writing. If any check fails, go back and fix it.
 **Structure:**
 - [ ] Category is correct and main sections follow the matching template
 - [ ] Description field starts with "Use when" and includes keywords
-- [ ] File stays under 500 lines (split if necessary)
+- [ ] `## Rules` comes first: one-line bullets with `KB-AP-n` / `KB-INV-n` IDs, about 3–5K characters, no volatile numbers
+- [ ] File within the 40,000-character ceiling (curate, never truncate); description at most 220 characters
 
 **Connections:**
 - [ ] Cross-references to related feature knowledge entries in Related section; decisions and pitfalls stated in words, with no ADR/PF ID anywhere in the file
@@ -249,10 +272,10 @@ After writing KNOWLEDGE.md, update the index cache directly:
 - **{slug}** — {areas} — {Use-when description}
 ```
 
-Where:
+The whole line is at most 300 characters; reword a longer one, never cut it. Where:
 - `{slug}` matches the `feature:` frontmatter field
 - `{areas}` is a comma-separated summary of the `directories:` frontmatter field
-- `{Use-when description}` is the `description:` frontmatter field value (the full "Use when..." sentence)
+- `{Use-when description}` is the `description:` frontmatter field value (the full "Use when..." sentence, at most 220 characters)
 
 If `index.md` does not exist, create it with just this line. If the file already has an entry for this slug, replace that line in-place. This is the discoverable cache read by `knowledge_load()` — the KNOWLEDGE.md frontmatter is always authoritative.
 
@@ -275,9 +298,17 @@ updated: 2026-04-30
 
 # Third-Party Integrations
 
+## Rules
+
+- **KB-AP-1** Fetch logic never lives in a command file: it breaks the lib/command split and cannot be tested alone.
+- **KB-AP-2** URLs never live in lib modules: they go through `config.ts`.
+- **KB-AP-3** A lib module never calls `showError()`: lib modules throw, commands catch and display.
+- **KB-AP-4** `spawn` needs the binary on PATH: detect `ENOENT` and give an install URL.
+- **KB-INV-1** Every external constant lives in `src/lib/config.ts`.
+
 ## Overview
 
-This project integrates with external systems in three ways: spawning CLI processes, fetching files from remote registries, and writing to directories that AI editors watch. Each integration lives in its own module under `src/lib/` and is wired into a command in `src/commands/`. All external constants are centralized in `src/lib/config.ts`.
+This project integrates with external systems by spawning CLI processes, fetching files from remote registries, and writing to directories that AI editors watch. Each integration lives in its own module under `src/lib/` and is wired into a command in `src/commands/`. All external constants are centralized in `src/lib/config.ts`.
 
 The key cross-cutting pattern is the separation between lib modules (which integrate) and commands (which orchestrate). Violating this creates coupling that breaks the error handling model.
 
@@ -289,7 +320,7 @@ The key cross-cutting pattern is the separation between lib modules (which integ
 
 ## Standard Structure
 
-Every integration follows the same file organization. This example shows the pattern that all three existing integrations (Claude CLI, GitHub, AI editors) follow:
+Every integration follows the same file organization. This example shows the pattern that every existing integration (Claude CLI, GitHub, AI editors) follows:
 
 ```
 src/lib/
@@ -309,13 +340,13 @@ All constants use `SCREAMING_SNAKE_CASE` with a descriptive prefix. If a value c
 
 ## Anti-Patterns
 
-- **Putting fetch logic in a command file** — breaks the lib/command separation and makes the integration untestable in isolation.
-- **Hardcoding URLs in lib modules** — always use `config.ts`. Scattered strings become stale and hard to find.
-- **Calling `showError()` from a lib module** — lib modules throw; commands catch and display.
+- **KB-AP-1, putting fetch logic in a command file** — breaks the lib/command separation and makes the integration untestable in isolation.
+- **KB-AP-2, hardcoding URLs in lib modules** — always use `config.ts`. Scattered strings become stale and hard to find.
+- **KB-AP-3, calling `showError()` from a lib module** — lib modules throw; commands catch and display.
 
 ## Gotchas
 
-- `spawn` requires the binary on PATH. If integrating a tool that may not be globally installed, detect `ENOENT` and provide an install URL.
+- **KB-AP-4**: `spawn` requires the binary on PATH. If integrating a tool that may not be globally installed, detect `ENOENT` and provide an install URL.
 - Temp files use `Date.now()`. If two processes run simultaneously, add a random suffix to avoid collisions.
 
 ## Key Files

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/quality-gates/SKILL.md

@@ -31,7 +31,7 @@ Based on [Google Engineering Practices](https://google.github.io/eng-practices/r
 ### P0 - Design
 Does the implementation fit the architecture? Follows existing patterns, respects layer boundaries, dependencies injected.
 
-If `FEATURE_KNOWLEDGE` is provided, verify implementation respects the feature area's documented architecture and anti-patterns. Flag deviations as P0-Design issues when the documented pattern is clearly intentional.
+If `FEATURE_KNOWLEDGE` is provided (Rules bullets and the KB path, no heading index), verify implementation respects each bullet's anti-pattern, gotcha or invariant; Read a KB section from its path for the architecture. Flag deviations as P0-Design issues when the documented pattern is clearly intentional.
 
 ### P0 - Functionality
 Does the code work? Happy path, edge cases (null, empty, boundary), no race conditions.

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"`.