devflow-kit 2.4.0 → 3.0.0

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

@@ -28,6 +28,8 @@ ${DEVFLOW_COMPLIANCE_ACTIVE}
 
 Compliance covers regulatory-specific gaps: retention, erasure/data-subject rights, audit-trail completeness (actor/purpose fields), segregation of duties, framework mapping, IaC exposure. Do NOT re-raise security lens findings (injection, secret handling, authN/Z) — reference those via framework mapping only.
 
+**Lens only.** This skill shapes what a compliance review looks for in the diff or design. It does not decide how much evidence a change must carry: tracker links, test plans, approvals and release traces follow the repository's evidence policy. Never report a missing ticket, test plan or approval as a compliance finding.
+
 ## Clean-Report Contract
 
 If the diff/design has no regulated-data surface (no PII/PHI/payment fields, no sensitive data in logs, no IaC, no auth/audit/retention changes) → emit zero findings with a one-line "no compliance-relevant surface detected" note. Never manufacture findings.
@@ -97,13 +99,13 @@ resource "aws_s3_bucket_logging" "data" { target_bucket = var.audit_bucket_id }
 | **CRITICAL** | Plaintext regulated data exposed; public IaC exposure of regulated stores |
 | **HIGH** | Missing audit trail on regulated mutations; PII in logs or errors |
 | **MEDIUM** | Missing retention/erasure paths; weak traceability (no actor/purpose) |
-| **LOW** | No active framework reference files installed; documentation/annotation gaps |
+| **LOW** | Documentation/annotation gaps |
 
 ${DEVFLOW_COMPLIANCE_MAPPING}
 
 ## Checklist
 
-- [ ] Active frameworks identified from installed `references/{id}.md` files; controls applied
+- [ ] Frameworks in force are the ids given (`COMPLIANCE_FRAMEWORKS`); their controls applied
 - [ ] No PII/PHI/payment data in logs, errors, or analytics events
 - [ ] Regulated data encrypted in transit (TLS 1.2+) and at rest
 - [ ] Every regulated mutation has an append-only audit entry (actor, purpose, timestamp)

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

@@ -42,7 +42,7 @@ All generated documentation lives under `.devflow/docs/` in the project root:
 │       ├── bug-analysis-summary.md    # Synthesize agent output
 │       └── resolution-summary.md      # Written by /resolve (if run)
 ├── design/                             # Design artifacts from /plan
-│   └── {issue}-{topic-slug}.{timestamp}.md  # Design document
+│   └── {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
@@ -71,6 +71,8 @@ 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`.
+
 ---
 
 ## Naming Conventions
@@ -103,7 +105,7 @@ TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^
 | 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 |
 | Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
-| Design documents | `{issue}-{topic-slug}.{timestamp}.md` | `42-jwt-auth.2026-04-07_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` |
@@ -115,15 +117,14 @@ TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^
 
 ## Helper Functions
 
-Source helpers for consistent naming:
+Define these inline, in the Bash call that needs them, for consistent naming. `.devflow/docs/` lives at the checkout's toplevel, never under a subdirectory the session started in:
 
 ```bash
-source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
-    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; }
-    ensure_docs_dir() { mkdir -p ".devflow/docs/$1"; }
-}
+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_docs_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
+ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
 ```
 
 ---
@@ -141,7 +142,7 @@ source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
 | 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 rows; retired rows dropped) |
 | Pitfalls | `.devflow/learning/pitfalls.md` | Rendered from `decisions-ledger.jsonl` (active PF-NNN rows; retired rows dropped) |
-| Design agent (via /plan) | `.devflow/docs/design/{issue}-{topic-slug}.{timestamp}.md` | Creates new design artifact |
+| 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 |

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

@@ -150,12 +150,9 @@ Always lowercase:
 
 ## Helper Functions
 
-Full implementation for `.devflow/scripts/docs-helpers.sh`:
+Full implementations, defined inline in the Bash call that needs them. `.devflow/docs/` lives at the checkout's toplevel, never under a subdirectory the session started in:
 
 ```bash
