devflow-kit 3.5.0 → 3.7.0

package/dist/learning-off/commands/self-review.md

@@ -1,9 +1,9 @@
 ---
-description: Self-review workflow - Simplify agent (code clarity) then Scrutinize agent (9-pillar quality gate)
+description: Self-review workflow - Polish agent (code clarity) then Harden agent (9-pillar quality gate)
 ---
 # Self-Review Command
 
-Run Simplify agent and Scrutinize agent sequentially on changed files for post-implementation quality refinement.
+Run Polish agent and Harden agent sequentially on changed files for post-implementation quality refinement.
 
 ## Usage
 
@@ -22,7 +22,7 @@ Detect changed files and build context:
 2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged
 3. If no changes found, report "No changes to review" and exit
 4. Build TASK_DESCRIPTION from recent commit messages or branch name
-5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Simplify runs — Phase 3 compares against it
+5. Record `HEAD_BEFORE` (`git rev-parse HEAD`) now, before Polish runs — Phase 3 compares against it
 
 **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 when the run has one worktree:
 
@@ -30,9 +30,9 @@ Detect changed files and build context:
 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> LEARNING=<on|off> KNOWLEDGE=<on|off>` — 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=on LEARNING=on KNOWLEDGE=off` instead.
+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> LEARNING=<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=on LEARNING=on KNOWLEDGE=off GATE_LEVEL=full` instead.
 
-The accepted line is the only source of these values: the script alone folds the committed `.devflow/project.json`, the personal `.devflow/config.json` and the machine manifest.
+The accepted line is the only source of these values.
 
 ### Load Feature Knowledge
 
@@ -56,7 +56,7 @@ If `index.md` exists and contains at least one entry line, use it for relevance
 
 **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). The frontmatter fields `name`, `description`, and `directories` are the authoritative relevance surface — `index.md` is only a cache.
+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:**
 
@@ -87,35 +87,35 @@ 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.** After resolving `{worktree}`, this step is 1 index read (or N frontmatter reads on fallback), plus one heading listing and one Rules read per selected KB, bounded by KB count.
+**One git call, then direct reads — no `.cjs` script.**
 
-Pass `FEATURE_KNOWLEDGE_RULES` to Scrutinize agent.
+Pass `FEATURE_KNOWLEDGE_RULES` to Harden agent.
 
 **Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), FEATURE_KNOWLEDGE (string, optional), FEATURE_KNOWLEDGE_RULES (string, optional), HEAD_BEFORE (40-hex SHA)
 
-### Phase 1: Simplify agent (Code Refinement)
+### Phase 1: Polish agent (Code Refinement)
 
-**Produces:** SIMPLIFY_COMMITS
+**Produces:** POLISH_COMMITS
 **Requires:** FILES_CHANGED, TASK_DESCRIPTION
 
-Spawn Simplify agent to refine code for clarity and consistency:
+Spawn Polish agent to refine code for clarity and consistency:
 
-Agent(subagent_type="Simplify", run_in_background=false):
+Agent(subagent_type="Polish", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
-Simplify and refine the code for clarity and consistency while preserving functionality.
+Polish and refine the code for clarity and consistency while preserving functionality.
 Commit any improvements with a conventional-commit message."
 
-**Wait for completion.** Simplify agent commits changes directly.
+**Wait for completion.** Polish agent commits changes directly.
 
-### Phase 2: Scrutinize agent (9-Pillar Quality Gate)
+### Phase 2: Harden agent (9-Pillar Quality Gate)
 
-**Produces:** SCRUTINIZE_STATUS
+**Produces:** HARDEN_STATUS
 **Requires:** FILES_CHANGED, TASK_DESCRIPTION
 
-Spawn Scrutinize agent for quality evaluation and fixing:
+Spawn Harden agent for quality evaluation and fixing:
 
-Agent(subagent_type="Scrutinize", run_in_background=false):
+Agent(subagent_type="Harden", run_in_background=false):
 "TASK_DESCRIPTION: {task_description}
 FILES_CHANGED: {files_changed}
 FEATURE_KNOWLEDGE: {feature_knowledge_rules}
@@ -127,11 +127,11 @@ Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
 ### Phase 3: Conditional Validation
 
 **Produces:** VALIDATION_RESULT
-**Requires:** HEAD_BEFORE, SCRUTINIZE_STATUS
+**Requires:** HEAD_BEFORE, HARDEN_STATUS
 
 If STATUS is BLOCKED, skip this phase: the report (Phase 4) names the blocker.
 
-Run this phase only if HEAD moved — `git rev-parse HEAD` differs from `HEAD_BEFORE`, meaning Simplify or Scrutinize committed (Simplify alone counts, whatever Scrutinize's STATUS is). Otherwise skip it. Its scope is changed-only over what the two agents changed:
+Run this phase only if HEAD moved — `git rev-parse HEAD` differs from `HEAD_BEFORE`, meaning Polish or Harden committed (Polish alone counts, whatever Harden's STATUS is). Otherwise skip it. Its scope is changed-only over what the two agents changed:
 
 Agent(subagent_type="Validate", run_in_background=false):
 "FILES_CHANGED: {output of `git diff --name-only HEAD_BEFORE..HEAD`}
@@ -143,7 +143,7 @@ Run build, typecheck, lint, test on modified files"
 
 ### Phase 4: Report
 
-**Requires:** SCRUTINIZE_STATUS, VALIDATION_RESULT
+**Requires:** HARDEN_STATUS, VALIDATION_RESULT
 
 Display summary:
 
@@ -152,10 +152,10 @@ Display summary:
 **Files Reviewed**: {n}
 **Status**: {PASS|FIXED|BLOCKED}
 
-### Simplify agent
+### Polish agent
 - {n} files refined for clarity
 
-### Scrutinize agent (9-Pillar Evaluation)
+### Harden agent (9-Pillar Evaluation)
 | Pillar | Status |
 |--------|--------|
 | Design | {status} |
@@ -209,16 +209,12 @@ FILES_CHANGED: {list of files changed}
 Write the knowledge base to:
   {worktree}/.devflow/features/{slug}/KNOWLEDGE.md
 
-Then update the index cache by performing a read-modify-write on:
+Then update the index cache:
   {worktree}/.devflow/features/index.md
 
 Index line format: `- **{slug}** — {areas} — {Use-when description}` — at most 300 characters, the description at most 220; reword a longer one, never cut it.
 
-If the line for this slug already exists in index.md, replace it. If it does not exist, append it. If index.md does not exist, create it with just this line.
-
-The frontmatter in KNOWLEDGE.md is the source of truth — index.md is only a cache. Write the two files directly — no intermediate result JSON files, no external scripts.
-
-After writing, commit the two files to the current worktree branch yourself by running git via your Bash tool (do not use a script). Stage ONLY .devflow/features/index.md and .devflow/features/{slug}/KNOWLEDGE.md, then commit just those paths with a docs(knowledge): message. Do NOT push, do NOT force, do NOT stage anything else. Follow your Commit Protocol — it is non-blocking, so if any git step fails, report KB_COMMIT and finish normally."
+Then commit the two files as your Commit Protocol directs."
 ```
 
 **Step 4 — Surface an uncommitted knowledge base:**
