devflow-kit 3.8.0 → 3.10.0

package/src/assets/mds/tracker/_jira.mds

@@ -67,6 +67,13 @@ column-0 `## ` line outside a fence terminates the section for every guard that
 reads it through `extractOpSectionFromCorpus`, and everything under it becomes
 invisible while the bytes stay on disk.
 
+A compliance arm (the `compliance:on`, `compliance:off` and `compliance:end` marker lines)
+opens and closes inside one define, so inside one operation's section. The compliance-off
+file keeps the off text: `setup-task` forwards no plan artifact, `create-release` composes
+no shipped-issues list, `ensure-traceable-issue` writes nothing to an existing issue, posts
+no artifact comment and has no `## Implementation Plan` section, and a kept operation never
+names an omitted reference.
+
 The comment-body cap is a PROVIDER FACT and is stated once, as `comment_cap()`
 below; every site that renders it invokes the define. It is not in `_mcp.mds`
 with the shared rules because it is not provider-independent — the CLI provider's
@@ -104,7 +111,11 @@ Load when the resolved tracker provider is `jira` and the operation is `setup-ta
 {{steps.base_branch_step()}}
 1. **`ISSUE_INPUT` pre-flight**, when provided: it is an existing issue key. {{common.ref_preflight_single("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`")}} Step 3 resolves an admitted key with *fetch by key*.
 {{common.conventions_step()}}
+<!-- compliance:on -->
 1c. Issue-first, only when `ISSUE_REQUIRED` is `true` and `ISSUE_INPUT` is absent: invoke `ensure-traceable-issue` with `TASK_DESCRIPTION` (and `PLAN_ARTIFACT_PATH` if provided) and capture the returned key for step 3's `{type}/{KEY}-{slug}`.
+<!-- compliance:off -->
+1c. Issue-first, only when `ISSUE_REQUIRED` is `true` and `ISSUE_INPUT` is absent: invoke `ensure-traceable-issue` with `TASK_DESCRIPTION` and capture the returned key for step 3's `{type}/{KEY}-{slug}`.
+<!-- compliance:end -->
    - Preconditions: the *create issue* and *fetch by key* capabilities are both available. Either one absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for {capability})` naming the capability, and continue to step 2. **The branch is still cut and the PR is still opened**, with the traceability field carrying `Tracked (pending)` and the reason. **NEVER create a GitHub issue as a fallback**.
 {{common.branch_detection_step()}}
    - The convention owns the branch **shape**, `## Reference Rendering` only the **token** in it; neither is the other's fallback.
@@ -177,10 +188,7 @@ Load when the resolved tracker provider is `jira` and the operation is `manage-d
 
 1. Find or create the rolling "Tech Debt Backlog" item. `## Tech Debt` defaults to a **single rolling item**, so this operation looks for exactly one: use the *search* capability once with a structured filter over the resolved project and the tech-debt label. Absent ⇒ create it with the *create issue* capability, using only the field names `## Required Fields` allows.
 2. Check the item's description length against the `{{comment_cap()}}`-character cap; archive when it is over.
-3. Extract items to add:
-   - `## Fix Separately` entries from `{REVIEW_DIR}/resolution-summary.md` (FIX_SEPARATE from Triage agent)
-   - `## Deferred to Tech Debt` entries from `{REVIEW_DIR}/resolution-summary.md` (TECH_DEBT from Triage agent)
-   - Pre-existing issues (Category 3) from review reports
+{{opsteps.manage_debt_step_3()}}
 4. Deduplicate against existing items using semantic matching.
 5. Remove items that have been fixed (verify in codebase).
 6. Compose the updated description and post it through the gate in `### Posting gate` below, using the *update description* capability.
@@ -207,11 +215,16 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 
 Load when the resolved tracker provider is `jira` and the operation is `create-release`.
 
+<!-- compliance:on -->
 **Mechanics held here:** the release-host steps 1a–6 — version check, annotated tag, tag push, notes composition, the D11 scrub and the release itself — and this provider's shipped-issues step inside step 5. The release-host steps are release-host mechanics, not tracker mechanics, and are the same under every provider.
+<!-- compliance:off -->
+**Mechanics held here:** the release-host steps 1a–6 — version check, annotated tag, tag push, notes composition, the D11 scrub and the release itself. The release-host steps are release-host mechanics, not tracker mechanics, and are the same under every provider.
+<!-- compliance:end -->
 
 ### Process
 
 {{opsteps.create_release_steps()}}
+<!-- compliance:on -->
 
 Inside step 5 (compose release notes):
 