-#!/bin/bash
-# .devflow/scripts/docs-helpers.sh
-
 # Get current timestamp in standard format
 get_timestamp() {
     date +%Y-%m-%d_%H%M
@@ -182,10 +179,15 @@ get_topic_slug() {
         cut -c1-50
 }
 
+# The checkout's toplevel, else the working directory outside git
+get_docs_root() {
+    git rev-parse --show-toplevel 2>/dev/null || pwd
+}
+
 # Ensure docs directory exists
 ensure_docs_dir() {
     local subdir="$1"
-    mkdir -p ".devflow/docs/$subdir"
+    mkdir -p "$(get_docs_root)/.devflow/docs/$subdir"
 }
 
 # Get full output path for a document
@@ -193,7 +195,7 @@ get_doc_path() {
     local subdir="$1"
     local filename="$2"
     ensure_docs_dir "$subdir"
-    echo ".devflow/docs/$subdir/$filename"
+    echo "$(get_docs_root)/.devflow/docs/$subdir/$filename"
 }
 
 # Create timestamped status log path
@@ -211,23 +213,14 @@ get_review_path() {
     branch_slug=$(get_branch_slug)
     timestamp=$(get_timestamp)
     ensure_docs_dir "reviews/$branch_slug/$timestamp"
-    echo ".devflow/docs/reviews/$branch_slug/$timestamp/${focus}.md"
+    echo "$(get_docs_root)/.devflow/docs/reviews/$branch_slug/$timestamp/${focus}.md"
 }
 ```
 
 ### Usage Example
 
 ```bash
-# Source helpers
-source .devflow/scripts/docs-helpers.sh 2>/dev/null || {
-    # Inline fallback if script not found
-    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; }
-    ensure_docs_dir() { mkdir -p ".devflow/docs/$1"; }
-}
-
-# Use helpers
+# Define the helpers above in the same Bash call, then use them
 TIMESTAMP=$(get_timestamp)
 BRANCH_SLUG=$(get_branch_slug)
 ensure_docs_dir "reviews/$BRANCH_SLUG"

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

@@ -103,9 +103,9 @@ 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 compliance skill installed)
+### 7. Compliance (when the compliance lens is on)
 
-Detect regulatory gaps that security doesn't cover. Active frameworks = the `references/{id}.md` files present in the installed skill. Load `devflow:compliance` before analyzing.
+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

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

@@ -21,11 +21,7 @@ Unified skill for safe git operations, atomic commits, honest PR descriptions, a
 
 ## When This Skill Activates
 
-- Staging files, creating commits, pushing branches
-- Creating or updating pull requests
-- Rebasing, force-pushing, merge conflicts, undoing commits
-- GitHub API operations (PR comments, issues, releases)
-- Any `git` or `gh` CLI command
+Any `git` or `gh` operation: staging, commits, branches, pull requests, rebases, issues, releases.
 
 ---
 
@@ -70,7 +66,7 @@ Only use `--amend` when ALL conditions are met:
 
 ### Branch Safety
 
-Never force push to: `main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production`
+Never force push to a protected branch — `devflow:worktree-support` holds the canonical list.
 
 **Branch naming**: `feat/`, `fix/`, `release/`, `hotfix/` prefixes with short descriptions.
 
@@ -114,6 +110,8 @@ See `references/patterns.md` for extended recovery and stash workflows.
 
 ### HEREDOC Format (Required)
 