@@ -235,14 +231,14 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 │  ├─ Git diff for changed files
 │  └─ Record HEAD_BEFORE
 │
-├─ Phase 1: Simplify agent
+├─ Phase 1: Polish agent
 │  └─ Code refinement (commits directly)
 │
-├─ Phase 2: Scrutinize agent
+├─ Phase 2: Harden agent
 │  └─ 9-pillar quality gate (may fix and commit)
 │
 ├─ Phase 3: Validate agent (conditional)
-│  └─ If HEAD moved since HEAD_BEFORE (Simplify or Scrutinize committed), changed-only Validate over HEAD_BEFORE..HEAD
+│  └─ If HEAD moved since HEAD_BEFORE (Polish or Harden committed), changed-only Validate over HEAD_BEFORE..HEAD
 │
 └─ Phase 4: Report
    └─ Display summary with pillar status
@@ -252,15 +248,15 @@ When the Knowledge agent reports `KB_COMMIT: skipped (detached HEAD)`, the files
 | Case | Handling |
 |------|----------|
 | No changes | Report "No changes to review" and exit |
-| Simplify agent finds nothing | Normal, continue to Scrutinize agent |
-| Scrutinize agent BLOCKED | Report blocking issue, halt workflow |
+| Polish agent finds nothing | Normal, continue to Harden agent |
+| Harden agent BLOCKED | Report blocking issue, halt workflow |
 | Validation fails | Report failures, halt (don't create broken state) |
 | Not in git repo | Report error, suggest running in git repo |
 
 ## Principles
 
 1. **Orchestration only** - Command spawns agents, doesn't do the work
-2. **Sequential execution** - Simplify agent must complete before Scrutinize agent
-3. **Validation gate** - If Simplify agent or Scrutinize agent committed, the changes must pass validation
+2. **Sequential execution** - Polish agent must complete before Harden agent
+3. **Validation gate** - If Polish agent or Harden agent committed, the changes must pass validation
 4. **Honest reporting** - Display actual agent outputs
 5. **Fail fast** - Stop on BLOCKED or validation failure

package/dist/skills/git/references/pr/check-merge-readiness.md

@@ -25,6 +25,8 @@ Load for `check-merge-readiness` under every tracker provider.
 
 ### Process
 
+Run the script from `WORKTREE_PATH` (else cwd) and print its stdout, nothing else: `node "$HOME/.devflow/scripts/verify-evidence.cjs" readiness --pr {PR_NUMBER}; echo "exit=$?"`, adding `--require-non-author-approval {REQUIRE_NON_AUTHOR_APPROVAL}` only when that is `true` or `false`, with the Bash `timeout` at 180000. On exit 0 or 2 its stdout is the `## Merge Readiness` block (exit 2: `DEGRADED`, closed by a `TRACEABILITY: DEGRADED ({reason})` line); any other exit, or empty stdout, is `TRACEABILITY: DEGRADED (readiness unavailable)`. The script makes the reads and applies the ladder below, so the steps are its specification: run none of them yourself.
+
 1. Fetch unresolved review threads via GraphQL: `reviewThreads(first: 100) { nodes { isResolved } totalCount }`. Count unresolved from nodes (`isResolved == false`). If `totalCount > 100`, report the unresolved count as approximate: prefix with `>` and note `(count approximate — PR has more than 100 threads)`.
 2. Fetch PR review decision: `gh pr view {PR_NUMBER} --json reviewDecision --jq '.reviewDecision'`
    - Values: `APPROVED`, `CHANGES_REQUESTED`, `REVIEW_REQUIRED`, or null

package/dist/skills/git/references/pr/update-pr-evidence.md

@@ -15,13 +15,11 @@ Update the PR's test-plan block and evidence comment.
 
 Load for `update-pr-evidence` under every tracker provider.
 
-**PR mechanics held here:** the evidence script run, the compare-and-swap body edit and the append-only evidence comment. The script owns every marker, grammar and state rule; nothing here restates one.
+**PR mechanics held here:** the one script run. `verify-evidence.cjs publish` owns every step, marker, grammar and state rule, and scrubs (D11) each body before it posts one; nothing here restates any of them.
 
 ### Process
 
-Run steps 1–4 as ONE Bash invocation from `WORKTREE_PATH` (else cwd) — the trap removes `$S` and the temp files when it exits — with `V="$HOME/.devflow/scripts"`.
+1. From `WORKTREE_PATH` (else cwd), run `node "$HOME/.devflow/scripts/verify-evidence.cjs" publish --pr {PR_NUMBER}; echo "exit=$?"`, adding `--publication {REVIEW_PUBLICATION}` only when that is `auto`, `full`, `off` or `stub`, and `--evidence "{EVIDENCE_FILE}"` when given — only a value matching `^[A-Za-z0-9._/-]{1,255}$` reaches the shell; any other is a failed run. Set the Bash `timeout` to 180000.
+2. Print the script's stdout and nothing else. On exit 0 it is the `## PR Evidence` block: the heading, the line `EVIDENCE pr:<n> head:<sha> total:<n> VERIFIED-CI:<n> ATTESTED-LOCAL:<n> UNVERIFIED:<n> STALE:<n> FAILED:<n> INDETERMINATE:<n> stale:<ids|none> exceptions:<kinds|none> approval:<yes|no|unchecked> key:<hex> posted:<yes|no|n/a> body:<same|changed>`, and the `**Body**:` / `**Comment**:` line, then one `TRACEABILITY: DEGRADED ({reason})` line for each part that degraded, such as `DEGRADED (concurrent edit)` (the body edit then reads `SKIPPED`), `DEGRADED (body read-back mismatch)` or `DEGRADED (redaction unavailable)`: a body the script cannot scrub is never posted. On exit 2 it is `TRACEABILITY: DEGRADED (evidence unavailable)`. Any other exit, or empty stdout, is a failed run: emit that same line.
 
-1. **Verify.** Set `S=`, arm the D11 trap with `[ -n "$S" ] && { rm -- "$S/base" "$S/base.sha256"; rmdir -- "$S"; } 2>/dev/null` added before its `exit`, then the four `mktemp`s and `S="$(mktemp -d)"`. Run `node "$V/verify-evidence.cjs" verify --pr {PR_NUMBER} --state "$S" --block-out "$DEVFLOW_NOTES_RAW" --comment-out "$DEVFLOW_BODY_RAW"`, adding `--publication {REVIEW_PUBLICATION}` only when that is `auto`, `full`, `off` or `stub`, and `--evidence "{EVIDENCE_FILE}"` when given — only a value matching `^[A-Za-z0-9._/-]{1,255}$` reaches the shell; any other is a failed run. Continue only on exit 0 with stdout exactly one line, `EVIDENCE pr:<n> head:<sha> total:<n> VERIFIED-CI:<n> ATTESTED-LOCAL:<n> UNVERIFIED:<n> STALE:<n> FAILED:<n> INDETERMINATE:<n> stale:<ids|none> exceptions:<kinds|none> approval:<yes|no|unchecked> key:<hex> posted:<yes|no|n/a> body:<same|changed>`; otherwise emit `TRACEABILITY: DEGRADED (evidence unavailable)` and stop. The script makes this op's one `gh pr view` read and prints nothing it read from the PR; never read the PR another way.
-2. **Body**, only on `body:changed` (else `UNCHANGED`): `node "$V/redact-secrets.cjs" "$DEVFLOW_NOTES_RAW" "$DEVFLOW_NOTES" && node "$V/verify-evidence.cjs" splice --pr {PR_NUMBER} --state "$S" --block "$DEVFLOW_NOTES" --out "$DEVFLOW_BODY" && gh pr edit {PR_NUMBER} --body-file "$DEVFLOW_BODY"`. Only the composed block is scrubbed (D11); every byte outside its markers is the PR's own and stays identical. `splice` re-reads the body: unchanged since step 1 → it writes; changed → it splices once onto the fresh body and re-reads; changed again → `SPLICE conflict`: `SKIPPED` and `TRACEABILITY: DEGRADED (concurrent edit)`. Any other non-zero → `DEGRADED ({reason})`, naming a printed `SPLICE` token. No edit either way; go to step 4.
-3. **Read back** after an edit: `node "$V/verify-evidence.cjs" readback --pr {PR_NUMBER} --expect "$DEVFLOW_BODY"`; anything but `READBACK ok` → `TRACEABILITY: DEGRADED (body read-back mismatch)`, else `EDITED`. GitHub has no conditional body edit: a human edit landing between the last re-read and `gh pr edit` is overwritten (it stays in the PR's edit history), and the read-back proves only that these bytes landed.
-4. **Comment.** `posted:yes` → `SKIPPED`; `posted:n/a` → `OFF`. Otherwise apply the Comment-sink scrub (D11): `node "$V/redact-secrets.cjs" "$DEVFLOW_BODY_RAW" "$DEVFLOW_BODY" && gh pr comment {PR_NUMBER} --body-file "$DEVFLOW_BODY"` → `POSTED`. Never edit or delete an evidence comment. On 5xx retry once; still 5xx → `DEGRADED ({reason})`.
+Run nothing else: the script makes the one PR read, the compare-and-swap body edit, its read-back and the append-only comment itself, and posts nothing it could not scrub.

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

@@ -32,7 +32,7 @@ Pre-flight: make the branch ready for review and open its PR.
 
 Load when the resolved tracker provider is `github` and the operation is `ensure-pr-ready`.
 
-**Mechanics held here:** the whole operation. Steps 1–4a, the PR-host half of step 4b and steps 4c–6 are PR-host mechanics, the same under every provider (written once in `_ops.mds`); step 4b is this provider's: the issue-number resolution and its `Closes #{n}` line.
+**Mechanics held here:** the whole operation. Steps 1–4a, the PR-host half of step 4b and steps 4c–6 are PR-host mechanics, the same under every provider (written once in `_ops.mds`); step 4b takes its link line and refuses it the same way under every provider; the line itself, `Closes #{n}`, is this provider's.
 
 ### Process
 
@@ -66,11 +66,11 @@ Load when the resolved tracker provider is `github` and the operation is `ensure
 
    This is a sink check, not a provider check: the spawn that resolved the provider rendered the line, this spawn does not re-derive it, and you never decide it. Two bounds sit outside the pattern because an anchor cannot express them, and you apply both: the value is **rejected if it carries a newline** — anchors are read as end-of-LINE by some engines, and everything after the first line would land in the PR body as free text — and rejected if it exceeds **60 characters**, which no valid line approaches.
 
-   `(none)`, or an absent `### Handoff Values` block, is **not a mismatch**: it means no line was captured, so emit the `## Related Issues` heading with no reference — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and emit the heading with no reference.
+   `(none)` is **not a mismatch**: it means no line was captured — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)`.
 
-   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs at this paste because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN` yourself; if the block is absent, say so rather than inventing either value.
+   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs at this paste because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN`; if the block is absent, say so.
 
-   **A given `ISSUE_PR_LINK` is final.** When it is given and not `(none)`, it is the section's whole answer, whether the gate above admitted it or refused it: step 4b does not resolve a number, verify a branch pattern or render a line. An admitted line goes under `## Related Issues` in the body this step creates; on an existing PR whose body has no `## Related Issues` section, step 4b's PR-host half publishes it. A refused line leaves the heading with no reference. `(none)` or absent leaves the answer to step 4b.
+   **A given `ISSUE_PR_LINK` is final.** When it is given, `(none)` included, it is the section's whole answer, whether the gate above admitted it or refused it: step 4b does not resolve a number or render a line. An admitted line goes under `## Related Issues` in the body this step creates; on an existing PR whose body has no `## Related Issues` section, step 4b's PR-host half publishes it. Only an absent `ISSUE_PR_LINK` goes to step 4b, and only when no admitted wave block exists. When `ISSUE_NUMBER` is set and no line is admitted, emit the heading with no reference and `TRACEABILITY: DEGRADED (ambiguous issue reference)`; when it is `(none)`, write no heading.
 
    **Pasting `PR_EXCEPTIONS`.** When `PR_EXCEPTIONS` is provided (not `(none)`), append it verbatim as the body's last section — it is scrubbed with the body. Re-check its shape first: its first line must be exactly `## Evidence Exceptions`, and every line after it must match this pattern as the WHOLE line:
 
@@ -82,14 +82,12 @@ Load when the resolved tracker provider is `github` and the operation is `ensure
 
    **D11 scrub (PR body is a GitHub-visible sink):** Compose the final PR body to `$DEVFLOW_BODY_RAW` (`DEVFLOW_BODY_RAW="$(mktemp)"`); scrub via `node "$HOME/.devflow/scripts/redact-secrets.cjs" "$DEVFLOW_BODY_RAW" "$DEVFLOW_BODY"` (where `DEVFLOW_BODY="$(mktemp)"`). On success: create PR with `gh pr create … --body-file "$DEVFLOW_BODY"`. **On scrubber failure** (non-zero exit or script missing): still create the PR — PR existence is the deliverable — but with a minimal body containing only the task reference, plan path (if available), and issue link (if ISSUE_NUMBER provided), plus the literal line `TRACEABILITY: DEGRADED (redaction unavailable)`. Never post `$DEVFLOW_BODY_RAW`.
 
-4b. (ALWAYS-ON) Ensure PR body contains a `## Related Issues` section with `Closes #{n}` link when a verified issue number is known. A given `ISSUE_PR_LINK` is already decided in step 4a: skip the resolution below. Resolution order:
-   a. Prefer the issue number returned by `setup-task` / `ensure-traceable-issue` for this branch.
-   b. If unavailable, fall back to the branch name pattern `{type}/{number}-{slug}`: extract the numeric segment and verify with `gh issue view {n} --json number,state`. If the call fails or `.state` is not `"open"`, skip silently — never add a `Closes` link for an unverified number. Branches like `chore/2026-cleanup` or `fix/2fa-login` may produce false matches; the existence check is the guard.
+4b. (ALWAYS-ON) Ensure the PR body contains a `## Related Issues` section with the `Closes #{n}` line of this branch's issue. A given `ISSUE_PR_LINK` is already decided in step 4a: skip the resolution below. Resolution: the only source is the `PR link line` of the `### Handoff Values` block that `setup-task` or `fetch-issue` returned for this branch. Publish it only if it passes step 4a's shape check. A line that fails the check is refused as step 4a refuses it, not repaired: emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and publish nothing. This step composes no line itself. Never compose a line from a bare issue number or a branch name.
 
    Publish the section through step 4b's PR-host half.
 
-   If no verified issue number is discoverable, skip silently.
-   On any 4xx/5xx from `gh pr edit` when updating the body: emit `TRACEABILITY: DEGRADED ({reason})` and continue — a failed Related Issues update never blocks the PR.
+   If no such line exists, skip silently.
+   A failure while updating the PR body emits `TRACEABILITY: DEGRADED ({reason})` and continues — a failed Related Issues update never blocks the PR.
 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.

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

@@ -32,7 +32,7 @@ Pre-flight: make the branch ready for review and open its PR.
 
 Load when the resolved tracker provider is `jira` and the operation is `ensure-pr-ready`.
 
-**Mechanics held here:** the whole operation. Steps 1–4a, the PR-host half of step 4b and steps 4c–6 are PR-host mechanics, the same under every provider (written once in `_ops.mds`): devflow deliberately keeps pull requests on their existing host while the tracker is this one, so nothing about the PR surface is provider-dependent. Step 4b is this provider's: resolving the issue key for this branch and rendering the link line.
+**Mechanics held here:** the whole operation. Steps 1–4a, the PR-host half of step 4b and steps 4c–6 are PR-host mechanics, the same under every provider (written once in `_ops.mds`): devflow deliberately keeps pull requests on their existing host while the tracker is this one, so nothing about the PR surface is provider-dependent. Step 4b takes its link line and refuses it the same way under every provider; only its note on closing effects is this provider's.
 
 ### Process
 
@@ -66,11 +66,11 @@ Load when the resolved tracker provider is `jira` and the operation is `ensure-p
 
    This is a sink check, not a provider check: the spawn that resolved the provider rendered the line, this spawn does not re-derive it, and you never decide it. Two bounds sit outside the pattern because an anchor cannot express them, and you apply both: the value is **rejected if it carries a newline** — anchors are read as end-of-LINE by some engines, and everything after the first line would land in the PR body as free text — and rejected if it exceeds **60 characters**, which no valid line approaches.
 
-   `(none)`, or an absent `### Handoff Values` block, is **not a mismatch**: it means no line was captured, so emit the `## Related Issues` heading with no reference — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and emit the heading with no reference.
+   `(none)` is **not a mismatch**: it means no line was captured — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)`.
 
-   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs at this paste because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN` yourself; if the block is absent, say so rather than inventing either value.
+   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs at this paste because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN`; if the block is absent, say so.
 
-   **A given `ISSUE_PR_LINK` is final.** When it is given and not `(none)`, it is the section's whole answer, whether the gate above admitted it or refused it: step 4b does not resolve a number, verify a branch pattern or render a line. An admitted line goes under `## Related Issues` in the body this step creates; on an existing PR whose body has no `## Related Issues` section, step 4b's PR-host half publishes it. A refused line leaves the heading with no reference. `(none)` or absent leaves the answer to step 4b.
+   **A given `ISSUE_PR_LINK` is final.** When it is given, `(none)` included, it is the section's whole answer, whether the gate above admitted it or refused it: step 4b does not resolve a number or render a line. An admitted line goes under `## Related Issues` in the body this step creates; on an existing PR whose body has no `## Related Issues` section, step 4b's PR-host half publishes it. Only an absent `ISSUE_PR_LINK` goes to step 4b, and only when no admitted wave block exists. When `ISSUE_NUMBER` is set and no line is admitted, emit the heading with no reference and `TRACEABILITY: DEGRADED (ambiguous issue reference)`; when it is `(none)`, write no heading.
 
    **Pasting `PR_EXCEPTIONS`.** When `PR_EXCEPTIONS` is provided (not `(none)`), append it verbatim as the body's last section — it is scrubbed with the body. Re-check its shape first: its first line must be exactly `## Evidence Exceptions`, and every line after it must match this pattern as the WHOLE line:
 
