devflow-kit 3.8.0 → 3.9.0

package/src/assets/mds/git/_pr.mds

@@ -28,12 +28,16 @@ one file, so they are readable from the operation's section alone:
 
 - the two summary operations' sentence naming `references/publication-gate.md`
   (D10's scope property [DR-20](i) is asserted over the references that name it);
+- the two summary operations' private-sections rule;
 - `post-resolution-summary`'s non-reproduction clause (Principle 8's containment
   obligation, readable from the operation's OWN section);
 - `resolve-review-threads`' step 3, the D9 gate application, between steps 2 and 4
   (the D9 predicate has one authority, and `references/decision-markers.md` is where
   the reference tree states it).
 
+The two summary operations carry no `PR mechanics held here` line. The review
+operation's cap line holds the 422 reason for both operations.
+
 `ensure-pr-ready` is not here. It is a tracker operation as well, so its one
 reference per provider holds the PR skeleton (`_ops_steps.mds`) and the provider's step 4b
 together; see `tracker/_github.mds`, `_jira.mds` and `_linear.mds`.
@@ -82,30 +86,28 @@ Load for `validate-branch` under every tracker provider.
 
 Load for `post-review-summary` under every tracker provider.
 
-**PR mechanics held here:** the author-filtered marker dedup, the visibility probe, the FULL/STUB compose templates with the 60000-character cap, and the scrub-then-post call.
-
 ### Process
 
-1. Check for existing comment with this run's marker (author-filtered — a third party posting the marker string must not suppress devflow's comment):
+1. Check for existing comment with this run's marker (author-filtered, so a third party's copy of the marker cannot suppress it):
    - Fetch viewer login: `gh api user --jq '.login'` → store as VIEWER_LOGIN
    - `gh pr view {PR_NUMBER} --json comments --jq '[.comments[] | select(.author.login == "'"$VIEWER_LOGIN"'")] | .[].body'`
    - Search for `<!-- devflow:review-summary cycle:{CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP}` in the viewer-authored comment bodies only (full pair match)
    - If found: skip — report `Skipped: already posted for cycle {CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP}`
 2. Load `references/publication-gate.md` and resolve `REVIEW_PUBLICATION` by its step 2; `off` ends the op without posting.
 3. Probe (if mode not yet determined): `gh repo view --json visibility --jq '.visibility'`, case-insensitive. `PRIVATE`/`INTERNAL` → FULL; `PUBLIC` → `STUB (public repository)`; empty output, an error or any other value → `STUB (visibility undeterminable)`. **Fail-closed: on any error or unrecognised value, treat as PUBLIC (mode STUB).**
-4. Read `REVIEW_SUMMARY_PATH` — repo-relative; read it under `WORKTREE_PATH` (else cwd).
+4. Read `REVIEW_SUMMARY_PATH` (repo-relative) under `WORKTREE_PATH` (else cwd); strip it (above).
 5. Compose body:
    - **FULL mode:**
      ```
      <!-- devflow:review-summary cycle:{CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP} -->
      ## Code Review — Cycle {CYCLE_NUMBER}
 
-     {full content of review-summary.md}
+     {stripped review-summary.md}
 
      ---
      *Posted by [devflow](https://github.com/dean0x/devflow) · cycle {CYCLE_NUMBER}*
      ```
-   - **STUB mode** (excluded: finding titles, file:line references, Blocking/Escalations/Third-Party/Verification sections, merge recommendation):
+   - **STUB mode** (stripped text only; excluded: all but the counts table):
      ```
      <!-- devflow:review-summary cycle:{CYCLE_NUMBER} ts:{REVIEW_TIMESTAMP} -->
      ## Code Review — Cycle {CYCLE_NUMBER}
@@ -214,28 +216,26 @@ unexplained unresolved threads.
 
 Load for `post-resolution-summary` under every tracker provider.
 
-**PR mechanics held here:** the author-filtered marker dedup, the visibility probe, the FULL/STUB compose templates with the 60000-character cap, and the scrub-then-post call.
-
 ### Process
 
-1. Check for existing marker (author-filtered — a third party posting the marker string must not suppress devflow's comment):
+1. Check for an existing marker (author-filtered, so a third party's copy of it cannot suppress devflow's comment):
    - Fetch viewer login: `gh api user --jq '.login'` → store as VIEWER_LOGIN
    - `gh pr view {PR_NUMBER} --json comments --jq '[.comments[] | select(.author.login == "'"$VIEWER_LOGIN"'")] | .[].body'`
    - Search the viewer-authored bodies only for the exact key `<!-- devflow:resolution-summary ts:{RESOLUTION_TS} -->`
    - If found: skip — report `Skipped: already posted for ts:{RESOLUTION_TS}`
 2. Load `references/publication-gate.md` and resolve `REVIEW_PUBLICATION` by its step 2; `off` ends the op without posting.
 3. Probe (if mode not yet determined): `gh repo view --json visibility --jq '.visibility'`, case-insensitive. `PRIVATE`/`INTERNAL` → FULL; `PUBLIC` → `STUB (public repository)`; empty output, an error or any other value → `STUB (visibility undeterminable)`. **Fail-closed: on any error or unrecognised value, treat as PUBLIC (mode STUB).**
-4. Read `RESOLUTION_SUMMARY_PATH` — repo-relative; read it under `WORKTREE_PATH` (else cwd).
+4. Read `RESOLUTION_SUMMARY_PATH` (repo-relative) under `WORKTREE_PATH` (else cwd); strip it (above).
 5. Compose body (where `{TS}` = `RESOLUTION_TS`):
    - **FULL mode:**
      ```
      <!-- devflow:resolution-summary ts:{TS} -->
