devflow-kit 3.9.0 → 3.11.0

package/dist/compliance-off/commands/release.md

@@ -0,0 +1,309 @@
+---
+description: Release project using adaptive learned configuration
+---
+
+# Release Command
+
+Release the project using adaptive learned configuration. On first run, scans the codebase to detect the release process and stores it in `.release/RELEASE-FLOW.md`. Subsequent releases use the stored config, skipping discovery.
+
+## Usage
+
+```
+/release v1.2.3          (explicit version)
+/release patch           (bump type: patch | minor | major)
+/release --dry-run       (simulate release, show plan without executing)
+/release                 (interactive: ask for version)
+```
+
+## Input
+
+What follows `/release` is bound once, here. Every later step names it `COMMAND_INPUT` and never restates it:
+
+<command-input>
+$ARGUMENTS
+</command-input>
+
+`COMMAND_INPUT` is one of:
+- Explicit version: `v1.2.3` or `1.2.3`
+- Bump type: `patch`, `minor`, `major`
+- Flag: `--dry-run`
+- Empty: interactive mode (will ask for version)
+
+Parse from `COMMAND_INPUT`:
+- `VERSION`: explicit version string if present (strip leading `v`)
+- `BUMP_TYPE`: `patch | minor | major` if bump type provided
+- `DRY_RUN`: true if `--dry-run` present, false otherwise
+
+## Phases
+
+### Phase 1: Load Config
+
+**Produces:** RELEASE_CONFIG, CONFIG_STATE (`learned` | `fresh`)
+
+**Continuation detection**: Check `.release/.progress.json`. If exists, an interrupted release is in progress. Offer user:
+- **Resume**: continue from last checkpoint (skip phases already completed)
+- **Restart**: clean start (delete `.release/.progress.json` and begin from Phase 1)
+
+Read `.release/RELEASE-FLOW.md`:
+- If exists → parse as structured config, set CONFIG_STATE = learned, skip to Phase 4
+- If missing → set CONFIG_STATE = fresh, continue to Phase 2
+
+### Phase 1b: Load Context
+
+**Produces:** DECISIONS_CONTEXT, FEATURE_KNOWLEDGE, FEATURE_KNOWLEDGE_RULES
+
+**Resolve the settings line** once per worktree root, reusing a line this run already resolved for the same root. `{root}` is the worktree the values are for — the repository root in a one-worktree run:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-settings.cjs" "{root}" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `TRACKER=<github|jira|linear> TRACKER_SOURCE=<project|personal|machine|default> TRACKER_WARN=<none|mismatch|invalid> SITE=<none|https://<host>> KEY=<none|<key>> REVIEW_PUBLICATION=<off|auto|full> COMPLIANCE=<off|generic|<id>[,<id>…]> MEMORY=<on|off> CURATION=<on|off> KNOWLEDGE=<on|off> GATE_LEVEL=<full|standard|lean>` — these fields, in this order, nothing else, where `<host>` is a lowercase dotted host name alone, `<key>` is 2–10 of `A-Z`, `0-9` and `_` starting with a letter, and each `<id>` is one of `gdpr`, `hipaa`, `pci-dss`, `soc2`, `iso-27001`, `sox`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `TRACKER=github TRACKER_SOURCE=default TRACKER_WARN=invalid SITE=none KEY=none REVIEW_PUBLICATION=off COMPLIANCE=generic MEMORY=off CURATION=off KNOWLEDGE=off GATE_LEVEL=full` instead.
+
+The accepted line is the only source of these values.
+
+When the settings line says `CURATION=off`, set `DECISIONS_CONTEXT` to `(none)` and skip this step, locating no ledger and reading no index.
+
+The decisions ledger belongs to the repository, not to one checkout: a linked worktree reads the main worktree's copy, a subdirectory session the repository root's. Locate it with ONE git call, run from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`):
+
+```bash
+git -C "{start}" rev-parse --path-format=absolute --show-toplevel --git-common-dir
+```
+
+Line 1 is the checkout's toplevel, line 2 the common git directory. A git older than 2.31 echoes `--path-format=absolute` back as a line of its own first. `{ledger}` is the first that applies:
+
+1. **The main worktree** — line 2 without its trailing `/.git`, when the output is exactly two lines each beginning with `/`, line 2 ends in `/.git`, and the directory left once it is removed is not your home directory and contains a `.devflow/` directory.
+2. **The toplevel** — line 1, or on an older git the line after the echoed flag.
+3. **The start directory itself** — when the command failed or printed no absolute toplevel (outside a git repository).
+
+This is the rule the curation hooks apply, so you read the index the Curate agent writes.
+
+Read `{ledger}/.devflow/curation/index.md`. If the file is absent or empty, set `DECISIONS_CONTEXT` to `(none)`; otherwise use the file content as `DECISIONS_CONTEXT`.
+
+Hand each agent that takes `DECISIONS_CONTEXT` a slice, not the whole index: the index lines whose title, scope or area touch the files and task it works on, verbatim, led by `(slice: N of M entries — full index: <absolute index path>)` and closed by the index footer. When unsure, include the line. Siblings over one diff share ONE slice.
+
+### Load Feature Knowledge
+
+Resolve `{worktree}` as the checkout's toplevel, because feature knowledge bases are committed with the branch (D-PROMPT-ROOT): from the start directory — `WORKTREE_PATH` if provided, otherwise cwd (`devflow:worktree-support`) — run
+
+```bash
+git -C "{start}" rev-parse --show-toplevel
+```
+
+and use its one-line output. If the command fails (outside a git repository), `{worktree}` is the start directory itself. All paths below are relative to `{worktree}`.
+
+**Step 1 — Read the index cache:**
+
+Attempt to read `{worktree}/.devflow/features/index.md`. Each line follows the format:
+
+```
+- **{slug}** — {areas} — {Use-when description}
+```
+
+If `index.md` exists and contains at least one entry line, use it for relevance matching.
+
+**Step 2 — Fallback: glob frontmatter (if `index.md` is absent or empty):**
+
+Glob `{worktree}/.devflow/features/*/KNOWLEDGE.md`. For each file found, read only its YAML frontmatter block (between the opening and closing `---` delimiters).
+
+**Step 3 — Pick relevant KBs:**
+
+Match the current task area and description against each index line (or frontmatter `description` + `directories` on fallback). Select entries whose documented area overlaps the current task. This is a relevance judgment — prefer specificity over breadth.
+
+**Step 4 — Read each selected KB's Rules:**
+
+For each selected entry, `{kb}` is `{worktree}/.devflow/features/{slug}/KNOWLEDGE.md`:
+
+1. List its `##` headings with line numbers through Bash: `command grep -n '^## ' "{kb}"`. This only locates sections; the text of a KB comes from the Read view alone.
+2. Read the `## Rules` range (its line to the next heading) with the Read tool, using `offset` and `limit`, and choose the one to three bullets most relevant to the current task. The choice is yours, made per KB.
+3. If the KB has no `## Rules` section, choose one to three entries from its `## Anti-Patterns` or `## Gotchas` range the same way, and label them by that section's name instead of an ID.
+
+When a KB contradicts the code you observe, **trust the code** — the code is the freshness mechanism; the KB may lag behind. A missing Rules section, a missing heading list and `(none)` are legitimate states, not errors.
+
+**Step 5 — Set FEATURE_KNOWLEDGE and FEATURE_KNOWLEDGE_RULES:**
+
+Write one block per selected KB. Paste each bullet verbatim from the Read view, never from a shell view. The path is relative to the checkout root; an agent resolves it under `WORKTREE_PATH` when one is provided.
+
+```
+--- Feature knowledge: {slug} ---
+KB: .devflow/features/{slug}/KNOWLEDGE.md
+Rules:
+- **KB-AP-2** {bullet text, verbatim}
+- **KB-INV-1** {bullet text, verbatim}
+Headings: L5 Rules · L40 Overview · L62 Anti-Patterns · L118 Key Files
+```
+
+A KB with no Rules section labels its entries `Rules ({section name}):` and gives them no ID. `FEATURE_KNOWLEDGE` is these blocks; `FEATURE_KNOWLEDGE_RULES` is the same blocks without the `Headings:` line. Both come from this one selection, and each spawn names the variable its recipient takes. If no KBs exist, no KBs are relevant, or `.devflow/features/` is absent, set both to `(none)`.
+
+**One git call, then direct reads — no `.cjs` script.**
+
+Pass `DECISIONS_CONTEXT` and `FEATURE_KNOWLEDGE` only to agents whose contract declares them; the Validate and Git agents this command spawns do not.
+
+### Phase 1c: Resolve the Evidence Policy
+
+**Produces:** EVIDENCE_POLICY, ISSUE_REQUIRED, APPLY_CONVENTIONS, REQUIRE_NON_AUTHOR_APPROVAL
+
+**Resolve the evidence policy once per run**, from the repository root, before any step reads the values:
+
+```bash
+node "$HOME/.devflow/scripts/resolve-evidence-policy.cjs" 2>/dev/null; echo "exit=$?"
+```
+
+Accept the output only when it is exactly two lines: `exit=0` last and, before it, one line of the form `EVIDENCE_POLICY=<required|standard> SOURCE=<file|worktree|default|invalid|error> REF=<branch|none>[ WARN=<remote-unavailable|invalid-file|raised-by-compliance|pr-changes-policy>[,…]] ISSUE_REQUIRED=<true|false> APPLY_CONVENTIONS=<true|false> REQUIRE_NON_AUTHOR_APPROVAL=<true|false>` — these fields, in this order, nothing else, where `<branch>` is a branch name such as `main`. **Anything else** (a non-zero exit, no line, extra text, or a missing, reordered or unlisted field or value) ⇒ use `EVIDENCE_POLICY=required SOURCE=error REF=none ISSUE_REQUIRED=true APPLY_CONVENTIONS=true REQUIRE_NON_AUTHOR_APPROVAL=true` instead.
+
+Set `EVIDENCE_POLICY`, `ISSUE_REQUIRED`, `APPLY_CONVENTIONS` and `REQUIRE_NON_AUTHOR_APPROVAL` from the accepted line. Pass agents only the three mechanism inputs, never `EVIDENCE_POLICY`. Report `Evidence policy: {EVIDENCE_POLICY} (source: {SOURCE})`, plus any `WARN` tokens as advisory, once in the final report.
+
+Reuse this result for all subsequent phases: it decides whether a real release gathers its commit list (Phase 4) and passes it to the release notes (step 4).
+When `EVIDENCE_POLICY` is `required`, record `TRACEABILITY: DEGRADED (compliance off on this machine; the repository requires evidence)` once, for the completion report.
+
+### Phase 2: Detect Release Process (First Run Only)
+
+**Produces:** RELEASE_SIGNALS
+**Requires:** CONFIG_STATE = fresh
+
+Tiered codebase scan to detect the project's release process:
+
+**Tier 1** — Read these if they exist: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Dockerfile`, `.github/workflows/*.yml`, `CHANGELOG.md`
+
+**Tier 2** — Broaden: monorepo indicators (`lerna.json`, `pnpm-workspace.yaml`, `turbo.json`), release tool configs (`.releaserc`, `.changeset/`, `release-please-config.json`)
+
+**Tier 3** — Git history: `git tag -l` for tag format, `git log --oneline -20` for conventions
+
+Skip credential files (`.env*`, `*credentials*`, `*secret*`, `*.key`). Max 20 files total.
+
+### Phase 3: Build Config (First Run Only)
+
+**Produces:** RELEASE_CONFIG (written to disk)
+**Requires:** RELEASE_SIGNALS
+
+Map RELEASE_SIGNALS to `.release/RELEASE-FLOW.md` with sections: Packages, Pre-release Checks, Changelog, Build & Test, Publish, Post-release.
+
+**Conventions naming:** Consult `.devflow/conventions.md` (the naming authority written by the Git `learn-conventions` operation) for version/tag/version-PR title conventions. When the branching model uses version PRs, follow the Version PR Titles convention recorded there; compliance defaults when the file is absent. When the repo uses a main+integration branching model, ship via a version PR per the recorded convention. Re-learn by deleting `.devflow/conventions.md` — the next Git `learn-conventions` call rewrites it.
+
+Use AskUserQuestion for any gaps that cannot be inferred.
+
+Lazy-init `.release/` directory. Create `.release/.gitignore` with `.progress.json` and `.lock/`.
+
+### Phase 4: Pre-release Checks
+
+**Produces:** PRE_RELEASE_RESULT, VERSION, RELEASE_EVIDENCE
+**Requires:** RELEASE_CONFIG, EVIDENCE_POLICY
+
+**Version determination** (in order):
+1. Explicit version from args → use directly
+2. Bump type from args → compute from current version
+3. `semver-auto` strategy → analyze commits since the last release tag: the tag that `node "$HOME/.devflow/scripts/release-trace.cjs" last-tag`, run from the repository root, prints as `LAST_TAG <tag>` (`LAST_TAG none` ⇒ the initial commit) — never `git describe`, which can return a local marker tag
+4. None → use AskUserQuestion
+
+Pre-release checks:
+- Clean working directory (`git status --porcelain`)
+- Tag does not already exist
+- Custom checks from RELEASE_CONFIG
+
+Spawn `Agent(subagent_type="Validate")` for build + test.
+
+**Gather the commit list** — under either policy when `DRY_RUN` is true, otherwise only when `EVIDENCE_POLICY` is `required`: spawn `Agent(subagent_type="Git")` with `gather-release-evidence` operation; pass `WORKTREE_PATH` if provided. Keep `COMMIT_LIST` alone as RELEASE_EVIDENCE. The Git agent applies its own bounds and degrades gracefully per D4.
+
+Unless `DRY_RUN` is true, write `.release/.progress.json` checkpoint, with RELEASE_EVIDENCE when it was gathered — a dry run leaves nothing to resume.
+
+`--dry-run`: report what would happen and, when the commit list was gathered, that list — never asking — then **halt after this phase**.
+
+### Phase 5: Build Release Plan
+
+**Produces:** RELEASE_PLAN
+**Requires:** PRE_RELEASE_RESULT, RELEASE_CONFIG, VERSION, RELEASE_EVIDENCE
+
+Build ordered execution plan from RELEASE_CONFIG. For monorepo: respect dependency ordering, present package selection to user.
+
+Confirm with user via AskUserQuestion before executing:
+"Ready to release v{VERSION}. Plan: {steps summary}. Proceed?"
+
+`--dry-run`: should already be halted from Phase 4.
+
+### Phase 6: Execute Release
+
+**Produces:** RELEASE_RESULT
+**Requires:** RELEASE_PLAN, VERSION, EVIDENCE_POLICY, RELEASE_EVIDENCE
+
+Sequential execution with progress checkpoints:
+1. **Version bumps** — write new version to configured files
+2. **Changelog update** — move Unreleased section to versioned entry (if configured)
+
+**Load Companion Skills** (D-RELEASE-GIT-LOAD-LATE) — Load via Skill tool: `devflow:git`, here and not earlier: steps 1–2 only write files and `--dry-run` halts after Phase 4, so neither carries the skill. A resume that skips step 3 loads it before its next main-thread git write. If a skill fails to load, continue without it.
+
+3. **Release commit** — `chore(release): v{VERSION}` (conventional commit)
+4. **Tag and GitHub Release** — spawn `Agent(subagent_type="Git")` with `create-release` operation (the agent reads `.devflow/conventions.md` for tag format and release title conventions; compliance defaults when absent); only when `EVIDENCE_POLICY` is `required`, also pass `COMMIT_LIST` from RELEASE_EVIDENCE as an input so the agent includes it in the release notes body.
+5. **Publish** — CI-driven (report) or manual (provide instructions)
+6. **Post-release steps** — version bump to next dev
+
+**Resume:** a checkpoint missing the RELEASE_EVIDENCE its Phase 4 gate called for is gathered again only before step 4; after step 4, report `evidence lost on resume` and continue — never block.
+
+Delete `.release/.progress.json` on success.
+
+### Phase 7: Suggest Improvements
+
+**Requires:** RELEASE_RESULT
+
+Post-release analysis for improvement opportunities. Present as suggested diffs to RELEASE-FLOW.md. Never auto-apply. Fire-and-forget.
+
+## Worktree Support
+
+If the orchestrator receives a `WORKTREE_PATH` context, pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution.
+
+## Output
+
+On completion:
+- Git tag created: `v{VERSION}` (or configured tag format)
+- GitHub Release created with release notes
+- Changelog updated (if configured)
+- Version files bumped
+- `.release/RELEASE-FLOW.md` created (first run only)
+
+## Architecture
+
+```
+/release (orchestrator)
+│
+├─ Phase 1: Load Config
+│  └─ Read .release/RELEASE-FLOW.md (learned) or proceed to detect (fresh)
+│
+├─ Phase 1b: Load Context
+│  └─ Load DECISIONS_CONTEXT and FEATURE_KNOWLEDGE for the agents that declare them
+│
+├─ Phase 2: Detect Release Process (first run only)
+│  └─ Tiered scan: package.json, CI workflows, git history
+│
+├─ Phase 3: Build Config (first run only)
+│  └─ Write .release/RELEASE-FLOW.md
+│
+├─ Phase 4: Pre-release Checks
+│  ├─ Validate agent (build + test)
+│  ├─ Git agent: gather the commit list (dry run, or evidence policy required)
+│  └─ Write progress checkpoint
+│
+├─ Phase 5: Build Release Plan
+│  └─ Confirm with user before executing
+│
+├─ Phase 6: Execute Release
+│  ├─ Version bumps → Changelog → Commit → Git agent (tag + release) → Publish → Post-release
+│  └─ Progress checkpoints between each step
+│
+└─ Phase 7: Suggest Improvements
+   └─ Suggested diffs to RELEASE-FLOW.md (never auto-applied)
+```
+
+## Principles
+
+1. **Learn once, reuse always** — discovery happens on first run; subsequent releases skip it
+2. **Config is data, not code** — structured config fields map to pre-defined operations, never raw shell commands
+3. **Checkpoint-resume** — progress file enables safe resume of interrupted releases
+4. **User confirms before execution** — release plan is presented for approval before any tags or commits
+
+## Error Handling
+
+- Validate agent reports no PASS: halt, report failures, do not proceed
+- User declines release plan: halt gracefully
+- Git agent reports DEGRADED while gathering: warn and continue — never halt the release
+- Git agent fails (tag/release): halt, report error, suggest manual steps
+- Mid-release failure: progress checkpoint enables resume on next run
+- Version file not found: halt, report which file is missing, ask user to update RELEASE-FLOW.md