@@ -82,16 +82,12 @@ Load when the resolved tracker provider is `jira` and the operation is `ensure-p
 
    **D11 scrub (PR body is a GitHub-visible sink):** Compose the final PR body to `$DEVFLOW_BODY_RAW` (`DEVFLOW_BODY_RAW="$(mktemp)"`); scrub via `node "$HOME/.devflow/scripts/redact-secrets.cjs" "$DEVFLOW_BODY_RAW" "$DEVFLOW_BODY"` (where `DEVFLOW_BODY="$(mktemp)"`). On success: create PR with `gh pr create … --body-file "$DEVFLOW_BODY"`. **On scrubber failure** (non-zero exit or script missing): still create the PR — PR existence is the deliverable — but with a minimal body containing only the task reference, plan path (if available), and issue link (if ISSUE_NUMBER provided), plus the literal line `TRACEABILITY: DEGRADED (redaction unavailable)`. Never post `$DEVFLOW_BODY_RAW`.
 
-4b. (ALWAYS-ON) Ensure the PR body contains a `## Related Issues` section naming the verified issue when one is known. A given `ISSUE_PR_LINK` is already decided in step 4a: skip the resolution and the rendering below. Resolution order:
-   a. Prefer the issue key returned by `setup-task` / `ensure-traceable-issue` for this branch — it was verified at creation time.
-   b. Otherwise fall back to the branch name pattern `{type}/{KEY}-{slug}`: extract the segment matching `^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$` and verify it with the *fetch by key* capability. If the call fails, or the issue is not open, **skip silently** — never render a link for an unverified reference. A branch name can carry a token that merely looks like one, and the existence check is the guard.
-   c. The *fetch by key* capability absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for fetch by key)` and skip the section; the PR is never blocked on it.
-
-   Render the line through `## Reference Rendering`. **This provider has no closing-reference magic** — a reference in a PR body does not transition or close anything here, and claiming otherwise in the rendered text would promise an effect that never happens; closing is a `## Transitions` matter and `gather-release-evidence` reports the absence as `TRACEABILITY: DEGRADED (unsupported by jira)`. `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the key on its own line under the section heading, and record the discard under `### Substitutions`.
+4b. (ALWAYS-ON) Ensure the PR body contains a `## Related Issues` section with the `Refs {KEY}-{n}` line of this branch's issue. A given `ISSUE_PR_LINK` is already decided in step 4a: skip the resolution below. Resolution: the only source is the `PR link line` of the `### Handoff Values` block that `setup-task` or `fetch-issue` returned for this branch. Publish it only if it passes step 4a's shape check. A line that fails the check is refused as step 4a refuses it, not repaired: emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and publish nothing. This step composes no line itself. Never compose a line from a bare issue number or a branch name. **This provider has no closing-reference magic** — a reference in a PR body does not transition or close anything here, and claiming otherwise in the rendered text would promise an effect that never happens; closing is a `## Transitions` matter and `gather-release-evidence` reports the absence as `TRACEABILITY: DEGRADED (unsupported by jira)`.
 
    Publish the section through step 4b's PR-host half.
 