-     {full content of resolution-summary.md}
+     {stripped resolution-summary.md}
 
      ---
      *Posted by [devflow](https://github.com/dean0x/devflow)*
      ```
-   - **STUB mode** (excluded: finding titles, file:line references, Blocking/Escalations/Third-Party/Verification sections):
+   - **STUB mode** (stripped text only; excluded: all but the counts table):
      ```
      <!-- devflow:resolution-summary ts:{TS} -->
      ## Resolution Summary
@@ -247,7 +247,7 @@ Load for `post-resolution-summary` under every tracker provider.
      Full report: {RESOLUTION_SUMMARY_PATH} (not committed; ask the author)
      *Posted by [devflow](https://github.com/dean0x/devflow)*
      ```
-   Cap body at 60000 characters (GitHub rejects over 65536 with a 422, which the 4xx rule would silently skip); truncate lowest-value sections first (Suggestions, then Pre-existing), keeping the counts table and every Blocking entry; end with `…truncated — full report in the local review artifact {RESOLUTION_SUMMARY_PATH} (not committed; ask the author)`.
+   Cap body at 60000 characters; truncate lowest-value sections first (Suggestions, then Pre-existing), keeping the counts table and every Blocking entry; end with `…truncated — full report in the local review artifact {RESOLUTION_SUMMARY_PATH} (not committed; ask the author)`.
 6. Write body to `$DEVFLOW_BODY_RAW`; apply the Comment-sink scrub (D11) — non-zero exit or missing script → DO NOT POST. Re-check the 60000-char cap on the scrubbed body (redaction may grow it; truncate at a line boundary below 59,800 chars, keeping the truncation pointer sentence; if truncation fires here: emit `NOTE: body exceeded 60k after redaction — truncated/stub posted` in op output and prepend that notice to the body). Post: `gh pr comment {PR_NUMBER} --body-file "$DEVFLOW_BODY"`.
 7. On 5xx: retry once. If still 5xx: `TRACEABILITY: DEGRADED (5xx on post-resolution-summary)`, warn, return.
 @end
@@ -301,7 +301,7 @@ Load for `update-pr-evidence` under every tracker provider.
 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.
 
-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.
+Run nothing else: the script makes the one PR read, the compare-and-swap body edit, its read-back and the evidence comment itself, edited in place when the viewer's own is the newest evidence comment, and posts nothing it could not scrub.
 @end
 
 <!-- op: validate-branch -->

package/src/assets/mds/git/_references.mds

@@ -104,15 +104,14 @@ When `.devflow/conventions.md` already exists the operation returns
 
 Applies to **`post-review-summary` and `post-resolution-summary` only.** No other op probes repo visibility.
 
-**Step order inside each summary op:**
-1. Dedup check (D7/D8 marker — unchanged, stays first).
+**Step order:**
+1. Dedup check (D7/D8 marker; stays first).
 2. Resolve `REVIEW_PUBLICATION` input: `off` → report `**Publication**: OFF (publication disabled by config)`, op ends without posting. `full` → mode FULL, skip probe. `auto` or absent/unrecognised → probe.
    - `stub` (never unrecognised) → mode STUB, skip probe; report `STUB (evidence policy)`.
-3. Probe once: `gh repo view --json visibility --jq '.visibility'` — compare case-insensitively. `PRIVATE` or `INTERNAL` → mode FULL. Anything else (including `PUBLIC`, empty output, command error, unauthenticated) → mode STUB. **Fail-closed rule: on any error or unrecognised value, treat as PUBLIC (mode STUB).**
-4. Compose body (full content in FULL mode; stub template in STUB mode — defined per op).
-5. Scrub per D11 (both modes — the stub is also scrubbed).
-6. Re-check 60000-char cap **after** the scrub (redaction tokens may grow the body; truncate at a line boundary below 59,800 chars, keeping the truncation pointer sentence).
-7. Post; 5xx retry-once (unchanged).
+3. Probe once: `gh repo view --json visibility --jq '.visibility'`, case-insensitive. `PRIVATE` or `INTERNAL` → mode FULL; anything else → mode STUB. **Fail-closed rule: on any error or unrecognised value, treat as PUBLIC (mode STUB).**
+4. Compose body (defined per op).
+5. Scrub per D11 (both modes), then re-check the 60000-char cap **after** the scrub.
+6. Post; 5xx retry-once.
 @end
 
 @define trust_rule():

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

@@ -152,10 +152,7 @@ Load when the resolved tracker provider is `github` and the operation is `manage
 
 1. Find or create "Tech Debt Backlog" issue with `tech-debt` label
 2. Check issue body size; archive if > 60000 chars (per devflow:git)
-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 updated issue body to `$DEVFLOW_BODY_RAW`; apply the Comment-sink scrub (D11) and post via `gh issue edit {number} --body-file "$DEVFLOW_BODY"`

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

@@ -177,10 +177,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.

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

@@ -215,10 +215,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.