+Compose the issue/PR reference line BEFORE the heredoc. The heredoc delimiter is single-quoted; unquoting it makes every interpolated value a command.
+
 ```bash
 git commit -m "$(cat <<'EOF'
 feat(auth): add JWT token validation
@@ -149,7 +147,7 @@ EOF
 | Changes | Features, fixes, refactoring by category |
 | Breaking Changes | User action required (or "None") |
 | Testing | Coverage, manual steps, gaps |
-| Related Issues | Closes/relates to links |
+| Related Issues | `Closes {ISSUE_REF}` / relates-to links |
 
 ### Size Assessment
 
@@ -187,78 +185,9 @@ See `references/detection.md` for full `check_for_secrets()` function.
 
 ## GitHub API
 
-> **RESPECT RATE LIMITS OR FAIL GRACEFULLY** — remaining < 10 wait 60s, 1-2s between calls, batch where possible.
-
-### Standard Throttling
-
-```bash
-REMAINING=$(gh api rate_limit --jq '.resources.core.remaining')
-if [ "$REMAINING" -lt 10 ]; then sleep 60; fi
-sleep 1  # Between each API call
-```
-
-### PR Comments
-
-- Only lines in the PR diff can receive inline comments
-- Deduplicate before posting (same file + line = keep one)
-- Always include a suggested fix; every comment carries the `<!-- devflow:* -->` marker, and the visible devflow footer (*Posted by [devflow](https://github.com/dean0x/devflow)*) is appended only on summary comments (see src/assets/agents/git.md)
-
-### Releases
-
-```bash
-[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || exit 1  # Validate semver
-git tag -a "v${VERSION}" -m "Version ${VERSION}" && git push origin "v${VERSION}"
-gh release create "v${VERSION}" --title "v${VERSION}" --notes "$NOTES"
-```
-
-See `references/github-api.md` for extended API, CLI, and GraphQL patterns.
-
----
-
-## Anti-Patterns
-
-| Violation | Impact | Fix |
-|-----------|--------|-----|
-| Parallel git commands | Index corruption | Sequential `&&` chains |
-| Grab-bag commits | Impossible to revert | One logical change per commit |
-| Blind staging (`git add .`) | Accidental secret commits | Stage specific files |
-| Force push to main | Destroys shared history | Create new commits |
-| Ignoring rate limits | API lockout | Check remaining, throttle |
-| Vague PR descriptions | Lost review context | Use structured template |
-| Hidden breaking changes | Consumer surprises | Mandatory section |
-
----
-
-## Traceability Issue Template (D3)
-
-When creating or enriching a GitHub issue via the `ensure-traceable-issue` operation, use the following canonical D3 template:
-
-```markdown
-## Initial Request
-{The verbatim or paraphrased user request / scope statement that drove this task}
-
-## Product Requirements
-{Discovered requirements summary — user needs, acceptance criteria, constraints}
-
-## Implementation Plan
-[Design artifact posted as a collapsed comment — see linked comment below]
-```
-
-**Rules:**
-- Pre-existing issues: post a structured comment using D3 sections — NEVER rewrite the issue body.
-- New issues: create with D3 body; then post the design artifact as a `<details>` collapsed comment; link that comment URL in the `## Implementation Plan` section.
-- Issue creation is gated by the `COMPLIANCE` input: `enabled` → mandatory (DEGRADED states exempt), absent or `(none)` → optional.
-
-## Naming Conventions Authority
-
-When `.devflow/conventions.md` is present, it is the authoritative source for:
-- Branch Naming — prefix style (`feat/`, `fix/`, etc.), separator style, slug rules
-- PR Titles — conventional commit format, scope rules
-- Version PR Titles and Version Names (when applicable)
-
-The `learn-conventions` operation writes `.devflow/conventions.md` with a bounded scan (≤50 branches, ≤20 tags, ≤30 PR titles). To re-learn conventions from scratch, delete `.devflow/conventions.md` and re-run `learn-conventions`.
+> **RESPECT RATE LIMITS OR FAIL GRACEFULLY** — at `X-RateLimit-Remaining` < 10 STOP the fan-out and report `THROTTLED` (D4); 1-2s between calls. Throttling, PR-comment rules and releases live in `references/github-api.md`.
 
-When `.devflow/conventions.md` is absent, fall back to heuristic branch-prefix detection from existing remote branches.
+Naming conventions: `learn-conventions` writes `.devflow/conventions.md` from a bounded scan (≤50 branches, ≤20 tags, ≤30 PR titles) and is its single authority; delete that file to re-learn.
 
 ---
 
@@ -271,6 +200,7 @@ When `.devflow/conventions.md` is absent, fall back to heuristic branch-prefix d
 | `references/violations.md` | Safety, commit, and PR anti-patterns |
 | `references/detection.md` | Sensitive file regex patterns and check functions |
 | `references/github-api.md` | Rate limiting, CLI commands, GraphQL, releases, review thread GraphQL |
+| `references/tracker/{provider}/{op}.md` | Generated per-op tracker mechanics (incl. the D3 template) |
 
 ## Checklist