-   If no verified issue key is discoverable, skip silently. A failure while updating the PR body emits `TRACEABILITY: DEGRADED ({reason})` and continues — a failed Related Issues update never blocks the PR.
+   If no such line exists, skip silently.
+   A failure while updating the PR body emits `TRACEABILITY: DEGRADED ({reason})` and continues — a failed Related Issues update never blocks the PR.
 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.
@@ -100,10 +96,6 @@ Load when the resolved tracker provider is `jira` and the operation is `ensure-p
 5. Get base branch from PR
 6. Derive branch-slug (replace `/` with `-`)
 
-**The read-site shape gate for `## Reference Rendering`.** The token arrives from the tracker configuration file, which is hand-editable and machine-wide, so it is parsed HERE — at the sink that renders it, and never on the writer's word. Require `^[A-Za-z0-9 #{}/_.-]{1,60}$`, anchored at both ends, and **discard** any token carrying a backtick, a `$`, a `"`, a `\`, a `;` or a newline. The anchored shape is the gate; the metachar denylist is a second, independent control, named separately so widening the shape for a new token form cannot silently relax it. **Discard, never repair** — a repaired token is one nobody can predict — and a discarded token falls back to **the resolved provider's** documented default, stated once in that provider's own mechanics, with a `### Substitutions` row recording what was dropped. An absent `## Reference Rendering` section, an absent file and a discarded token are the SAME outcome: the documented default. This gate never yields `# UNRESOLVED:`.
-
-**This provider's documented default is `Refs {KEY}-{n}`.** It is stated here because it is a provider fact, and the gate above is what routes to it: a section that is absent, a file that is absent and a token the gate discarded all render this, and none of them is a degradation.
-
 ### Step 4b's PR-host half
 
 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"`.

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