@@ -222,6 +235,7 @@ Inside step 5 (compose release notes):
 {{mcp.reference_rendering_gate()}}
 
 **This provider's documented default is `{{pr_link_default()}}`.** 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.
+<!-- compliance:end -->
 @end
 
 @define gather_release_evidence():
@@ -245,7 +259,11 @@ Load when the resolved tracker provider is `jira` and the operation is `gather-r
    - {{common.ref_preflight_list("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`", "", "", ".")}}
    - Confirm the survivors exist with **one** call to the *batch fetch* capability over the whole set, bounded `≤50` with `TRUNCATED ({n} not processed)` for the remainder — **one query, never a per-item loop**.
    - **Because the closing-reference step degraded, the enrichment is incomplete by construction: never report the status as `COMPLETE`.** Report `PARTIAL ({n} DEGRADED)` whenever any step above degraded, and `TRUNCATED ({n} not processed)` whenever the bound was reached. A release that reads `COMPLETE` over an unresolvable evidence set is the one report nobody re-checks.
+<!-- compliance:on -->
    - On a tool error for an individual item → DEGRADED for that item, continue. On backpressure → follow `### Provider signals (Jira)` in this operation's `backlink-shipped-issues` reference, which is where this provider's one signal is stated.
+<!-- compliance:off -->
+   - On a tool error for an individual item → DEGRADED for that item, continue. On backpressure — this provider's one signal is a `Retry-After` value on a 429, reported and never slept on — stop the enrichment and report the remaining items as `THROTTLED`; there is no earlier rung.
+<!-- compliance:end -->
 {{steps.release_evidence_gate_step()}}
 {{common.trace_map_step("--grammar jira --key {KEY}", "`{KEY}` is the resolved project key; with none usable, skip the run and take the arm below. ")}}
 @end
@@ -334,21 +352,30 @@ Load when the resolved tracker provider is `jira` and the operation is `associat
 
 Load when the resolved tracker provider is `jira` and the operation is `ensure-traceable-issue`.
 
+<!-- compliance:on -->
 **Mechanics held here:** the `### Process` body — issue creation, and how the design artifact is attached on a provider whose comment format has no collapsed-block analogue.
+<!-- compliance:off -->
+**Mechanics held here:** the `### Process` body — issue creation.
+<!-- compliance:end -->
 
 {{common.traceable_issue_rules()}}
 
 ### Process
 
 1. If `ISSUE_INPUT` is provided — an issue key, or free prose to resolve through the *search* capability with a structured filter:
+<!-- compliance:on -->
    - Compose a structured comment using the D3 sections and post it through `### Posting gate` below. **NEVER rewrite the issue description** — an existing description is somebody's work.
    - If `PLAN_ARTIFACT_PATH` is provided: **the artifact is NOT inlined.** See `### The artifact is posted as content`.
+<!-- compliance:off -->
+   - Write nothing to the issue: no comment and no edit. **NEVER rewrite the issue description** — an existing description is somebody's work.
+<!-- compliance:end -->
    - Return the issue key.
 2. If no `ISSUE_INPUT`: create a new issue through the *create issue* capability.
    - Summary: derived from `TASK_DESCRIPTION` (same slug logic as `setup-task`).
    - Fields: only the names `## Required Fields` allows, and the issue type by exact match against the types enumerated this run. The capability absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for create issue)` and return without an issue key; the caller proceeds with `Tracked (pending)` and the reason, and **never creates a GitHub issue instead**.
    - **Description** — composed from the D3 template and posted through `### Posting gate` below. `TASK_DESCRIPTION`, `INITIAL_REQUEST` and `REQUIREMENTS` are caller-supplied and untrusted — they reach the call as values, never as part of a query or a command.
 3. Return the issue key.
+<!-- compliance:on -->
 
 ### The artifact is posted as content
 
@@ -357,18 +384,31 @@ This provider's comment format has **no HTML-comment node and no collapsed-block
 Measure the composed body against the `{{comment_cap()}}`-character cap **after redaction** — the scrubber's tokens can grow it. Over the cap, post **none of the plan**: post the pointer sentence alone — `Implementation plan: {PLAN_ARTIFACT_PATH} (not committed; ask the author)` — and emit `TRACEABILITY: DEGRADED (plan artifact exceeds comment cap)`. A truncated plan is worse than a pointer, because the reader cannot tell which half is missing.
 
 Over the `{{comment_cap()}}`-character cap after redaction, truncate in **preservation order** — line 1 the marker, then the status and DEGRADED lines, then the pointer sentence; the untrusted middle is what gets cut — and end with `NOTE: body exceeded the {{comment_cap()}}-character cap after redaction — truncated/stub posted`. The pointer sentence is the last thing to go because it is the only line that still leads somewhere.
