devflow-kit 3.3.0 → 3.5.0

package/src/assets/mds/tracker/_github.mds

@@ -2,6 +2,9 @@
 output-dir: dist/skills/git/references
 ---
 @import "./_common.mds" as common
+@import "./_steps.mds" as steps
+@import "../git/_ops.mds" as ops
+@import "../git/_ops_steps.mds" as opsteps
 
 GitHub tracker mechanics for the `devflow:git` skill.
 
@@ -18,18 +21,23 @@ moving with it. Define-set parity — one `@define` per op, named identically
 across modules — is what the `cross-provider define-set parity` scan asserts
 over all three, because a define name is visible to no type.
 
-Each section states what the Git agent loads it for. An operation's contract —
-its `**Input:**`, its `**Output:**` template and its `**Degradation (D4):**`
-clause — is never restated here: that is the agent's, and a second copy outside
-the single-authority corpus is the divergence this split exists to prevent.
+Each section is the WHOLE operation, and a spawn reads nothing else for it
+(D-OP-ONE-REF): the operation's contract (description, `**Input:**`, degradation
+notes, `**Output:**` template) comes first, called from `_ops.mds` once for every
+module that emits the operation (D-OP-CONTRACT-ONCE), and the provider's
+mechanics follow it (D-OP-MOVABLE). `_ops.mds` and `_ops_steps.mds` are two more
+ALIAS imports (`as ops`, `as opsteps`); the second holds the inline steps every
+provider runs identically, which each section places at the position its step
+number gives it.
 
 Headings below each section's own anchor are `###` by grammar, not by taste: a
 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.
 
-`_common.mds` is an ALIAS import (`as common`), as in the other two provider
-modules. A SELECTIVE import deep-copies each named function into every `@define`
+`_common.mds` and `_steps.mds` are ALIAS imports (`as common`, `as steps`), as in the
+other two provider modules; `_steps.mds` holds the provider-neutral step text of the
+tracker operations (D-NEUTRAL-STEP-MOVE). A SELECTIVE import deep-copies each named function into every `@define`
 here: with four names selected this module measured ~320 ms against ~10 ms
 aliased. An alias changes lookup, not expansion — the emitted bytes are
 identical — and `tests/build-mds-compile-time.test.ts` holds the budget.
@@ -37,12 +45,15 @@ identical — and `tests/build-mds-compile-time.test.ts` holds the budget.
 @define setup_task():
 ## Operation: setup-task
 