@@ -32,7 +32,7 @@ Pre-flight: make the branch ready for review and open its PR.
 
 Load when the resolved tracker provider is `linear` and the operation is `ensure-pr-ready`.
 
-**Mechanics held here:** the whole operation. Steps 1–4a, the PR-host half of step 4b and steps 4c–6 are PR-host mechanics, the same under every provider (written once in `_ops.mds`): devflow deliberately keeps pull requests on their existing host while the tracker is this one, so nothing about the PR surface is provider-dependent. Step 4b is this provider's: resolving the issue reference for this branch and rendering the link line.
+**Mechanics held here:** the whole operation. Steps 1–4a, the PR-host half of step 4b and steps 4c–6 are PR-host mechanics, the same under every provider (written once in `_ops.mds`): devflow deliberately keeps pull requests on their existing host while the tracker is this one, so nothing about the PR surface is provider-dependent. Step 4b takes its link line and refuses it the same way under every provider; only its note on closing effects is this provider's.
 
 ### Process
 
@@ -66,11 +66,11 @@ Load when the resolved tracker provider is `linear` and the operation is `ensure
 
    This is a sink check, not a provider check: the spawn that resolved the provider rendered the line, this spawn does not re-derive it, and you never decide it. Two bounds sit outside the pattern because an anchor cannot express them, and you apply both: the value is **rejected if it carries a newline** — anchors are read as end-of-LINE by some engines, and everything after the first line would land in the PR body as free text — and rejected if it exceeds **60 characters**, which no valid line approaches.
 
-   `(none)`, or an absent `### Handoff Values` block, is **not a mismatch**: it means no line was captured, so emit the `## Related Issues` heading with no reference — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and emit the heading with no reference.
+   `(none)` is **not a mismatch**: it means no line was captured — never compose one from `ISSUE_NUMBER`. A bare issue number is not a reference at all — the same digits name a different issue under each provider — which is why `TRACEABILITY: DEGRADED (ambiguous issue reference)` exists rather than a `#`-prefixed guess. On a MISMATCH, do not paste it and do not repair it — emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)`.
 
-   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs at this paste because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN` yourself; if the block is absent, say so rather than inventing either value.
+   This re-check is the only gate on that value — no operation checks the rendered line's shape before returning it — and it belongs at this paste because a value that was well-formed when it was produced is still attacker-influenceable text by the time it reaches a GitHub-visible sink. Never re-derive `ISSUE_BRANCH_TOKEN`; if the block is absent, say so.
 