+<!-- compliance:off -->
+
+Over the `{{comment_cap()}}`-character cap after redaction, truncate any body this operation posts in **preservation order** — the status and DEGRADED lines are kept; the untrusted middle is what gets cut — and end with `NOTE: body exceeded the {{comment_cap()}}-character cap after redaction — truncated/stub posted`.
+<!-- compliance:end -->
 
 {{mcp.query_safety()}}
 
 {{mcp.posting_gate_head("every write below")}}
+<!-- compliance:on -->
 4. Post through the *add comment* capability with arguments (issue key, body: {SCRUBBED_BODY}), or on a new issue through the *create issue* capability with the description field carrying the same gated value.
+<!-- compliance:off -->
+4. Create the issue through the *create issue* capability with the description field carrying the gated value.
+<!-- compliance:end -->
 
 ### Traceability Issue Template (D3)
 
 The D3 section headings are the canonical ones; only the transport differs from the GitHub path. Rules:
 
+<!-- compliance:on -->
 - Pre-existing issues: post a structured comment using the D3 sections — NEVER rewrite the issue description.
 - New issues: create with the D3 description, then post the artifact as its own comment and reference it from the `## Implementation Plan` section.
+<!-- compliance:off -->
+- Pre-existing issues: write nothing to them, no comment and no edit — NEVER rewrite the issue description.
+- New issues: create with the D3 description.
+<!-- compliance:end -->
 @end
 
 @define post_wave_report():

package/src/assets/mds/tracker/_linear.mds

@@ -69,6 +69,13 @@ invisible while the bytes stay on disk. The one `## ` heading in this
 file is the module-level section below, which sits above every section marker and
 is therefore emitted nowhere.
 
+A compliance arm (the `compliance:on`, `compliance:off` and `compliance:end` marker lines)
+opens and closes inside one define, so inside one operation's section. The compliance-off
+file keeps the off text: `setup-task` forwards no plan artifact, `create-release` composes
+no shipped-issues list, `ensure-traceable-issue` writes nothing to an existing issue, posts
+no artifact comment and has no `## Implementation Plan` section, and a kept operation never
+names an omitted reference.
+
 ## Known Unknowns
 
 <!-- twin: docs/cli-reference.md § Known Unknowns — Linear -->
@@ -141,7 +148,11 @@ Load when the resolved tracker provider is `linear` and the operation is `setup-
 {{steps.base_branch_step()}}
 1. **`ISSUE_INPUT` pre-flight**, when provided: it is an existing issue reference. {{common.ref_preflight_single("linear", "**either** anchored form — the team-key form `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` or the internal-id form `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$`", "**ASCII-upper-normalise it first** — a reference copied out of a branch name or a URL arrives lowercased. ", ", never joined into one alternation")}} Step 3 resolves an admitted reference with *fetch by key*.
 {{common.conventions_step()}}
+<!-- compliance:on -->
 1c. Issue-first, only when `ISSUE_REQUIRED` is `true` and `ISSUE_INPUT` is absent: invoke `ensure-traceable-issue` with `TASK_DESCRIPTION` (and `PLAN_ARTIFACT_PATH` if provided) and capture the returned reference for step 3's `{type}/{REF}-{slug}`.
+<!-- compliance:off -->
+1c. Issue-first, only when `ISSUE_REQUIRED` is `true` and `ISSUE_INPUT` is absent: invoke `ensure-traceable-issue` with `TASK_DESCRIPTION` and capture the returned reference for step 3's `{type}/{REF}-{slug}`.
+<!-- compliance:end -->
    - Preconditions: the *create issue* and *fetch by key* capabilities are both available. Either one absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for {capability})` naming the capability, and continue to step 2. **The branch is still cut and the PR is still opened**, with the traceability field carrying `Tracked (pending)` and the reason. **NEVER create a GitHub issue as a fallback**.
 {{common.branch_detection_step()}}
    - The convention owns the branch **shape**, `## Reference Rendering` only the **token** in it; neither is the other's fallback.
@@ -215,10 +226,7 @@ Load when the resolved tracker provider is `linear` and the operation is `manage
 
 1. Find or create the rolling "Tech Debt Backlog" item. `## Tech Debt` defaults to a **single rolling item**, so this operation looks for exactly one: use the *search* capability once with a structured filter over the resolved team and the tech-debt label. Absent ⇒ create it with the *create issue* capability, using only the field names `## Required Fields` allows.
 2. Check the item's description length against the `{{comment_cap()}}`-character cap; archive when it is over.