+{{ops.setup_task_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `setup-task`.
 
-**Mechanics held here:** the `**Process:**` steps that talk to GitHub — issue lookup, branch-token rendering, and the conventions probe.
+**Mechanics held here:** the `### Process` steps that talk to GitHub — issue lookup, branch-token rendering, and the conventions probe.
 
 ### Process
 
+{{steps.base_branch_step()}}
 1. **`ISSUE_INPUT` pre-flight**, when provided: it must satisfy `^#?[1-9][0-9]{0,8}$`, anchored at both ends; strip one leading `#` — the digits are the issue number steps 1c and 3 use. Anything else ⇒ `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match github reference grammar)`, and the task proceeds with no issue.
 {{common.conventions_step()}}
 1c. Issue-first, only when `ISSUE_REQUIRED` is `true`: before branch derivation, ensure a GitHub issue exists for this task:
@@ -58,6 +69,7 @@ Load when the resolved tracker provider is `github` and the operation is `setup-
      - Before placing fetched content in the output, neutralise any `</untrusted-issue-body>` in it (Principle 8 marker neutralisation).
    - If `TASK_DESCRIPTION` provided (no issue): infer type from description keywords (e.g., "fix login bug" → `fix`, "refactor auth" → `refactor`, "add JWT" → `feature`, "update docs" → `docs`, "chore: cleanup" → `chore`), then slugify description as `{type}/{slug}` (max 40 chars)
    - If neither: fallback to `task-{YYYY-MM-DD_HHMM}`
+{{steps.branch_create_steps()}}
 
 {{common.handoff_values("`{n}` (bare, never `#{n}`)", "Closes #{n}")}}
 @end
@@ -65,16 +77,21 @@ Load when the resolved tracker provider is `github` and the operation is `setup-
 @define fetch_issue():
 ## Operation: fetch-issue
 
+{{ops.fetch_issue_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `fetch-issue`.
 
-**Mechanics held here:** the `**Process:**` body — single-issue lookup and the field projection it requests.
+**Mechanics held here:** the `### Process` body — single-issue lookup and the field projection it requests.
 
 ### Process
 
+{{opsteps.fetch_issue_step_1()}}
 1b. **Ref pre-flight.** The numeric path is taken only when `ISSUE_INPUT` satisfies `^#?[1-9][0-9]{0,8}$` — this provider's anchored reference grammar, stated with its strip-one-leading-`#` normalisation and the shell-comment reason it exists for in this operation's sibling `backlink-shipped-issues` reference. Interpolate only the digits that survive the strip. Anything the grammar rejects is a SEARCH TERM and takes the text path, so it never reaches a command.
 2. Fetch full issue data (title, body, labels, assignees, milestone, comments)
 3. Extract acceptance criteria and dependencies from body; neutralise any `</untrusted-issue-body>` in the body before wrapping (Principle 8 marker neutralisation).
 
+{{steps.fetch_issue_neutralise()}}
+
 {{common.handoff_values("`{n}` (bare, never `#{n}`)", "Closes #{n}")}}
 
 ### Fetch Issue with All Details
@@ -100,12 +117,15 @@ DEPENDS_ON=$(echo "$BODY" | grep -oE '(depends on|blocked by) #[0-9]+' | grep -o
 @define fetch_issues_batch():
 ## Operation: fetch-issues-batch
 
+{{ops.fetch_issues_batch_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `fetch-issues-batch`.
 
-**Mechanics held here:** the `**Process:**` body — the single bounded batch query and the reporting of references it could not resolve.
+**Mechanics held here:** the `### Process` body — the single bounded batch query and the reporting of references it could not resolve.
 
 ### Process
 
+{{opsteps.fetch_issues_batch_step_1()}}
 2. Fetch all issues in a **single** GraphQL query using per-issue aliases (dynamically constructed for the resolved list); resolve owner/repo from the git remote context:
    ```
    gh api graphql -f query='query { repository(owner:"OWNER", name:"REPO") {
@@ -115,14 +135,18 @@ Load when the resolved tracker provider is `github` and the operation is `fetch-
    }}'
    ```
 {{common.state_batch_line("`state` (`OPEN` or `CLOSED`)", "`state`", "{ISSUE_REF}")}}
+{{steps.batch_extract_steps()}}
+{{opsteps.fetch_issues_batch_step_5()}}
 @end
 
 @define manage_debt():
 ## Operation: manage-debt
 
+{{ops.manage_debt_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `manage-debt`.
 
-**Mechanics held here:** the `**Process:**` body — locating the rolling tech-debt item, creating it when absent, and updating its description.
+**Mechanics held here:** the `### Process` body — locating the rolling tech-debt item, creating it when absent, and updating its description.
 
 ### Process
 
@@ -224,12 +248,16 @@ This issue reached the size limit.
 @define create_release():
 ## Operation: create-release
 
+{{ops.create_release_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `create-release`.
 
-**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation.
+**Mechanics held here:** the release-host steps 1a–6 — version check, annotated tag, tag push, notes composition, the D11 scrub and the release itself — which are the same under every provider, and this provider's shipped-issues step inside step 5.
 
 ### Process
 
+{{opsteps.create_release_steps()}}
+
 Inside step 5 (compose release notes):
 
    - If `SHIPPED_ISSUES` provided: append a `## Shipped Issues` section with issue references — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails)
@@ -238,13 +266,17 @@ Inside step 5 (compose release notes):
 @define gather_release_evidence():
 ## Operation: gather-release-evidence
 
+{{ops.gather_release_evidence_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `gather-release-evidence`.
 
 **Mechanics held here:** the last release tag, the closing-keyword rule, this provider's history grammar, resolving which issues the range's merged PRs close — one listing, with its bounded fallback — and the trace map.
 
 ### Process
 
+{{steps.release_evidence_tag_step()}}
 {{common.last_release_tag_step()}}
+{{steps.release_evidence_range_steps()}}
 {{common.closing_keyword_rule()}}
 3b. **This provider's history grammar** is `^#[1-9][0-9]{0,8}$`. A bare number is not a reference here either: a keyword-anchored candidate must carry the `#`, and step 4 renders every number it reads from a merged PR as `#{n}` before step 5's gate.
 4. If `gh` is authenticated and remote is reachable, resolve which issues the range's merged PRs close — **one listing, never one call per commit** — and merge the result with the commit-message set:
@@ -254,15 +286,18 @@ Load when the resolved tracker provider is `github` and the operation is `gather
    - **Coverage:** a range subject carries a PR marker (`(#N)` or `Merge pull request #N`) but no listed PR maps into the range ⇒ `TRACEABILITY: DEGRADED (merged-PR listing did not cover the range)`. A listing of exactly 200 ⇒ status `INDETERMINATE (merged-PR listing hit its 200 cap)`, returning what was collected.
    - **The listing fails** (an older `gh` reports `Unknown JSON field`) ⇒ `TRACEABILITY: DEGRADED ({reason})`, then fall back to `gh pr view N --json closingIssuesReferences` over the PR numbers in `(#N)` / `Merge pull request #N` subjects — after a listing that succeeds, also over each range `(#N)` naming no listed PR — each N gated `^[1-9][0-9]{0,8}$`, filtered and rendered as above, bounded at ≤25 PRs; report the remainder as `THROTTLED ({n} not processed)` and never report the enrichment as complete while PRs went unresolved.
    - On any 4xx → DEGRADED for that item, continue. On 5xx → 1 retry; still 5xx → DEGRADED for that item, continue. On the secondary rate limit of `### Provider signals (GitHub)` in this operation's `backlink-shipped-issues` reference → stop GitHub enrichment immediately, report remaining as `THROTTLED`.
+{{steps.release_evidence_gate_step()}}
 {{common.trace_map_step("--grammar github --traced-file \"$T\"", "In one shell: `trap 'rm -- \"$T\"' EXIT; T=\"$(mktemp)\"`, then one 40-hex SHA per line into `$T` — each range commit step 4 tied to a PR with ≥1 kept reference (its `mergeCommit.oid`, or a subject naming it). ")}}
 @end
 
 @define backlink_shipped_issues():
 ## Operation: backlink-shipped-issues
 
+{{ops.backlink_shipped_issues_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `backlink-shipped-issues`.
 
-**Mechanics held here:** the `**Process:**` body — the hoisted current-user lookup, the back-link post, and the inter-item throttle — and, because this is the tracker operation that owns the fan-out, GitHub's rate-limit and posting signals for the always-loaded D4 and D11 contracts.
+**Mechanics held here:** the `### Process` body — the hoisted current-user lookup, the back-link post, and the inter-item throttle — and, because this is the tracker operation that owns the fan-out, GitHub's rate-limit and posting signals for the always-loaded D4 and D11 contracts.
 
 ### Provider signals (GitHub)
 
@@ -282,10 +317,14 @@ node "$HOME/.devflow/scripts/redact-secrets.cjs" "$DEVFLOW_BODY_RAW" "$DEVFLOW_B
 
 ### Process
 
+{{opsteps.shipped_issues_step_0()}}
+
 **Ref pre-flight (the always-loaded entry gate, instantiated for this provider).** Every entry of `SHIPPED_ISSUES` must satisfy `^#?[1-9][0-9]{0,8}$`, anchored at both ends of the STRING (a newline fails it) — this provider's reference grammar is what the entry gate's shape requirement means here, and the anchored form is what keeps a reference out of the commands below. **Then normalise once, before the loop, never inside it:** strip **exactly one** leading `#` from every admitted entry (`#42` ≡ `42`) and interpolate only the stripped digits. The grammar admits both spellings because both are how a reference is written here, but a `#` at word start opens a shell comment — an un-stripped `#42` would truncate `gh issue view`, `gh issue comment` and every other command below at the reference, so the stripped form is the only one that reaches a command. **Drop** every entry that fails and report it as `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match github reference grammar)`. If every entry is dropped, emit `TRACEABILITY: DEGRADED (no parseable refs for provider {p})`, post nothing, and **never report the status as `COMPLETE`**.
 
 **Setup (once, before the loop):** Fetch viewer login: `gh api user --jq '.login'` → store as VIEWER_LOGIN
 
+{{opsteps.shipped_issues_loop()}}
+
 Then, per issue, within the operation's ≤50 bound:
 
 1. Fetch existing comments authored by the viewer: `gh issue view {number} --json comments --jq '[.comments[] | select(.author.login == "'"$VIEWER_LOGIN"'")] | .[].body'`
@@ -303,12 +342,18 @@ Then, per issue, within the operation's ≤50 bound:
 @define associate_release():
 ## Operation: associate-release
 
+{{ops.associate_release_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `associate-release`.
 
 **Mechanics held here:** the release milestone — created first, else found by a bounded walk — then one batched read and one batched assignment that never replaces a milestone.
 
 ### Process
 
+{{opsteps.shipped_issues_step_0()}}
+
+{{opsteps.associate_release_marker_step()}}
+
 **Ref pre-flight (the always-loaded entry gate, instantiated for this provider).** Every entry of `SHIPPED_ISSUES` must satisfy `^#?[1-9][0-9]{0,8}$`, anchored at both ends of the STRING; strip exactly one leading `#` once, and interpolate only the digits. Drop each failure as `TRACEABILITY: DEGRADED (issue reference "{ref}" does not match github reference grammar)`. Every entry dropped ⇒ `TRACEABILITY: DEGRADED (no parseable refs for provider {p})`, no call, and **never report the status as `COMPLETE`**.
 
 Steps 1, 3 and 4 each run in ONE shell that opens with `trap 'rm -- "$F"' EXIT; F="$(mktemp)"`.
@@ -324,9 +369,11 @@ Steps 1, 3 and 4 each run in ONE shell that opens with `trap 'rm -- "$F"' EXIT;
 @define ensure_traceable_issue():
 ## Operation: ensure-traceable-issue
 
+{{ops.ensure_traceable_issue_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `ensure-traceable-issue`.
 
-**Mechanics held here:** the `**Process:**` body — issue creation, and posting the design artifact as a collapsed comment; and the D3 issue template below, whose section headings are GitHub's Markdown, not every tracker's.
+**Mechanics held here:** the `### Process` body — issue creation, and posting the design artifact as a collapsed comment; and the D3 issue template below, whose section headings are GitHub's Markdown, not every tracker's.
 
 {{common.traceable_issue_rules()}}
 
@@ -396,9 +443,11 @@ When creating or enriching a GitHub issue via the `ensure-traceable-issue` opera
 @define post_wave_report():
 ## Operation: post-wave-report
 
+{{ops.post_wave_report_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `post-wave-report`.
 
-**Mechanics held here:** the `**Process:**` body — locating the wave's tracking item and posting or updating the report.
+**Mechanics held here:** the `### Process` body — locating the wave's tracking item and posting or updating the report.
 
 {{common.wave_report_inputs()}}
 
@@ -409,6 +458,7 @@ Load when the resolved tracker provider is `github` and the operation is `post-w
    - `gh issue view {TRACKING_ISSUE} --json comments --jq '[.comments[] | select(.author.login == "'"$VIEWER_LOGIN"'")] | .[].body'`
    - Search for `<!-- devflow:wave-report wave:{WAVE_ID} -->` in viewer-authored comment bodies only
    - If found: skip — report `Skipped: wave report for {WAVE_ID} already posted`
+{{steps.wave_report_read_step()}}
 3. Compose the comment body:
    ```markdown
    <!-- devflow:wave-report wave:{WAVE_ID} -->
@@ -422,13 +472,17 @@ Load when the resolved tracker provider is `github` and the operation is `post-w
 @define ensure_pr_ready():
 ## Operation: ensure-pr-ready
 
+{{ops.ensure_pr_ready_contract()}}
+
 Load when the resolved tracker provider is `github` and the operation is `ensure-pr-ready`.
 
-**Mechanics held here:** step 4b's TRACKER half only — the issue-number resolution and its `Closes #{n}` line; every other step is in `references/pr/ensure-pr-ready.md`.
+**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.
 
 ### Process
 
-4b. (ALWAYS-ON) Ensure PR body contains a `## Related Issues` section with `Closes #{n}` link when a verified issue number is known. Resolution order:
+{{opsteps.ensure_pr_ready_steps_to_4a()}}
+
+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.
 
@@ -436,6 +490,9 @@ Load when the resolved tracker provider is `github` and the operation is `ensure
 
    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.
+{{opsteps.ensure_pr_ready_steps_from_4c()}}
+
+{{opsteps.ensure_pr_ready_pr_edit()}}
 @end
 
 <!-- op: setup-task -->

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

@@ -3,6 +3,9 @@ output-dir: dist/skills/git/references
 ---
 @import "./_mcp.mds" as mcp
 @import "./_common.mds" as common
+@import "./_steps.mds" as steps
+@import "../git/_ops.mds" as ops
+@import "../git/_ops_steps.mds" as opsteps
 
 Jira tracker mechanics for the `devflow:git` skill.
 
@@ -19,10 +22,14 @@ Define-set parity — one `@define` per op, named identically across modules —
 what the `cross-provider define-set parity` scan asserts over all three,
 because a define name is visible to no type.
 
-Each section states what the Git agent loads it for. An operation's contract —
-its `**Input:**`, its `**Output:**` template and its `**Degradation (D4):**`
-clause — is never restated here: that is the agent's, and a second copy outside
-the single-authority corpus is the divergence this split exists to prevent.
+Each section is the WHOLE operation, and a spawn reads nothing else for it
+(D-OP-ONE-REF): the operation's contract (description, `**Input:**`, degradation
+notes, `**Output:**` template) comes first, called from `_ops.mds` once for every
+module that emits the operation (D-OP-CONTRACT-ONCE), and the provider's
+mechanics follow it (D-OP-MOVABLE). `_ops.mds` and `_ops_steps.mds` are two more
+ALIAS imports (`as ops`, `as opsteps`); the second holds the inline steps every
+provider runs identically, which each section places at the position its step
+number gives it.
 
 The provider-independent rules the sections below carry are IMPORTED rather than
 written here: `posting_gate_head`, `query_safety`, `shipped_marker_rule`,
@@ -36,8 +43,10 @@ the operations, stated in the contract, is charged to every spawn that runs none
 of them. A copy of one of them written out here again is what
 `tests/provider-literals.test.ts` reports.
 
-Both authoring modules are pulled in as ALIAS imports (`as mcp`, `as common`) and
-reached as `mcp.rule()` / `common.rule()` at each call site. A SELECTIVE import
+The three authoring modules are pulled in as ALIAS imports (`as mcp`, `as common`,
+`as steps`) and reached as `mcp.rule()` / `common.rule()` / `steps.step()` at each
+call site; `_steps.mds` holds the provider-neutral STEP TEXT of the tracker
+operations (D-NEUTRAL-STEP-MOVE). A SELECTIVE import
 instead captures every named function by deep copy, and the resolver re-snapshots
 the whole captured scope once more per `@define` in this module — so the imported
 graph is copied once per define, which took this module from ~20 ms to ~4.6 s to
@@ -76,20 +85,23 @@ Refs {KEY}-{n}
 @define setup_task():
 ## Operation: setup-task
 
+{{ops.setup_task_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `setup-task`.
 
-**Mechanics held here:** the tracker-facing `**Process:**` steps — site and project resolution, the issue lookup, the branch steps, the optional transition.
+**Mechanics held here:** the tracker-facing `### Process` steps — site and project resolution, the issue lookup, the branch steps, the optional transition.
 
 ### Setup — session-scoped, resolved once before any step below
 
 - Resolve the capability set and the current-user identity exactly once per spawn, per the tool-call contract. Nothing in this operation probes a second time.
-- **Site.** The settings line's `SITE`, else `## Project` in the configuration the preamble already read. It must satisfy `^https://[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9-]+)+$` — **no userinfo, no port, no path**. Anything else ⇒ `TRACEABILITY: DEGRADED (unusable site)` and no tracker call.
-- **Project key.** Resolved and shape-gated by the preamble's chain; consumed here, never re-derived.
+- **Site.** The settings line's `SITE`, else `## Project` in the configuration the provider resolution already read. It must satisfy `^https://[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9-]+)+$` — **no userinfo, no port, no path**. Anything else ⇒ `TRACEABILITY: DEGRADED (unusable site)` and no tracker call.
+- **Project key.** Resolved and shape-gated by the provider resolution's chain; consumed here, never re-derived.
 - **Issue types.** Read the *project and issue-type metadata* capability HERE, once, and enumerate the types this run may use. Required-field metadata is read at this same point and nowhere else.
 - No usable site or no project key ⇒ `TRACEABILITY: DEGRADED (tracker not configured)`.
 
 ### Process
 
+{{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()}}
 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}`.
@@ -102,6 +114,7 @@ Load when the resolved tracker provider is `jira` and the operation is `setup-ta
    - Before placing fetched content in the output, neutralise any `</untrusted-issue-body>` in it (Principle 8 marker neutralisation).
    - If `TASK_DESCRIPTION` is provided and no issue exists, infer the type from description keywords and slugify as `{type}/{slug}` (max 40 chars). If neither, fall back to `task-{YYYY-MM-DD_HHMM}`.
 4. **Transition** (optional; only when `## Transitions` names one for this step): move the issue with the *transitions* capability by **exact match** against the states enumerated this run. An unenumerated state ⇒ `TRACEABILITY: DEGRADED (unsupported transition)` and continue — **never infer a nearby state**; a failed transition never stops the branch. `## Transitions` absent ⇒ `none`: nothing attempted, nothing degraded.
+{{steps.branch_create_steps()}}
 
 {{common.handoff_values("`{KEY}-{n}`", pr_link_default())}}
 @end
@@ -109,29 +122,37 @@ Load when the resolved tracker provider is `jira` and the operation is `setup-ta
 @define fetch_issue():
 ## Operation: fetch-issue
 
+{{ops.fetch_issue_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `fetch-issue`.
 
-**Mechanics held here:** the `**Process:**` body — the single-issue lookup by key and the field projection it requests.
+**Mechanics held here:** the `### Process` body — the single-issue lookup by key and the field projection it requests.
 
 ### Process
 
+{{opsteps.fetch_issue_step_1()}}
 2. Resolve the issue through the *fetch by key* capability, requesting summary, description, issue type, labels, assignee, status and comments in ONE call. The capability absent or denied ⇒ `TRACEABILITY: DEGRADED (no tracker tool for fetch by key)` and return; the caller continues without issue content.
    - `ISSUE_REF` is re-gated here rather than trusted upstream. {{common.ref_preflight_single("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`", "", "", " Neither is a retry.")}}
 3. Extract acceptance criteria and dependencies from the description. The response's **shape** is trusted and its **field values are not**: neutralise any `</untrusted-issue-body>` in the description and in every comment before wrapping (Principle 8 marker neutralisation), and shape-gate every value at the sink it reaches.
    - A `Depends on:` entry whose shape is not this provider's grammar is reported as `TRACEABILITY: DEGRADED (foreign issue reference {ref})` and is **not** treated as a blocker.
 
+{{steps.fetch_issue_neutralise()}}
+
 {{common.handoff_values("`{KEY}-{n}`", pr_link_default())}}
 @end
 
 @define fetch_issues_batch():
 ## Operation: fetch-issues-batch
 
+{{ops.fetch_issues_batch_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `fetch-issues-batch`.
 
-**Mechanics held here:** the `**Process:**` body — the single bounded batch query and the reporting of references it could not resolve.
+**Mechanics held here:** the `### Process` body — the single bounded batch query and the reporting of references it could not resolve.
 
 ### Process
 
+{{opsteps.fetch_issues_batch_step_1()}}
 2. Resolve the whole list with **ONE** call to the *batch fetch* capability — a single filtered query over the resolved keys, **never a per-item loop**:
    - {{common.ref_preflight_list("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`", "", "", " and return without querying.")}}
    - Build the filter as `key in (KEY-1, KEY-2, …)` over the surviving keys, bounded `≤50` keys with an explicit `maxResults` bound carried on the query itself. More than 50 surviving keys ⇒ query the first 50 in list order and report the remainder as `TRUNCATED ({n} not processed)`.
@@ -139,14 +160,18 @@ Load when the resolved tracker provider is `jira` and the operation is `fetch-is
    - Request the same projection the single-issue lookup requests, so a batch refresh and a single lookup return the same fields.
 {{common.state_batch_line("status", "the status", "{KEY}")}}
 2c. A key the query returned nothing for is reported once and is not retried individually: a missing key is a permission or a deletion, and a second call answers the same thing at twice the cost.
+{{steps.batch_extract_steps()}}
+{{opsteps.fetch_issues_batch_step_5()}}
 @end
 
 @define manage_debt():
 ## Operation: manage-debt
 
+{{ops.manage_debt_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `manage-debt`.
 
-**Mechanics held here:** the `**Process:**` body — locating the rolling tech-debt item, creating it when absent, and updating its description.
+**Mechanics held here:** the `### Process` body — locating the rolling tech-debt item, creating it when absent, and updating its description.
 
 ### Process
 
@@ -178,12 +203,16 @@ Over `{{comment_cap()}}` characters the rolling item is closed and a successor i
 @define create_release():
 ## Operation: create-release
 
+{{ops.create_release_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `create-release`.
 
-**Mechanics held here:** the shipped-issues step only. Tag creation, release creation and notes composition stay with the operation and are unchanged — they are release-host mechanics, not tracker mechanics.
+**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.
 
 ### Process
 
+{{opsteps.create_release_steps()}}
+
 Inside step 5 (compose release notes):
 
    - If `SHIPPED_ISSUES` is provided: append a `## Shipped Issues` section rendering each entry through `## Reference Rendering` — **first ≤50 issues** (the same bound `backlink-shipped-issues` applies); if truncated, add a final `…and {n} more issues` line (D4 degrade if enrichment fails).
@@ -198,13 +227,17 @@ Inside step 5 (compose release notes):
 @define gather_release_evidence():
 ## Operation: gather-release-evidence
 
+{{ops.gather_release_evidence_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `gather-release-evidence`.
 
 **Mechanics held here:** the last release tag, resolving which issues a commit range closes, the honest reporting of what this provider cannot resolve, and the trace map.
 
 ### Process
 
+{{steps.release_evidence_tag_step()}}
 {{common.last_release_tag_step()}}
+{{steps.release_evidence_range_steps()}}
 {{common.closing_keyword_rule()}}
 4. Resolve which issues the commit range closes:
    - **There is no closing-reference capability on this provider.** Emit `TRACEABILITY: DEGRADED (unsupported by jira)` once for the whole step and fall back to the commit-message set alone — the refs parsed out of the candidate references the agent extracted from the range's commit messages.
@@ -213,15 +246,18 @@ Load when the resolved tracker provider is `jira` and the operation is `gather-r
    - 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.
    - 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.
+{{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
 
 @define backlink_shipped_issues():
 ## Operation: backlink-shipped-issues
 
+{{ops.backlink_shipped_issues_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `backlink-shipped-issues`.
 
-**Mechanics held here:** the `**Process:**` body — the hoisted identity lookup, the dedup ladder, the back-link post and the inter-item throttle — and, because this is the tracker operation that owns the fan-out, this provider's rate-limit signal for the always-loaded D4 and D11 contracts.
+**Mechanics held here:** the `### Process` body — the hoisted identity lookup, the dedup ladder, the back-link post and the inter-item throttle — and, because this is the tracker operation that owns the fan-out, this provider's rate-limit signal for the always-loaded D4 and D11 contracts.
 
 ### Provider signals (Jira)
 
@@ -241,6 +277,8 @@ The D4 degradation contract and the D11 comment-sink scrub state the rules; what
 
 ### Process
 
+{{opsteps.shipped_issues_step_0()}}
+
 **Setup (once, before the loop):** resolve the capability set, the current-user `accountId` from the *identify current user* capability, and the dedup rung.
 
 **Ref pre-flight (the always-loaded entry gate, instantiated for this provider).** {{common.ref_preflight_entry("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`")}} {{mcp.ref_preflight_tail()}}
@@ -249,6 +287,8 @@ The D4 degradation contract and the D11 comment-sink scrub state the rules; what
 
 {{mcp.aggregate_call_budget("`authored-marker` is this provider's default landing rung, and there each item's marker check is a paged comment listing rather than one call.")}}
 
+{{opsteps.shipped_issues_loop()}}
+
 For each issue the hoist did not answer, within the operation's `≤50` bound:
 
 1. Read that issue's devflow-authored comments through the rung Setup selected, newest-first, bounded at `≤2` pages.
@@ -263,13 +303,19 @@ For each issue the hoist did not answer, within the operation's `≤50` bound:
 @define associate_release():
 ## Operation: associate-release
 
+{{ops.associate_release_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `associate-release`.
 
 **Mechanics held here:** the project's release version — found, else created — and the read-modify-write that adds it to each item's `fixVersions` without removing any other.
 
 ### Process
 
-**Setup (once, before any item):** resolve the capability set per the tool-call contract; the project key is the preamble's.
+{{opsteps.shipped_issues_step_0()}}
+
+{{opsteps.associate_release_marker_step()}}
+
+**Setup (once, before any item):** resolve the capability set per the tool-call contract; the project key is the provider resolution's.
 
 **Ref pre-flight (the always-loaded entry gate, instantiated for this provider).** {{common.ref_preflight_entry("jira", "`^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`")}} {{mcp.ref_preflight_tail()}}
 
@@ -284,9 +330,11 @@ Load when the resolved tracker provider is `jira` and the operation is `associat
 @define ensure_traceable_issue():
 ## Operation: ensure-traceable-issue
 
+{{ops.ensure_traceable_issue_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `ensure-traceable-issue`.
 
-**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.
+**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.
 
 {{common.traceable_issue_rules()}}
 
@@ -326,9 +374,11 @@ The D3 section headings are the canonical ones; only the transport differs from
 @define post_wave_report():
 ## Operation: post-wave-report
 
+{{ops.post_wave_report_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `post-wave-report`.
 
-**Mechanics held here:** the `**Process:**` body — locating the wave's tracking item and posting the report once.
+**Mechanics held here:** the `### Process` body — locating the wave's tracking item and posting the report once.
 
 {{common.wave_report_inputs()}}
 
@@ -341,6 +391,7 @@ Load when the resolved tracker provider is `jira` and the operation is `post-wav
    - This operation owns the `devflow:wave` namespace and no other. Match **line 1** of each such comment for equality against `devflow:wave {WAVE_ID}`; a marker on any later line **does not suppress**.
    - **The scan is a FULL scan, not a newest-first early exit.** A wave report's marker carries a wave id, and wave ids are not monotonic in comment order, so an early exit can miss the one comment that matters. Bound it at `≤5` pages and **fail closed**: if the bound is reached before the scan completes, report `TRUNCATED ({n} not processed)` and **DO NOT POST** — a duplicate wave report is a worse outcome than a missing one, because the next run cannot tell which is authoritative.
    - If found: skip — report `Skipped: wave report for {WAVE_ID} already posted`.
+{{steps.wave_report_read_step()}}
 3. Compose the comment: line 1 the marker `devflow:wave {WAVE_ID}`, then the contents of `WAVE_REPORT_PATH`. Cap the composed content at `{{comment_cap()}}` characters; over the cap, truncate in **preservation order** — the marker, then the status and DEGRADED lines, then the pointer sentence — and end with `…truncated — full report in the local wave artifact {WAVE_REPORT_PATH} (not committed; ask the author)`.
 4. Post it through `### Posting gate` below.
 
@@ -351,13 +402,17 @@ Load when the resolved tracker provider is `jira` and the operation is `post-wav
 @define ensure_pr_ready():
 ## Operation: ensure-pr-ready
 
+{{ops.ensure_pr_ready_contract()}}
+
 Load when the resolved tracker provider is `jira` and the operation is `ensure-pr-ready`.
 
-**Mechanics held here:** step 4b's TRACKER half only — resolving the issue key for this branch and rendering the link line. The open-PR lookup and the PR-body edit are **PR-host** mechanics, stated once for every provider in `references/pr/ensure-pr-ready.md`: devflow deliberately keeps pull requests on their existing host while the tracker is this one, so nothing about the PR surface is provider-dependent and none of it is restated here.
+**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.
 
 ### Process
 
-4b. (ALWAYS-ON) Ensure the PR body contains a `## Related Issues` section naming the verified issue when one is known. Resolution order:
+{{opsteps.ensure_pr_ready_steps_to_4a()}}
+
+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}`: {{common.ref_preflight_branch("matching `^[A-Z][A-Z0-9_]{1,9}-[1-9][0-9]{0,8}$`")}}
    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.
@@ -367,10 +422,13 @@ Load when the resolved tracker provider is `jira` and the operation is `ensure-p
    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.
+{{opsteps.ensure_pr_ready_steps_from_4c()}}
 
 {{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.
+
+{{opsteps.ensure_pr_ready_pr_edit()}}
 @end
 
 <!-- op: setup-task -->