-   **A given `ISSUE_PR_LINK` is final.** When it is given and not `(none)`, it is the section's whole answer, whether the gate above admitted it or refused it: step 4b does not resolve a number, verify a branch pattern or render a line. An admitted line goes under `## Related Issues` in the body this step creates; on an existing PR whose body has no `## Related Issues` section, step 4b's PR-host half publishes it. A refused line leaves the heading with no reference. `(none)` or absent leaves the answer to step 4b.
+   **A given `ISSUE_PR_LINK` is final.** When it is given, `(none)` included, it is the section's whole answer, whether the gate above admitted it or refused it: step 4b does not resolve a number or render a line. An admitted line goes under `## Related Issues` in the body this step creates; on an existing PR whose body has no `## Related Issues` section, step 4b's PR-host half publishes it. Only an absent `ISSUE_PR_LINK` goes to step 4b, and only when no admitted wave block exists. When `ISSUE_NUMBER` is set and no line is admitted, emit the heading with no reference and `TRACEABILITY: DEGRADED (ambiguous issue reference)`; when it is `(none)`, write no heading.
 
    **Pasting `PR_EXCEPTIONS`.** When `PR_EXCEPTIONS` is provided (not `(none)`), append it verbatim as the body's last section — it is scrubbed with the body. Re-check its shape first: its first line must be exactly `## Evidence Exceptions`, and every line after it must match this pattern as the WHOLE line:
 