-3. Extract items to add:
-   - `## Fix Separately` entries from `{REVIEW_DIR}/resolution-summary.md` (FIX_SEPARATE from Triage agent)
-   - `## Deferred to Tech Debt` entries from `{REVIEW_DIR}/resolution-summary.md` (TECH_DEBT from Triage agent)
-   - Pre-existing issues (Category 3) from review reports
+{{opsteps.manage_debt_step_3()}}
 4. Deduplicate against existing items using semantic matching.
 5. Remove items that have been fixed (verify in codebase).
 6. Compose the updated description and post it through the gate in `### Posting gate` below, using the *update description* capability.
@@ -245,11 +253,16 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 
 Load when the resolved tracker provider is `linear` and the operation is `create-release`.
 
+<!-- compliance:on -->
 **Mechanics held here:** the release-host steps 1a–6 — version check, annotated tag, tag push, notes composition, the D11 scrub and the release itself — and this provider's shipped-issues step inside step 5. The release-host steps are release-host mechanics, not tracker mechanics, and are the same under every provider.
+<!-- compliance:off -->
+**Mechanics held here:** the release-host steps 1a–6 — version check, annotated tag, tag push, notes composition, the D11 scrub and the release itself. The release-host steps are release-host mechanics, not tracker mechanics, and are the same under every provider.
+<!-- compliance:end -->
 
 ### Process
 
 {{opsteps.create_release_steps()}}
+<!-- compliance:on -->
 
 Inside step 5 (compose release notes):
 
@@ -260,6 +273,7 @@ Inside step 5 (compose release notes):
 {{mcp.reference_rendering_gate()}}
 
 **This provider's documented default is `{{pr_link_default()}}`.** 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.
+<!-- compliance:end -->
 @end
 
 @define gather_release_evidence():
@@ -283,7 +297,11 @@ Load when the resolved tracker provider is `linear` and the operation is `gather
    - {{common.ref_preflight_list("linear", "**either** anchored form — the team-key form `^[A-Z][A-Z0-9]{0,9}-[1-9][0-9]{0,8}$` or the internal-id form `^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$`", "**ASCII-upper-normalise every entry first.** ", ", never joined into one alternation", ".")}}
    - Confirm the survivors exist with **one** call to the *batch fetch* capability over the whole set, bounded `≤50` with `TRUNCATED ({n} not processed)` for the remainder — **one query, never a per-item loop**.
    - **Because the closing-reference step degraded, the enrichment is incomplete by construction: never report the status as `COMPLETE`.** Report `PARTIAL ({n} DEGRADED)` whenever any step above degraded, and `TRUNCATED ({n} not processed)` whenever the bound was reached. A release that reads `COMPLETE` over an unresolvable evidence set is the one report nobody re-checks.
+<!-- compliance:on -->
    - On a tool error for an individual item → DEGRADED for that item, continue. On backpressure → follow `### Provider signals (Linear)` in this operation's `backlink-shipped-issues` reference, which is where this provider's one signal is stated.
+<!-- compliance:off -->
+   - On a tool error for an individual item → DEGRADED for that item, continue. On backpressure — this provider's one signal is an HTTP `400` carrying `RATELIMITED`, which a tool call surfaces as error text, not as a 429 — stop the enrichment and report the remaining items as `THROTTLED`; there is no earlier rung.
+<!-- compliance:end -->
 {{steps.release_evidence_gate_step()}}
 {{common.trace_map_step("--grammar linear --key {KEY}", "`{KEY}` is the resolved team key; with none usable, skip the run and take the arm below. ")}}
 @end
@@ -376,21 +394,30 @@ Load when the resolved tracker provider is `linear` and the operation is `associ
 
 Load when the resolved tracker provider is `linear` and the operation is `ensure-traceable-issue`.
 
+<!-- compliance:on -->
 **Mechanics held here:** the `### Process` body — issue creation, and how the design artifact is attached on a provider whose comment format has no collapsed-block analogue.
+<!-- compliance:off -->
+**Mechanics held here:** the `### Process` body — issue creation.
+<!-- compliance:end -->
 
 {{common.traceable_issue_rules()}}
 
 ### Process
 
 1. If `ISSUE_INPUT` is provided — an issue reference, or free prose to resolve through the *search* capability with a structured filter:
+<!-- compliance:on -->
    - Compose a structured comment using the D3 sections and post it through `### Posting gate` below. **NEVER rewrite the issue description** — an existing description is somebody's work.
    - If `PLAN_ARTIFACT_PATH` is provided: **the artifact is NOT inlined.** See `### The artifact is posted as content`.