@@ -82,16 +82,12 @@ Load when the resolved tracker provider is `linear` and the operation is `ensure
 
    **D11 scrub (PR body is a GitHub-visible sink):** Compose the final PR body to `$DEVFLOW_BODY_RAW` (`DEVFLOW_BODY_RAW="$(mktemp)"`); scrub via `node "$HOME/.devflow/scripts/redact-secrets.cjs" "$DEVFLOW_BODY_RAW" "$DEVFLOW_BODY"` (where `DEVFLOW_BODY="$(mktemp)"`). On success: create PR with `gh pr create … --body-file "$DEVFLOW_BODY"`. **On scrubber failure** (non-zero exit or script missing): still create the PR — PR existence is the deliverable — but with a minimal body containing only the task reference, plan path (if available), and issue link (if ISSUE_NUMBER provided), plus the literal line `TRACEABILITY: DEGRADED (redaction unavailable)`. Never post `$DEVFLOW_BODY_RAW`.
 
-4b. (ALWAYS-ON) Ensure the PR body contains a `## Related Issues` section naming the verified issue when one is known. A given `ISSUE_PR_LINK` is already decided in step 4a: skip the resolution and the rendering below. Resolution order:
-   a. Prefer the issue reference returned by `setup-task` / `ensure-traceable-issue` for this branch — it was verified at creation time.
-   b. Otherwise fall back to the branch name pattern `{type}/{REF}-{slug}`: extract the segment that, after ASCII-upper normalisation, satisfies `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` and verify it with the *fetch by key* capability. If the call fails, or the issue is not open, **skip silently** — never render a link for an unverified reference. A branch name can carry a token that merely looks like one, and the existence check is the guard.
-   c. The *fetch by key* capability absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for fetch by key)` and skip the section; the PR is never blocked on it.
-
-   Render the line through `## Reference Rendering`. **This provider's magic words are the SERVER's behaviour, not a capability this operation controls.** A reference rendered in a PR body may or may not transition or close the issue depending on how the workspace is configured, and on how the PR host and the tracker are connected — so the rendered text **never claims an effect**: closing is a `## Transitions` matter, and `gather-release-evidence` reports the absence of a closing-reference capability as `TRACEABILITY: DEGRADED (unsupported by linear)`. Promising an effect that may not happen is worse than rendering a plain reference that always does. `## Reference Rendering` absent, or its token discarded by the gate below ⇒ render the reference on its own line under the section heading, and record the discard under `### Substitutions`.
+4b. (ALWAYS-ON) Ensure the PR body contains a `## Related Issues` section with the `Refs {REF}-{n}` line of this branch's issue. A given `ISSUE_PR_LINK` is already decided in step 4a: skip the resolution below. Resolution: the only source is the `PR link line` of the `### Handoff Values` block that `setup-task` or `fetch-issue` returned for this branch. Publish it only if it passes step 4a's shape check. A line that fails the check is refused as step 4a refuses it, not repaired: emit `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match any tracker reference grammar)` and publish nothing. This step composes no line itself. Never compose a line from a bare issue number or a branch name. **This provider's magic words are the SERVER's behaviour, not a capability this operation controls.** A reference rendered in a PR body may or may not transition or close the issue depending on how the workspace is configured, and on how the PR host and the tracker are connected — so the rendered text **never claims an effect**: closing is a `## Transitions` matter, and `gather-release-evidence` reports the absence of a closing-reference capability as `TRACEABILITY: DEGRADED (unsupported by linear)`. Promising an effect that may not happen is worse than rendering a plain reference that always does.
 
    Publish the section through step 4b's PR-host half.
 
-   If no verified issue reference is discoverable, skip silently. A failure while updating the PR body emits `TRACEABILITY: DEGRADED ({reason})` and continues — a failed Related Issues update never blocks the PR.
+   If no such line exists, skip silently.
+   A failure while updating the PR body emits `TRACEABILITY: DEGRADED ({reason})` and continues — a failed Related Issues update never blocks the PR.
 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.
@@ -100,10 +96,6 @@ Load when the resolved tracker provider is `linear` and the operation is `ensure
 5. Get base branch from PR
 6. Derive branch-slug (replace `/` with `-`)
 
-**The read-site shape gate for `## Reference Rendering`.** The token arrives from the tracker configuration file, which is hand-editable and machine-wide, so it is parsed HERE — at the sink that renders it, and never on the writer's word. Require `^[A-Za-z0-9 #{}/_.-]{1,60}$`, anchored at both ends, and **discard** any token carrying a backtick, a `$`, a `"`, a `\`, a `;` or a newline. The anchored shape is the gate; the metachar denylist is a second, independent control, named separately so widening the shape for a new token form cannot silently relax it. **Discard, never repair** — a repaired token is one nobody can predict — and a discarded token falls back to **the resolved provider's** documented default, stated once in that provider's own mechanics, with a `### Substitutions` row recording what was dropped. An absent `## Reference Rendering` section, an absent file and a discarded token are the SAME outcome: the documented default. This gate never yields `# UNRESOLVED:`.
-
-**This provider's documented default is `Refs {REF}-{n}`.** It is stated here because it is a provider fact, and the gate above is what routes to it: a section that is absent, a file that is absent and a token the gate discarded all render this, and none of them is a degradation.
-
 ### Step 4b's PR-host half
 
 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"`.