+<!-- compliance:off -->
+   - Write nothing to the issue: no comment and no edit. **NEVER rewrite the issue description** — an existing description is somebody's work.
+<!-- compliance:end -->
    - Return the issue reference.
 2. If no `ISSUE_INPUT`: create a new issue through the *create issue* capability.
    - Title: derived from `TASK_DESCRIPTION` (same slug logic as `setup-task`).
    - Fields: only the names `## Required Fields` allows, and the issue type by exact match against the types enumerated this run. The capability absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for create issue)` and return without a reference; the caller proceeds with `Tracked (pending)` and the reason, and **never creates a GitHub issue instead**.
    - **Description** — composed from the D3 template and posted through `### Posting gate` below. `TASK_DESCRIPTION`, `INITIAL_REQUEST` and `REQUIREMENTS` are caller-supplied and untrusted — they reach the call as values, never as part of a query or a command.
 3. Return the issue reference.
+<!-- compliance:on -->
 
 ### The artifact is posted as content
 
@@ -399,18 +426,31 @@ This provider's comment format has **no HTML-comment node and no collapsed-block
 Measure the composed body against the `{{comment_cap()}}`-character cap **after redaction** — the scrubber's tokens can grow it. Over the cap, post **none of the plan**: post the pointer sentence alone — `Implementation plan: {PLAN_ARTIFACT_PATH} (not committed; ask the author)` — and emit `TRACEABILITY: DEGRADED (plan artifact exceeds comment cap)`. A truncated plan is worse than a pointer, because the reader cannot tell which half is missing.
 
 Over the `{{comment_cap()}}`-character cap after redaction, truncate in **preservation order** — line 1 the marker, then the status and DEGRADED lines, then the pointer sentence; the untrusted middle is what gets cut — and end with `NOTE: body exceeded the {{comment_cap()}}-character cap after redaction — truncated/stub posted`. The pointer sentence is the last thing to go because it is the only line that still leads somewhere.
+<!-- compliance:off -->
+
+Over the `{{comment_cap()}}`-character cap after redaction, truncate any body this operation posts in **preservation order** — the status and DEGRADED lines are kept; the untrusted middle is what gets cut — and end with `NOTE: body exceeded the {{comment_cap()}}-character cap after redaction — truncated/stub posted`.
+<!-- compliance:end -->
 
 {{mcp.query_safety()}}
 
 {{mcp.posting_gate_head("every write below")}}
+<!-- compliance:on -->
 4. Post through the *add comment* capability with arguments (issue reference, body: {SCRUBBED_BODY}), or on a new issue through the *create issue* capability with the description field carrying the same gated value.
+<!-- compliance:off -->
+4. Create the issue through the *create issue* capability with the description field carrying the gated value.
+<!-- compliance:end -->
 
 ### Traceability Issue Template (D3)
 
 The D3 section headings are the canonical ones; only the transport differs from the GitHub path. Rules:
 
+<!-- compliance:on -->
 - Pre-existing issues: post a structured comment using the D3 sections — NEVER rewrite the issue description.
 - New issues: create with the D3 description, then post the artifact as its own comment and reference it from the `## Implementation Plan` section.
+<!-- compliance:off -->
+- Pre-existing issues: write nothing to them, no comment and no edit — NEVER rewrite the issue description.
+- New issues: create with the D3 description.
+<!-- compliance:end -->
 @end
 
 @define post_wave_report():

package/src/assets/rules/quality.md

@@ -6,10 +6,12 @@ paths: []
 **Match existing patterns — consistency beats cleverness.**
 
 - Single responsibility: one reason to change per module
+- Find the existing owner: extend it when new code shares its job, never add a parallel copy; a trust-boundary or fail-closed check is not a copy
 - No regressions: every change must pass existing tests
 - Behavior-focused tests: assert outcomes, not implementation details
 - If you can't explain it in 5 minutes, it's too complex — simplify first
 - Delete dead code — commented-out code is not version control
 - Leave the end-state, not the transition — after removing or renaming, strip the residue: tombstone comments ("no longer does X"), `*_old`/`v2` names, guards for now-impossible states, leftover migration scaffolding. Git holds the history.
+- When a change alters a name, path or behavior, update the current tracked docs that state the old fact, not released changelog entries; for a security fix, state the effect only
 - Cut leftover debug statements, unused imports, unnecessary variables used once right after assignment, nested ternaries; cut checks the types enforce and catches around code that cannot throw, never at a trust boundary or fail-closed path
 - Zero warnings policy — treat all compiler and linter warnings as errors