From bfe812b4e8ec912d0af04a0f7c1d042486a6e2c4 Mon Sep 17 00:00:00 2001
From: Rasmus Widing <rasmus.widing@gmail.com>
Date: Sun, 19 Apr 2026 09:17:56 +0300
Subject: [PATCH 1/3] =?UTF-8?q?feat(workflows):=20add=20repo-triage=20?=
 =?UTF-8?q?=E2=80=94=206-node=20periodic=20maintenance=20workflow?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds .archon/workflows/repo-triage.yaml: a self-contained periodic
maintenance workflow that uses inline sub-agents (Claude SDK agents:
field introduced in #1276) for map-reduce across open issues and PRs.

Six DAG nodes, three-layer topology:
- Layer 1 (parallel): triage-issues, link-prs, closed-pr-dedup-check,
  stale-nudge
- Layer 2: closed-dedup-check (reads triage-issues state)
- Layer 3: digest (synthesises all prior nodes + writes markdown)

Capabilities per node:
- triage-issues: delegates labeling to on-disk triage-agent; inline
  brief-gen Haiku for duplicate detection; 3-day auto-close clock
  for unanswered duplicate warnings
- link-prs: conservative PR ↔ issue cross-refs via inline pr-issue-
  matcher Haiku, Sonnet re-verifies fully-addresses claims before
  suggesting Closes #X; auto-nudges on low-quality PR template fill
  with first-run grandfather guard (snapshot-only, no nudge spam)
- closed-dedup-check: cross-matches open issues against recently-
  closed ones via inline closed-brief-gen Haiku; same 3-day clock
- closed-pr-dedup-check: flags open PRs duplicating recently-closed
  PRs via inline pr-brief-gen Haiku; comment-only, never closes PRs
- stale-nudge: 60-day inactivity pings (configurable); no auto-close
- digest: synthesises per-node outputs + reads state files to emit
  $ARTIFACTS_DIR/digest.md with clickable GitHub comment links

Env-gated rollout knobs:
- DRY_RUN=1 (read-only; prints [DRY] lines, no gh/state mutations)
- SKIP_PR_LINK=1, SKIP_CLOSED_DEDUP=1, SKIP_CLOSED_PR_DEDUP=1,
  SKIP_STALE_NUDGE=1
- STALE_DAYS=N (stale-nudge window; default 60)

Cross-run state under .archon/state/ (gitignored):
- triage-state.json        briefs + pendingDedupComments
- closed-dedup-state.json  closedBriefs + closedMatchComments
- closed-pr-dedup-state.json openBriefs + closedBriefs + matches
- pr-state.json            linkedPrs + commentIds + templateAdherence
- stale-nudge-state.json   nudged (with updatedAtAtNudge for re-nudge)

Every bot comment:
- @-tags the target human (reporter for issues, author for PRs)
- Tracks comment ID in state for traceability
- Is idempotent — re-runs skip existing comments

Intended use: invoke periodically (`archon workflow run repo-triage
--no-worktree`) once a scheduler lands; live state persists across
runs so previously-flagged items reconcile correctly.

.gitignore: adds .archon/state/ for cross-run memory files.
---
 .archon/workflows/repo-triage.yaml | 1339 ++++++++++++++++++++++++++++
 .gitignore                         |    3 +
 2 files changed, 1342 insertions(+)
 create mode 100644 .archon/workflows/repo-triage.yaml

diff --git a/.archon/workflows/repo-triage.yaml b/.archon/workflows/repo-triage.yaml
new file mode 100644
index 0000000000..0928f3f3d8
--- /dev/null
+++ b/.archon/workflows/repo-triage.yaml
@@ -0,0 +1,1339 @@
+name: repo-triage
+description: >-
+  Periodic repo maintenance — in parallel, triages open issues (labels +
+  dedup detection + 3-day auto-close) and cross-references open PRs against
+  open issues (conservative: suggests Closes #X only when a PR fully
+  addresses an issue, never closes anything itself). State is persisted
+  under .archon/state/ so prior runs are remembered. Designed for periodic
+  runs; safe to re-run; idempotent.
+interactive: false
+
+nodes:
+  # ---------------------------------------------------------------------------
+  # Issue triage — runs concurrently with pr-link (no depends_on between them).
+  # ---------------------------------------------------------------------------
+  - id: triage-issues
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      brief-gen:
+        description: >-
+          Reads a single GitHub issue and returns a concise JSON brief,
+          plus a template-adherence check if the caller provided template
+          context. Used for duplicate detection + template-fill reporting.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You are a concise GitHub issue summariser. The caller's prompt
+          will include an issue number AND (optionally) the issue
+          templates from `.github/ISSUE_TEMPLATE/`.
+
+          Fetch the issue:
+            gh issue view <N> --json number,title,body,labels,author
+
+          Return ONLY a single JSON object — no fences, no prose:
+
+          {
+            "number": <N>,
+            "summary": "2-3 sentence neutral summary",
+            "primarySymptom": "one short sentence — the core symptom or ask",
+            "area": "best-guess tag, e.g. backend, frontend, docs, core, isolation, cli, workflows, providers",
+            "templateAdherence": {
+              "templateType": "bug_report | feature_request | other | none",
+              "sectionsFilled": ["<section headers where the reporter wrote non-trivial content>"],
+              "sectionsMissing": ["<template section headers clearly left empty or untouched>"],
+              "quality": "good | partial | empty | no-template-context"
+            }
+          }
+
+          Template-adherence rules:
+          - If the caller did NOT include templates → `quality: "no-template-context"`, skip sections.
+          - `quality: "good"` = most template sections have real content.
+          - `quality: "partial"` = headers present but several sections look blank/placeholder.
+          - `quality: "empty"` = body has nothing matching the template shape.
+          - Ignore whitespace / HTML comment placeholders like `<!-- ... -->` as "filled".
+
+          Be terse. If the issue body is empty, set area='unknown' and
+          quality='empty'.
+    prompt: |
+      You are the issue-triage orchestrator for the repository in the
+      current working directory.
+
+      # Mode check — READ THIS FIRST
+
+      Run once at the start:
+          echo "DRY_RUN=${DRY_RUN:-0}"
+
+      If DRY_RUN=1 — READ-ONLY mode:
+        - Do all read-only work (gh list/view/api, state file reads, clustering).
+        - For every mutation you WOULD have made (label, comment, close,
+          state write), print a line prefixed `[DRY] would ...` with the
+          full body you would have posted.
+        - Do NOT run `gh issue (comment|close|edit)`. Do NOT use the Write
+          tool on `.archon/state/*.json`.
+        - When delegating via Task to triage-agent/brief-gen, PREPEND this
+          exact sentence to every Task prompt:
+              "DRY_RUN=1 is active. Do NOT apply labels or mutate the
+               issue in any way. Instead print `[DRY] would ...` lines
+               describing what you would have done."
+        - End with the standard summary table, but prefix the title
+          `## (DRY RUN) Issue triage — <now>`.
+
+      Your job on every (non-dry) run:
+        1. Apply labels to any unlabeled open issues (delegate to triage-agent)
+        2. Generate or refresh briefs for new/changed open issues (delegate to brief-gen)
+        3. Detect potential duplicates across all briefs
+        4. Comment on suspected duplicates with a "reply in 3 days or auto-close" note
+        5. Auto-close stale warnings from prior runs whose authors never replied
+        6. Persist state so future runs remember what's already been processed
+
+      # State file
+
+      Location: `.archon/state/triage-state.json` (relative to repo root).
+      Before reading or writing, ensure the directory exists:
+
+          mkdir -p .archon/state
+
+      Shape — on first run the file may not exist; treat missing as:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "briefs": {},
+            "pendingDedupComments": {}
+          }
+
+      - `briefs[<issueNumber>]`: { sha, summary, primarySymptom, area, briefedAt }
+          - `sha`: short digest of `title + "\n" + body + "\n" + updatedAt`,
+            e.g. `printf '%s\n%s\n%s' "$T" "$B" "$U" | shasum | cut -c1-12`.
+      - `pendingDedupComments[<issueNumber>]`: { canonical, botCommentId, postedAt }
+          - `postedAt`: ISO-8601 UTC (`date -u +%FT%TZ`).
+          - `botCommentId`: the comment ID from `gh issue comment` — if you
+            can't parse one, keep the full returned URL.
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/triage-state.json 2>/dev/null
+      ```
+      Parse as JSON. On ENOENT or empty, start from the default shape above.
+
+      ## 2. Fetch all open issues
+      ```
+      gh issue list --state open \
+        --json number,title,body,author,labels,comments,createdAt,updatedAt \
+        --limit 200 > "$ARTIFACTS_DIR/issues.json"
+      ```
+      (`gh issue list` already excludes PRs.)
+
+      Also read issue templates ONCE at this point for the template-
+      adherence check downstream:
+      ```
+      for tpl in .github/ISSUE_TEMPLATE/*.md; do
+        [ -f "$tpl" ] && printf '### %s\n```\n' "$(basename "$tpl")" && cat "$tpl" && printf '\n```\n\n'
+      done > "$ARTIFACTS_DIR/issue-templates.md"
+      ```
+      If no templates exist, the file will be empty — that's fine.
+
+      ## 3. Classify work
+      For each open issue:
+        - If `labels` is empty → needs LABEL.
+        - Compute sha. If no entry in `state.briefs[N]` OR stored sha differs
+          → needs BRIEF. Otherwise reuse the cached brief.
+
+      ## 4. LABEL PASS — parallel fan-out to triage-agent
+      Spawn the existing on-disk `triage-agent` sub-agent in PARALLEL (a
+      single assistant turn with multiple Task tool calls — this matters
+      for speed). Per-task prompt:
+
+          "Triage open issue #<N> in this repository. Fetch it via
+           `gh issue view`, classify by type/effort/priority/area, and
+           apply the missing label categories via `gh issue edit`.
+           Respect existing labels."
+
+      Wait for all label tasks to settle before moving on.
+
+      ## 5. BRIEF PASS — parallel fan-out to brief-gen
+      For every issue that needs a brief, spawn the inline `brief-gen`
+      sub-agent in PARALLEL (single turn, multiple Task calls).
+
+      Per-task prompt template:
+          "Brief issue #<N>.
+
+           <if issue-templates.md has content, inline it here with a header>
+           ISSUE TEMPLATES (for templateAdherence check):
+           <file contents>"
+
+      If `$ARTIFACTS_DIR/issue-templates.md` is empty, omit the template
+      block — brief-gen will return `quality: "no-template-context"`.
+
+      Parse each response as JSON. If parsing fails, skip that issue.
+      Merge results into `state.briefs[N]` with a freshly computed sha
+      and `briefedAt = now-iso`. Preserve the `templateAdherence` field.
+
+      ## 6. CLUSTER PASS — detect duplicates
+      Using fresh + cached briefs:
+        - Group issues whose `summary` + `primarySymptom` describe the
+          same underlying problem. Prefer matches where `area` is the same.
+        - A cluster of size 1 is NOT a duplicate — skip.
+        - For each cluster of 2+: the oldest (lowest number) is `canonical`.
+        - Members already in `state.pendingDedupComments` are already
+          tracked — SKIP. Everything else is a NEW dedup to act on.
+
+      Be CONSERVATIVE. False negatives are fine — this workflow re-runs.
+      False positives create noise. If two issues share a surface keyword
+      but describe different root causes, do not cluster.
+
+      ## 7. ACT PASS — comment + track
+      For each NEW dedup candidate #N with canonical #C:
+        - Post a comment on #N:
+
+              @<reporter-of-N> this looks like it may overlap with #<C>.
+              Could you confirm whether it's a duplicate? If there is no
+              reply within 3 days this issue will be auto-closed.
+
+          Via: `gh issue comment <N> --body "..."` — capture the comment ID.
+        - Record in state:
+              pendingDedupComments[N] = {
+                canonical: C,
+                botCommentId: "<id>",
+                postedAt: "<now-iso>"
+              }
+
+      Post sequentially (not via Task) so you can reliably capture each
+      comment ID.
+
+      ## 8. RECONCILE PASS — 3-day auto-close
+      Cache the bot's GitHub login once at the top of the run:
+          gh api user --jq .login
+
+      For each entry `(N, { canonical, botCommentId, postedAt })`:
+        - Fetch current comments: `gh issue view <N> --json comments`
+        - Identify comments created AFTER `postedAt` whose author is NOT
+          the cached bot login.
+        - If ANY non-bot reply after `postedAt` → drop entry from state
+          (humans are engaged).
+        - Else if `now - postedAt >= 3 days`:
+            - Post closing comment on #N:
+                  "Auto-closing: no reply within 3 days of the duplicate
+                   check. Please reopen if this is still relevant."
+            - `gh issue close <N> --reason not_planned`
+            - Drop entry from state.
+        - Else → keep the entry as-is (will be revisited next run).
+
+      ## 9. SAVE
+      Set `state.lastRunAt = <now-iso>`. Use the Write tool to persist
+      `.archon/state/triage-state.json` as formatted JSON (2-space indent).
+
+      ## 10. Summary output
+      Print a single compact block:
+
+          ## Issue triage — <now>
+          Labels applied:         <N>
+          Briefs: fresh=<N>, cached=<M>, failed=<K>
+          New dedup clusters:     <N>
+          Dedup comments posted:  <N>
+          Auto-closed this run:   <N>
+          Still pending (waiting on reply): <N>
+          Template fill (of issues briefed this run):
+            good=<N>, partial=<N>, empty=<N>, no-template-context=<N>
+            Issues with empty templates (#):
+              <list of up to 10 numbers, rest truncated "… +K more">
+
+      No other prose.
+
+      # Guardrails
+
+      - NEVER close an issue that is not tracked in `pendingDedupComments`
+        with `postedAt` ≥ 3 days ago AND no reply after that timestamp.
+      - NEVER label issues yourself — always delegate to `triage-agent`.
+      - If `gh` returns an auth error or rate limit, stop the run cleanly
+        and report in the summary. Do NOT partially mutate state.
+      - State writes are ATOMIC per run — only write the final merged
+        state once at step 9. If a pass fails midway, the previous state
+        remains.
+      - Parallel Task fan-out is strict: ONE assistant turn with MANY
+        Task tool calls, not sequential Task calls.
+
+  # ---------------------------------------------------------------------------
+  # Closed-dedup check — follow-up to triage-issues. Checks whether any
+  # currently open issue duplicates a recently-closed one (reporter may not
+  # have noticed their case is already fixed or declined). Reads open-issue
+  # briefs from the state file produced by triage-issues as its context
+  # artifact. Runs in parallel with link-prs once triage-issues is done.
+  # ---------------------------------------------------------------------------
+  - id: closed-dedup-check
+    depends_on: [triage-issues]
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      closed-brief-gen:
+        description: >-
+          Reads a single recently-CLOSED GitHub issue and returns a JSON
+          brief including close reason and any closing PR reference.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You are a concise summariser for CLOSED GitHub issues. You will
+          be given an issue number in the caller's prompt.
+
+          Fetch the issue with:
+            gh issue view <N> --json number,title,body,stateReason,closedAt,comments,labels
+
+          Also check the closing comment thread for any `#<pr>` reference
+          that looks like it closed the issue (keywords: closed by, fixed by,
+          resolved by, Closes, Fixes, Resolves).
+
+          Return ONLY a single JSON object on stdout — no fences, no prose:
+
+          {
+            "number": <N>,
+            "summary": "2-3 sentence summary of what the issue was",
+            "primarySymptom": "one short sentence — the core symptom",
+            "area": "single best-guess area tag (same vocabulary as open briefs)",
+            "closedAt": "<ISO timestamp>",
+            "stateReason": "completed | not_planned | duplicate | null",
+            "resolvedByPr": "<PR number if identifiable from closing thread, else null>"
+          }
+
+          Be terse. If `stateReason` is `not_planned` or `duplicate`, that
+          matters for the match verdict downstream — include it honestly.
+    prompt: |
+      You check whether any currently OPEN issue duplicates a recently
+      CLOSED one. A reporter may have filed a bug that was fixed months
+      ago under a different number, or one that was already declined.
+
+      # Mode check — READ FIRST
+
+      Run once:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_CLOSED_DEDUP=${SKIP_CLOSED_DEDUP:-0}"
+
+      If SKIP_CLOSED_DEDUP=1 — print
+          "Skipping closed-dedup-check per SKIP_CLOSED_DEDUP=1"
+      and exit immediately. No gh calls, no state read, no Task fan-out.
+
+      If DRY_RUN=1 — READ-ONLY:
+        - Do read-only work (gh list/view, state reads, clustering).
+        - For every mutation (comment, close, state write), print `[DRY] would ...`.
+        - Do NOT run gh issue comment/close.
+        - Do NOT use Write on `.archon/state/*.json`.
+        - When spawning closed-brief-gen via Task, prepend to its prompt:
+              "DRY_RUN=1 is active. Run only read-only gh commands."
+        - End with a summary prefixed `## (DRY RUN) Closed-dedup check — <now>`.
+
+      # Context artifact from triage-issues
+
+      Open-issue briefs live in:
+          .archon/state/triage-state.json
+
+      Schema (written by the triage-issues node earlier in this run):
+
+          {
+            "version": 1,
+            "lastRunAt": "...",
+            "briefs": { "<number>": { sha, summary, primarySymptom, area, briefedAt } },
+            "pendingDedupComments": { ... }
+          }
+
+      If the file is missing or `briefs` is empty, print
+          "No open-issue briefs available from triage-issues — skipping."
+      and exit. (This guards against a failed upstream.)
+
+      # State file (this node)
+
+      Separate file to isolate concerns from triage-issues:
+          .archon/state/closed-dedup-state.json
+
+      Default shape when missing:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "closedBriefs": {},
+            "closedMatchComments": {}
+          }
+
+      - `closedBriefs[<closedIssue>]`: { sha, summary, primarySymptom, area, closedAt, stateReason, resolvedByPr, briefedAt }
+      - `closedMatchComments[<openIssue>]`: { matchedClosed, botCommentId, postedAt }
+
+      `mkdir -p .archon/state` before any write.
+
+      # Step-by-step
+
+      ## 1. Read both state files
+      - Read `.archon/state/triage-state.json` — grab `briefs` (open-issue briefs).
+      - Read `.archon/state/closed-dedup-state.json` — default on ENOENT.
+
+      ## 2. Fetch recently-closed issues (last 90 days)
+      Compute cutoff:
+          CUTOFF=$(date -u -v-90d +%Y-%m-%d 2>/dev/null || date -u -d '90 days ago' +%Y-%m-%d)
+
+      Fetch:
+          gh issue list --state closed --limit 200 \
+            --json number,title,body,labels,stateReason,closedAt \
+            --search "closed:>${CUTOFF}" > "$ARTIFACTS_DIR/closed-issues.json"
+
+      Filter out any closed issue whose `stateReason` is `duplicate` — those
+      are noise for our matching (they were already dedup'd against canonical).
+
+      ## 3. Classify work
+      For each closed issue:
+        - Compute sha of `title + "\n" + body + "\n" + closedAt`.
+        - If `state.closedBriefs[N]` exists AND sha matches → reuse.
+        - Else → needs BRIEF.
+
+      ## 4. BRIEF PASS — parallel Task fan-out to closed-brief-gen
+      Spawn `closed-brief-gen` in PARALLEL (single assistant turn, multiple
+      Task calls) for every closed issue needing a brief. Per-task prompt:
+
+          "Brief closed issue #<N>."
+
+      Parse each JSON response. On parse failure, skip that issue. Merge
+      into `state.closedBriefs`.
+
+      ## 5. CROSS-CLUSTER PASS — match open vs closed
+      For each OPEN issue brief (from triage-state.json):
+        - Find the best match (if any) among `closedBriefs`. Same
+          conservative rules as triage-issues:
+            - `area` should match
+            - `primarySymptom` + `summary` should describe the same problem
+            - SKIP weak keyword-only matches
+        - Pick at most ONE closed match per open issue (the strongest).
+
+      A match that is ALREADY recorded in `state.closedMatchComments[<open>]`
+      → SKIP (already acted on).
+
+      Everything else is a NEW closed-dedup candidate.
+
+      ## 6. ACT PASS — comment + track
+      For each NEW candidate (open #O → closed #C):
+
+        - Fetch the reporter's login (not stored in briefs):
+              gh issue view <O> --json author --jq .author.login
+
+        - Build the comment body (tag the reporter):
+
+              @<reporter-of-O> this looks like it may have been resolved
+              by #<C> (closed <date> as <stateReason><if resolvedByPr: ",
+              via PR #<pr>">). Could you check whether that fix addresses
+              your case? If there is no reply within 3 days this issue will
+              be auto-closed.
+
+        - Post: `gh issue comment <O> --body "..."`
+          Capture comment ID.
+        - Record in state:
+              closedMatchComments[O] = {
+                matchedClosed: C,
+                botCommentId: "<id>",
+                postedAt: "<now-iso>"
+              }
+
+      Post sequentially (not via Task) so you can capture comment IDs.
+
+      ## 7. RECONCILE PASS — 3-day auto-close
+      Cache bot login once at top-of-run: `gh api user --jq .login`.
+
+      For each entry `(O, { matchedClosed, botCommentId, postedAt })` in
+      `state.closedMatchComments`:
+        - Fetch: `gh issue view <O> --json comments`
+        - Find comments AFTER `postedAt` whose author is NOT the bot.
+        - If reporter replied → drop entry (engaged).
+        - Else if `now - postedAt >= 3 days`:
+            - Post closing comment:
+                  "Auto-closing: no reply within 3 days of the closed-match
+                   check. Please reopen if your case is NOT resolved by
+                   #<matchedClosed>."
+            - `gh issue close <O> --reason not_planned`
+            - Drop entry from state.
+        - Else → keep as-is.
+
+      ## 8. SAVE
+      Set `state.lastRunAt = <now-iso>`. Write
+      `.archon/state/closed-dedup-state.json` with the Write tool
+      (2-space JSON).
+
+      ## 9. Summary output
+          ## Closed-dedup check — <now>
+          Open briefs loaded:          <N>   (from triage-issues)
+          Closed issues in window:     <N>   (last 90 days, non-duplicate)
+          Closed briefs: fresh=<N>, cached=<M>, failed=<K>
+          New closed-match candidates: <N>
+          Comments posted:             <N>
+          Auto-closed this run:        <N>
+          Still pending (waiting on reply): <N>
+
+      # Guardrails
+      - NEVER close an open issue unless it's been tracked in
+        `closedMatchComments` for ≥3 days AND had no non-bot reply.
+      - Be MORE conservative here than triage-issues — false positives
+        suggest a reporter's bug is already fixed when it isn't, and that
+        erodes trust. When in doubt, skip.
+      - If `gh` errors (auth, rate limit), abort cleanly and summarise.
+      - State writes are ATOMIC — one Write at step 8.
+      - Parallel Task fan-out required for step 4 only. Step 6 is sequential
+        to capture comment IDs reliably.
+
+  # ---------------------------------------------------------------------------
+  # Closed-PR dedup check — standalone. For each OPEN PR, checks whether a
+  # recently-CLOSED PR covered the same change (superseded, rejected, or
+  # merged variant). Comments only — NEVER closes an open PR (author's work
+  # is too valuable to discard without consent). Runs in parallel with the
+  # other top-level nodes.
+  # ---------------------------------------------------------------------------
+  - id: closed-pr-dedup-check
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      pr-brief-gen:
+        description: >-
+          Reads a single PR (open OR closed) and returns a compact JSON
+          brief suitable for cross-comparison.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You summarise a single GitHub PR. You will be given a PR number
+          and a `state` hint (open/closed) in the caller's prompt.
+
+          Fetch:
+            gh pr view <N> --json number,title,body,state,headRefName,changedFiles,additions,deletions,mergedAt,closedAt,stateReason
+            gh pr diff <N> --color=never | head -c 30000
+
+          Return ONLY a single JSON object — no fences, no prose:
+
+          {
+            "number": <N>,
+            "state": "open" | "closed" | "merged",
+            "stateReason": "<closed reason if applicable, else null>",
+            "title": "<title>",
+            "summary": "2-3 sentence neutral summary of what the PR changes",
+            "intent": "one-sentence core goal (bug fix X, add feature Y, refactor Z)",
+            "scope": "affected-area tag (backend/frontend/docs/core/providers/etc)",
+            "filesChanged": <count>,
+            "mergedAt": "<iso or null>",
+            "closedAt": "<iso or null>"
+          }
+
+          Be terse. Don't quote commit messages verbatim unless they are
+          the only information available.
+    prompt: |
+      You find OPEN PRs that duplicate or supersede a recently-CLOSED PR.
+      A contributor may have missed that a similar change was already
+      merged, rejected, or abandoned — flag it so a maintainer can decide.
+
+      # Mode check — READ FIRST
+
+      Run once:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_CLOSED_PR_DEDUP=${SKIP_CLOSED_PR_DEDUP:-0}"
+
+      If SKIP_CLOSED_PR_DEDUP=1 — print
+          "Skipping closed-pr-dedup-check per SKIP_CLOSED_PR_DEDUP=1"
+      and exit immediately.
+
+      If DRY_RUN=1 — READ-ONLY:
+        - All read-only gh calls OK.
+        - Do NOT run `gh pr comment`. Do NOT use Write on state files.
+        - Print `[DRY] would ...` for every mutation.
+        - When spawning pr-brief-gen via Task, prepend:
+              "DRY_RUN=1 is active. Run only read-only gh commands."
+        - End with a summary prefixed `## (DRY RUN) Closed-PR dedup — <now>`.
+
+      # State file
+
+      Location: `.archon/state/closed-pr-dedup-state.json`.
+      `mkdir -p .archon/state` before any write.
+
+      Default shape when missing:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "openBriefs": {},
+            "closedBriefs": {},
+            "closedMatchComments": {}
+          }
+
+      - `openBriefs[<prNumber>]`: { sha, brief-fields..., briefedAt }
+      - `closedBriefs[<prNumber>]`: { sha, brief-fields..., briefedAt }
+      - `closedMatchComments[<openPr>]`: { matchedClosed, botCommentId, postedAt }
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/closed-pr-dedup-state.json 2>/dev/null
+      ```
+      Parse JSON; default on ENOENT.
+
+      ## 2. Fetch PRs
+      Compute the cutoff:
+          CUTOFF=$(date -u -v-90d +%Y-%m-%d 2>/dev/null || date -u -d '90 days ago' +%Y-%m-%d)
+
+      ```
+      gh pr list --state open --limit 100 \
+        --json number,title,body,headRefName,updatedAt,author \
+        > "$ARTIFACTS_DIR/open-prs.json"
+
+      gh pr list --state closed --limit 200 \
+        --json number,title,body,state,closedAt,mergedAt \
+        --search "closed:>${CUTOFF}" \
+        > "$ARTIFACTS_DIR/closed-prs.json"
+      ```
+
+      (`--state closed` includes both merged and non-merged closed PRs.)
+
+      ## 3. Classify work
+      For both open and closed PRs:
+        - Compute a sha of `title + "\n" + body + "\n" + (mergedAt ?? closedAt ?? headRefName)`.
+        - If an entry exists in the corresponding `state.{open,closed}Briefs`
+          and the sha matches → reuse the cached brief.
+        - Else → needs BRIEF.
+
+      ## 4. BRIEF PASS — parallel Task fan-out to pr-brief-gen
+      Spawn `pr-brief-gen` in PARALLEL for every PR needing a brief
+      (open AND closed, all in a single assistant turn if possible — the
+      sub-agent handles both via the `state` hint).
+
+      Per-task prompt template:
+          "Brief PR #<N> — state=<open|closed>."
+
+      Parse each JSON response. Skip on parse failure. Merge into the
+      appropriate `{open,closed}Briefs` bucket.
+
+      ## 5. CROSS-CLUSTER PASS — match open vs closed
+      For each OPEN PR brief:
+        - Find the strongest match among `closedBriefs`. Match rules (all
+          should broadly agree before declaring a duplicate):
+            - `scope` matches
+            - `intent` is substantially the same (not just same area)
+            - `title` is semantically close OR the diffs plausibly touch
+              the same files (look at `filesChanged` counts + bodies)
+        - Pick at most ONE closed match per open PR.
+
+      Skip open PRs already in `state.closedMatchComments`.
+
+      Be STRICT. PR duplication calls are higher-stakes than issue
+      duplication — suggesting a maintainer's merged change already did
+      the work of someone's open PR is embarrassing if wrong. When in
+      doubt, skip.
+
+      ## 6. ACT PASS — comment + record
+      For each NEW candidate (open PR #O → closed PR #C):
+
+        - Determine the close flavour for the comment text (always tag
+          the open PR's author):
+            - If `closedBriefs[C].state == "merged"` →
+                "@<pr-author> this PR looks similar to the already-merged
+                 #<C> (merged <date>). Please check whether your change
+                 is still needed — rebase on main and confirm."
+            - Else (closed unmerged) →
+                "@<pr-author> this PR looks similar to #<C>, which was
+                 closed on <date> (<stateReason>). You may want to read
+                 the discussion there before pushing further."
+
+        - Idempotency: fetch `gh pr view <O> --json comments` and skip if
+          a comment with the same body already exists.
+
+        - Post: `gh pr comment <O> --body "..."`. Capture comment ID.
+
+        - Record in state:
+              closedMatchComments[O] = {
+                matchedClosed: C,
+                botCommentId: "<id>",
+                postedAt: "<now-iso>"
+              }
+
+      Post sequentially (not via Task) for reliable comment-ID capture.
+
+      NO auto-close. PRs are author work product; closing them without
+      consent discards effort. A reminder comment is the right ceiling.
+      Entries stay in `closedMatchComments` indefinitely (never reconciled)
+      so we never re-post on the same PR.
+
+      ## 7. SAVE
+      Set `state.lastRunAt = <now-iso>`. Write
+      `.archon/state/closed-pr-dedup-state.json` with the Write tool.
+
+      ## 8. Summary output
+          ## Closed-PR dedup — <now>
+          Open PRs scanned:             <N>
+          Closed PRs in window:         <N>   (last 90 days)
+          Briefs: fresh_open=<N>, cached_open=<N>, fresh_closed=<N>, cached_closed=<N>, failed=<N>
+          New closed-match candidates:  <N>
+          Comments posted:              <N>
+          Total tracked matches (all time): <N>
+
+      # Guardrails
+      - NEVER close an open PR. Comment only.
+      - Idempotent comments — always check existing PR comments before
+        posting to avoid noise.
+      - State writes are ATOMIC — one Write at step 7.
+      - Parallel Task fan-out for step 4 only. Step 6 sequential.
+      - Strict matching — false positives on PR dedup are a maintainer
+        trust hit. When ambiguous, skip.
+
+  # ---------------------------------------------------------------------------
+  # PR ↔ issue linker — runs concurrently with triage-issues.
+  # ---------------------------------------------------------------------------
+  - id: link-prs
+    model: sonnet
+    allowed_tools: [Bash, Read, Write, Task]
+    agents:
+      pr-issue-matcher:
+        description: >-
+          Given one PR (title + body + diff) and a compact list of open
+          issues, returns related-issue matches AND a template-adherence
+          check if the caller provided the PR template. Conservative —
+          prefers "related" over "fully-addresses" when in doubt.
+        model: haiku
+        tools: [Bash, Read]
+        prompt: |
+          You match a single GitHub PR to the open issues it touches AND
+          score its adherence to the repository's PR template (if the
+          caller provided one).
+
+          Inputs in the caller's prompt:
+            - PR number
+            - Compact issue list (one per line: `#<N> <title> — <body excerpt>`)
+            - Optional PR_TEMPLATE section
+
+          Your work:
+            1. Fetch the PR:
+                 gh pr view <N> --json number,title,body,files,headRefName
+            2. Fetch a compact diff:
+                 gh pr diff <N> --color=never | head -c 60000
+            3. For each open issue, decide:
+               - `fully-addresses`: PR's scope CLEARLY covers EVERY symptom
+                 in the issue. Err strictly toward "related" if unsure.
+               - `related`: touches same area / partial fix.
+               - `unrelated`: omit.
+            4. Score template adherence against the PR_TEMPLATE (if present):
+               - Enumerate the `(required)` sections and other section
+                 headers from the template.
+               - Mark each section as filled (non-trivial reporter content)
+                 or missing (empty / placeholder / HTML-comment-only).
+
+          Return ONLY a single JSON object — no fences, no prose:
+
+          {
+            "prNumber": <N>,
+            "candidates": [
+              {
+                "issue": <issueNumber>,
+                "relation": "fully-addresses" | "related",
+                "evidence": "one-sentence justification citing files/symptoms"
+              }
+            ],
+            "templateAdherence": {
+              "sectionsFilled": ["<section titles with real content>"],
+              "sectionsMissing": ["<empty / placeholder section titles>"],
+              "requiredMissing": ["<subset of sectionsMissing that are marked (required)>"],
+              "quality": "good | partial | empty | no-template-context"
+            }
+          }
+
+          `quality` scale:
+          - "good" = required sections all filled AND most non-required too
+          - "partial" = some required sections empty but not all
+          - "empty" = essentially no template content beyond headers
+          - "no-template-context" = caller didn't include PR_TEMPLATE
+
+          No matches: candidates=[]. Always return templateAdherence
+          (may be no-template-context).
+
+          Default bias: when the PR description doesn't explicitly claim
+          to close the issue, mark it `related`, never `fully-addresses`.
+    prompt: |
+      You are the PR-to-issue linker for the repository in the current
+      working directory.
+
+      # Mode check — READ THIS FIRST
+
+      Run once at the start:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_PR_LINK=${SKIP_PR_LINK:-0}"
+
+      If SKIP_PR_LINK=1 — print exactly:
+          "Skipping link-prs per SKIP_PR_LINK=1 — no state read, no gh
+           calls, no comments."
+      and exit immediately. Do not read state, do not call gh, do not
+      use Task. This is the "staged rollout" escape hatch for the first
+      live run of the full workflow.
+
+      If DRY_RUN=1 — READ-ONLY mode:
+        - Do all read-only work (gh list/view/diff, state reads, matching).
+        - For every mutation you WOULD have made (PR/issue comment, state
+          write), print a line prefixed `[DRY] would ...` with the full
+          body you would have posted on which target.
+        - Do NOT run `gh issue comment` or `gh pr comment`. Do NOT use
+          the Write tool on `.archon/state/*.json`.
+        - When delegating via Task to pr-issue-matcher, PREPEND this exact
+          sentence to every Task prompt:
+              "DRY_RUN=1 is active. Run only read-only gh commands."
+          (pr-issue-matcher is already read-only, so this is belt-and-braces.)
+        - End with the standard summary table, but prefix the title
+          `## (DRY RUN) PR-issue linker — <now>`.
+
+      Your job on every (non-dry, non-skipped) run:
+        1. For every open PR not yet fully processed, identify related
+           open issues via the pr-issue-matcher sub-agent.
+        2. Add a `Closes #X` SUGGESTION comment on the PR only when the
+           matcher says the PR fully addresses the issue AND you — the
+           orchestrator — agree after re-reading the issue + PR diff.
+        3. Otherwise post a conservative "related to #X" cross-reference
+           comment on the PR, plus a mirror comment on the issue.
+        4. Persist state to avoid re-commenting on the same link.
+
+      # State file
+
+      Location: `.archon/state/pr-state.json`. `mkdir -p .archon/state`
+      before any write.
+
+      Default shape when missing:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "linkedPrs": {}
+          }
+
+      - `linkedPrs[<prNumber>]`: {
+           sha,                 # digest of title + body + headRefName
+           processedAt,
+           related: [<issueNumber>, ...],
+           fullyAddresses: [<issueNumber>, ...],
+           templateAdherence: { quality, requiredMissing, sectionsFilled, sectionsMissing },
+           templateNudgedAt: "<iso>",   # set only when we posted a template-nudge comment
+           commentIds: {                # bot-comment IDs for everything we posted,
+             fullyAddresses: { "<issue>": "<id>", ... },  #   keyed by target issue.
+             related: {
+               pr:    { "<issue>": "<id>", ... },         # comment on this PR referencing issue
+               issue: { "<issue>": "<id>", ... }          # mirror comment on the issue
+             },
+             templateNudge: "<id>"      # comment on this PR nudging template fill
+           }
+         }
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/pr-state.json 2>/dev/null
+      ```
+      Parse JSON; default on ENOENT.
+
+      ## 2. Fetch
+      ```
+      gh pr list --state open \
+        --json number,title,body,headRefName,author,updatedAt \
+        --limit 100 > "$ARTIFACTS_DIR/prs.json"
+
+      gh issue list --state open \
+        --json number,title,body,labels,author \
+        --limit 200 > "$ARTIFACTS_DIR/issues.json"
+      ```
+
+      Also read the PR template ONCE for the template-adherence check:
+      ```
+      if [ -f .github/pull_request_template.md ]; then
+        cp .github/pull_request_template.md "$ARTIFACTS_DIR/pr-template.md"
+      elif [ -f .github/PULL_REQUEST_TEMPLATE.md ]; then
+        cp .github/PULL_REQUEST_TEMPLATE.md "$ARTIFACTS_DIR/pr-template.md"
+      else
+        : > "$ARTIFACTS_DIR/pr-template.md"   # empty = no template in repo
+      fi
+      ```
+      If the file is empty, skip the entire template-adherence behavior
+      below (matcher returns `quality: "no-template-context"`).
+
+      ## 3. Classify
+      For each open PR:
+        - Compute sha of `title + "\n" + body + "\n" + headRefName`.
+        - If `state.linkedPrs[N]` exists AND its sha matches → SKIP.
+        - Else → needs MATCHING.
+
+      ## 4. MATCH PASS — parallel Task fan-out to pr-issue-matcher
+      Spawn `pr-issue-matcher` in PARALLEL for every PR needing matching
+      (single turn, multiple Task calls).
+
+      Per-task prompt template:
+          "Match PR #<N> against the open issues below.
+           <issues list — one per line: `#<num> <title> — <first 120 chars of body>`>
+
+           <if pr-template.md is non-empty, append:>
+           PR_TEMPLATE (for templateAdherence scoring):
+           <file contents>"
+
+      Keep the issue list compact. Parse each response as JSON. If parsing
+      fails for a given PR, skip it. Preserve the full `templateAdherence`
+      object in `state.linkedPrs[<pr>]` for the digest downstream.
+
+      ## 5. VERIFY PASS — confirm any "fully-addresses"
+      Haiku is optimistic; Sonnet (you) owns the final judgment. For each
+      candidate tagged `fully-addresses`:
+        - Read issue body fully: `gh issue view <issue> --json body,title,labels`
+        - Read PR body + diff:   `gh pr view <pr> --json body,title`
+                                 `gh pr diff <pr> --color=never`
+        - Decide: does the PR's change set plausibly resolve EVERY
+          symptom/ask in the issue body? If ANY part is out of scope,
+          ambiguous, or only partially addressed → DOWNGRADE to `related`.
+
+      When in doubt, downgrade.
+
+      ## 6. ACT PASS — comment + record
+      Before posting ANY comment, check idempotency: fetch existing
+      comments on the target (`gh pr view <pr> --json comments` /
+      `gh issue view <issue> --json comments`) and skip if a comment with
+      the same body already exists.
+
+      For each PR's confirmed candidates:
+
+        - `fully-addresses` (post-verify):
+            - If the PR body does NOT already contain `Closes #<issue>`
+              / `Fixes #<issue>` / `Resolves #<issue>` (case-insensitive):
+              post a PR comment tagging the PR author:
+
+                  "@<pr-author> this PR appears to fully address #<issue>.
+                   Consider adding `Closes #<issue>` to the PR body so
+                   the issue auto-closes on merge."
+
+              Capture the returned comment ID from the `gh pr comment`
+              URL (the number after `#issuecomment-`) and record it:
+                  state.linkedPrs[<pr>].commentIds.fullyAddresses[<issue>] = "<id>"
+
+            - Add <issue> to `state.linkedPrs[<pr>].fullyAddresses`.
+
+        - `related`:
+            - On the PR (tag the PR author):
+                  "@<pr-author> related to #<issue> — overlapping area or partial fix."
+              Capture ID:
+                  state.linkedPrs[<pr>].commentIds.related.pr[<issue>] = "<id>"
+            - On the issue (tag the issue reporter):
+                  "@<issue-reporter> potentially related to PR #<pr>."
+              Capture ID:
+                  state.linkedPrs[<pr>].commentIds.related.issue[<issue>] = "<id>"
+            - Add <issue> to `state.linkedPrs[<pr>].related`.
+
+      On idempotent SKIP (existing comment found), do NOT attempt to
+      extract an ID — leave the slot absent.
+
+      Post sequentially — don't Task-fan-out this step.
+
+      ## 6b. TEMPLATE NUDGE PASS — auto-comment on low-quality PR fills
+
+      ### First-run grandfather guard
+
+      Before the nudge logic, check whether this is the baseline run.
+      Condition: the `state.linkedPrs` object **as read at the start of
+      this run** (step 1) was empty.
+
+      If baseline → DO NOT POST any template-nudge comments this run.
+      Instead, for every PR that WOULD have been nudged, stamp
+      `state.linkedPrs[<pr>].templateNudgedAt = "<first-run-baseline>"`
+      so future runs treat them as already handled. Print a single line:
+
+          [grandfather] baseline run — snapshotting N PRs without posting
+          nudges. Future runs will only nudge new low-quality PRs.
+
+      Skip the entire rest of this step on the baseline run.
+
+      ### Normal nudge logic (second run onward)
+
+      Only runs if `pr-template.md` is non-empty (i.e. the repo HAS a
+      template). For each PR processed this run whose matcher returned
+      `templateAdherence.quality ∈ {"empty", "partial"}` AND whose
+      `requiredMissing` list is non-empty:
+
+        - Skip if `state.linkedPrs[<pr>].templateNudgedAt` already exists
+          (we've nudged before — don't badger the contributor again).
+        - Skip if the PR is marked `draft` (contributors often fill
+          templates later on drafts).
+        - Build the comment:
+
+              Hi @<pr-author> — thanks for opening this PR.
+
+              This repository uses a PR template at
+              `.github/pull_request_template.md` with several required
+              sections. A few of them appear to be empty or placeholder
+              here:
+
+              - <requiredMissing[0]>
+              - <requiredMissing[1]>
+              - ...
+
+              Could you fill those out (even briefly)? The template
+              helps reviewers understand scope, risk, and rollback — it
+              speeds up review significantly.
+
+              If a section genuinely doesn't apply, just write "N/A" in
+              it rather than leaving it blank.
+
+        - Idempotency: `gh pr view <pr> --json comments` — skip if an
+          existing comment already mentions "pull_request_template.md"
+          or starts with the exact greeting.
+        - Post: `gh pr comment <pr> --body "..."`. Capture the comment ID
+          from the returned URL.
+        - Record in state:
+              state.linkedPrs[<pr>].templateNudgedAt = "<now-iso>"
+              state.linkedPrs[<pr>].commentIds.templateNudge = "<id>"
+
+      Do NOT nudge PRs with `quality: "good"` or `"no-template-context"`.
+
+      ## 7. SAVE
+      For every PR processed this run (success or skip), write/refresh
+      `state.linkedPrs[<pr>]` with:
+          { sha, processedAt: <now-iso>, related: [...], fullyAddresses: [...] }
+      Update `state.lastRunAt`. Write `.archon/state/pr-state.json`.
+
+      ## 8. Summary
+          ## PR-issue linker — <now>
+          PRs scanned:                        <N>
+          PRs newly processed:                <N>
+          Fully-addresses suggestions posted: <N>
+          Related cross-refs posted:          <N>
+          Template nudges posted this run:    <N>
+          PR template fill (of PRs processed this run):
+            good=<N>, partial=<N>, empty=<N>, no-template-context=<N>
+
+      # Guardrails
+
+      - NEVER close an issue. GitHub closes issues on merge via the
+        `Closes #X` keyword — that is the only closure path this workflow
+        endorses.
+      - NEVER add `Closes #X` to the PR body yourself; only SUGGEST via a
+        comment. Maintainers decide.
+      - Default to `related`. Only suggest `fully-addresses` when the
+        evidence is overwhelming.
+      - If `gh` errors out (auth, rate limit), abort cleanly and summarise.
+      - State writes are ATOMIC per run — a single Write at step 7.
+      - Parallel Task fan-out is required for the match pass only. Act
+        pass is sequential for idempotent comment-ID capture.
+      - Template nudge comments happen AT MOST ONCE per PR (tracked via
+        `templateNudgedAt`). Never re-nudge — contributors will ignore us.
+
+  # ---------------------------------------------------------------------------
+  # Stale nudge — standalone. For issues and PRs untouched for STALE_DAYS
+  # (default 60), post a gentle "still relevant?" comment. No auto-close —
+  # this is a reminder, not an ultimatum. Tracked in state so we only
+  # nudge each item once per quiet period.
+  # ---------------------------------------------------------------------------
+  - id: stale-nudge
+    model: sonnet
+    allowed_tools: [Bash, Read, Write]
+    prompt: |
+      You post gentle reminders on GitHub issues and PRs that have gone
+      quiet. No auto-close. No Task fan-out needed — this is direct work.
+
+      # Mode check — READ FIRST
+
+      Run once:
+          echo "DRY_RUN=${DRY_RUN:-0} SKIP_STALE_NUDGE=${SKIP_STALE_NUDGE:-0} STALE_DAYS=${STALE_DAYS:-60}"
+
+      If SKIP_STALE_NUDGE=1 — print
+          "Skipping stale-nudge per SKIP_STALE_NUDGE=1"
+      and exit immediately.
+
+      If DRY_RUN=1 — READ-ONLY. Print `[DRY] would ...` for each would-be
+      comment. Do NOT run `gh issue comment` / `gh pr comment`. Do NOT
+      use Write on the state file. End with summary prefixed `## (DRY RUN)`.
+
+      # State file
+
+      Location: `.archon/state/stale-nudge-state.json`.
+      `mkdir -p .archon/state` before any write.
+
+      Default shape:
+
+          {
+            "version": 1,
+            "lastRunAt": null,
+            "nudged": {}
+          }
+
+      - `nudged["issue/<N>" | "pr/<N>"]`: { nudgedAt, updatedAtAtNudge, botCommentId }
+        - Re-nudge allowed only when the item has been updated AFTER
+          `nudgedAt` AND has gone quiet again for ≥ STALE_DAYS. Otherwise
+          skip — don't spam.
+
+      # Step-by-step
+
+      ## 1. Read state
+      ```
+      cat .archon/state/stale-nudge-state.json 2>/dev/null
+      ```
+      Parse JSON; default on ENOENT.
+
+      ## 2. Fetch stale items
+      Compute cutoff (STALE_DAYS ago):
+          DAYS=${STALE_DAYS:-60}
+          CUTOFF=$(date -u -v-${DAYS}d +%Y-%m-%d 2>/dev/null || date -u -d "${DAYS} days ago" +%Y-%m-%d)
+
+      Stale open issues:
+          gh issue list --state open --limit 200 \
+            --json number,title,author,updatedAt,labels \
+            --search "updated:<${CUTOFF}" > "$ARTIFACTS_DIR/stale-issues.json"
+
+      Stale open PRs (skip drafts):
+          gh pr list --state open --limit 100 \
+            --json number,title,author,updatedAt,isDraft \
+            --search "updated:<${CUTOFF}" > "$ARTIFACTS_DIR/stale-prs.json"
+
+      ## 3. Filter
+      For each item:
+        - Skip PRs where `isDraft == true` — drafts are often WIP, nudging
+          them is rude.
+        - Skip any item with a label matching `wontfix`, `blocked`,
+          `needs-maintainer`, `pinned`, `keep-open` (common "do not bother"
+          signals). Check current labels via the fetched JSON.
+        - Skip if `state.nudged["<type>/<N>"]` exists AND the item's
+          `updatedAt` is ≤ `nudgedAt` (nothing has changed since we nudged).
+
+      Everything else is a NEW nudge candidate.
+
+      ## 4. Post nudges (sequential)
+      For each candidate, build the comment body:
+
+        Issues:
+            @<author> this issue has been quiet for <N> days. Is it still
+            relevant? A quick update on current status would help with
+            triage. No reply needed if it's no longer blocking you.
+
+        PRs:
+            @<author> this PR has been quiet for <N> days. Is it still
+            active? Happy to help unblock if review feedback or a rebase
+            is needed — just drop a note.
+
+      Idempotency: `gh {issue,pr} view <N> --json comments` — skip if any
+      existing comment already starts with "this {issue,pr} has been quiet".
+
+      Post: `gh issue comment <N> --body "..."` / `gh pr comment <N> --body "..."`.
+      Capture the comment ID from the returned URL (the number after
+      `#issuecomment-`).
+      Record: `state.nudged["<type>/<N>"] = {
+                nudgedAt: <now-iso>,
+                updatedAtAtNudge: <item.updatedAt>,
+                botCommentId: "<id>"
+              }`
+
+      ## 5. SAVE
+      Set `state.lastRunAt = <now-iso>`. Write
+      `.archon/state/stale-nudge-state.json`.
+
+      ## 6. Summary
+          ## Stale nudge — <now>
+          STALE_DAYS window:             <N>
+          Stale issues found:            <N>
+          Stale PRs found (non-draft):   <N>
+          Filtered out (labels/draft/already-nudged): <N>
+          New nudges posted — issues:    <N>
+          New nudges posted — PRs:       <N>
+
+      # Guardrails
+
+      - NEVER auto-close here. This node is comment-only, always.
+      - Respect "do-not-bother" labels: wontfix, blocked, needs-maintainer,
+        pinned, keep-open. (Add more via PR if missed.)
+      - One nudge per quiet period. Re-nudge only if the item was updated
+        after the prior nudge AND went quiet again.
+      - If `gh` errors out, abort cleanly. State stays atomic.
+
+  # ---------------------------------------------------------------------------
+  # Digest — runs LAST, after every other node. Reads each prior node's
+  # final assistant output via $<nodeId>.output and synthesises one
+  # maintainer-facing report to $ARTIFACTS_DIR/digest.md. Pure synthesis —
+  # no gh calls, no mutations, no Task fan-out.
+  # ---------------------------------------------------------------------------
+  - id: digest
+    depends_on:
+      - triage-issues
+      - link-prs
+      - closed-dedup-check
+      - closed-pr-dedup-check
+      - stale-nudge
+    model: sonnet
+    allowed_tools: [Bash, Read, Write]
+    prompt: |
+      You synthesise the outputs of all prior nodes in this run into one
+      maintainer-facing digest.
+
+      # Inputs
+
+      Each prior node's final summary is available via variable
+      substitution:
+
+      - $triage-issues.output
+      - $link-prs.output
+      - $closed-dedup-check.output
+      - $closed-pr-dedup-check.output
+      - $stale-nudge.output
+
+      Some may include `(DRY RUN)` prefix or a "Skipping … per SKIP_X=1"
+      line — pass those through honestly.
+
+      You may also read the state files under `.archon/state/` for any
+      counts the summaries omitted, but keep it light — this is a digest,
+      not a re-analysis.
+
+      # Comment-URL index — REQUIRED
+
+      The digest MUST include a direct GitHub URL for every bot comment
+      this run posted. Build URLs from state files.
+
+      Steps:
+
+      1. Determine the repo slug:
+             SLUG=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+         (example: `coleam00/Archon`)
+
+      2. URL shape:
+             Issue comment: https://github.com/<slug>/issues/<N>#issuecomment-<id>
+             PR    comment: https://github.com/<slug>/pull/<N>#issuecomment-<id>
+
+      3. Sources to read (all optional — missing files mean that node
+         didn't run OR posted nothing):
+
+         a. `.archon/state/triage-state.json` → `pendingDedupComments`
+            Keyed by OPEN ISSUE number → `issues/<N>#issuecomment-<botCommentId>`.
+
+         b. `.archon/state/closed-dedup-state.json` → `closedMatchComments`
+            Keyed by OPEN ISSUE number → `issues/<N>#issuecomment-<botCommentId>`.
+
+         c. `.archon/state/closed-pr-dedup-state.json` → `closedMatchComments`
+            Keyed by OPEN PR number → `pull/<N>#issuecomment-<botCommentId>`.
+
+         d. `.archon/state/pr-state.json` → `linkedPrs[<pr>].commentIds`:
+              - `fullyAddresses[<issue>]` → comment lives ON THE PR:
+                    `pull/<pr>#issuecomment-<id>`
+              - `related.pr[<issue>]`     → `pull/<pr>#issuecomment-<id>`
+              - `related.issue[<issue>]`  → `issues/<issue>#issuecomment-<id>`
+              - `templateNudge`           → `pull/<pr>#issuecomment-<id>`
+            Note: entries may be absent (idempotent skip or pre-IDs run) —
+            in that case list the action without a URL and suffix
+            `(no ID captured)`.
+
+         e. `.archon/state/stale-nudge-state.json` → `nudged`
+            Keys: `"issue/<N>"` → `issues/<N>#issuecomment-<botCommentId>`
+                  `"pr/<N>"`    → `pull/<N>#issuecomment-<botCommentId>`
+
+      4. Include the URLs BOTH inline in the per-node sections (next to
+         the issue/PR number it acted on) AND in a dedicated "Comment
+         index" section at the end grouped by category.
+
+      5. Only surface comments posted IN THIS RUN. Use the `postedAt` /
+         `nudgedAt` timestamps: include entries whose timestamp equals
+         today's run window (≥ this run's start time). Older entries
+         from prior runs should NOT re-appear in the "just posted" tables
+         but DO appear in a separate "carry-forward pending" table so
+         maintainers see what's still on the 3-day clock.
+
+      # Output
+
+      Produce ONE markdown document. Write it to `$ARTIFACTS_DIR/digest.md`
+      using the Write tool. Then print the SAME content to stdout.
+
+      Template:
+
+          # Repo-triage digest — <now-iso>
+
+          _(Dry run)_   ← include this line only if ANY node ran with DRY_RUN=1
+
+          ## Headline numbers
+
+          | Action | Count |
+          |---|---|
+          | Labels applied | N |
+          | New duplicate clusters (open↔open) | N |
+          | New closed-match candidates (open issue ↔ closed issue) | N |
+          | Issues auto-closed this run | N |
+          | PR template nudges posted | N |
+          | Stale nudges (issues) | N |
+          | Stale nudges (PRs) | N |
+          | PR `Closes #X` suggestions posted | N |
+          | PR/issue "related to" cross-refs posted | N |
+          | Open PR vs closed PR duplicate comments | N |
+
+          ## Per-node summaries
+
+          ### triage-issues
+          <verbatim $triage-issues.output, trimmed of log noise>
+
+          ### link-prs
+          <verbatim>
+
+          ### closed-dedup-check
+          <verbatim>
+
+          ### closed-pr-dedup-check
+          <verbatim>
+
+          ### stale-nudge
+          <verbatim>
+
+          ## Template-fill snapshot
+
+          From this run's processed items:
+          - Issues: good=<N>, partial=<N>, empty=<N>, no-template=<N>
+          - PRs:    good=<N>, partial=<N>, empty=<N>, no-template=<N>
+
+          ## Comment index — this run
+
+          Every URL below was posted by this run. Click to jump to the
+          comment on GitHub.
+
+          ### Dedup warnings (open ↔ open) — 3-day clock
+          - #<openIssue> → duplicate of #<canonical> — [comment](https://github.com/<slug>/issues/<N>#issuecomment-<id>)
+
+          ### Closed-issue matches — 3-day clock
+          - #<openIssue> → matched closed #<closedIssue> (<stateReason>) — [comment](URL)
+
+          ### Closed-PR duplicates (info only, no clock)
+          - PR #<openPr> → matched #<closedPr> (<merged|closed unmerged>) — [comment](URL)
+
+          ### PR `Closes #X` suggestions
+          - PR #<pr> → suggest `Closes #<issue>` — [comment](URL)
+
+          ### Related cross-refs
+          - PR #<pr> ↔ issue #<issue>
+            - on PR: [comment](URL)
+            - on issue: [comment](URL)
+
+          ### PR template nudges
+          - PR #<pr> — [comment](URL)
+
+          ### Stale nudges
+          - Issue #<N> — [comment](URL)
+          - PR #<N> — [comment](URL)
+
+          (Omit any section whose list is empty rather than printing a
+          header with "none".)
+
+          ## Carry-forward — still on the 3-day clock from prior runs
+
+          Items whose `postedAt` is OLDER than this run but still pending
+          (no reporter reply yet, not yet auto-closed):
+
+          - #<N> → #<canonical> — posted <ISO>, <days> day(s) elapsed, [comment](URL)
+
+          (Omit the whole section if nothing is pending.)
+
+          ## Pending (waiting on human)
+
+          - Duplicate warnings awaiting reporter reply: <list #N>
+          - Closed-match warnings awaiting reporter reply: <list #N>
+          - PR template nudges sent this run: <list #PR>
+
+          ## Next scheduled run considerations
+
+          - Any items the human should look at before the next run
+            (ambiguous clusters, PR template edge cases, etc.) — 1-3 bullets
+            max. Empty section is fine.
+
+      Keep the digest scannable — a maintainer should be able to assess
+      "did anything need my attention?" in under 30 seconds.
+
+      # Guardrails
+
+      - No gh calls here. No comments. No closes. Synthesis only.
+      - If any prior node's output is missing or mangled, note it in the
+        corresponding section: "(output unavailable)". Don't invent numbers.
+      - Preserve `(DRY RUN)` markers — readers need to know if counts are
+        hypothetical.
diff --git a/.gitignore b/.gitignore
index a2f33c5d5c..5d21706265 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,9 @@ e2e-screenshots/
 .archon/logs/
 .archon/artifacts/
 
+# Cross-run workflow state (e.g. issue-triage memory)
+.archon/state/
+
 # Agent artifacts (generated, local only)
 .agents/
 .agents/rca-reports/

From ce3c74574f1bec521e6e68ef95082a07efb6a2da Mon Sep 17 00:00:00 2001
From: Rasmus Widing <rasmus.widing@gmail.com>
Date: Mon, 20 Apr 2026 09:29:03 +0300
Subject: [PATCH 2/3] feat(workflows/repo-triage): post digest to Slack when
 SLACK_WEBHOOK is set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extends the digest node with an optional Slack-post step after the
canonical digest.md artifact is written. Uses Slack incoming webhook
(no bot token required beyond the incoming-webhook scope).

Behavior:
- SLACK_WEBHOOK unset → skipped silently with a one-line note
- DRY_RUN=1 → prints full payload, does not curl
- Otherwise → POSTs a compact (<3500 char) mrkdwn-formatted summary
  containing headline numbers, this-run comment index (clickable
  GitHub URLs), pending items, and a path reference to digest.md
- curl failure or non-ok Slack response is logged but does not fail
  the node — digest.md on disk remains authoritative
- Intermediate Slack text written to $ARTIFACTS_DIR/digest-slack.txt
  for traceability; payload JSON assembled via jq and written to
  $ARTIFACTS_DIR/slack-payload.json before curl posts it

Slack mrkdwn conversion rules baked into the prompt (no tables, link
shape <url|text>, single-asterisk bold) so Sonnet emits a variant
that renders cleanly in Slack rather than being sent raw.

The webhook URL is read from the operator's environment (Archon
auto-loads ~/.archon/.env on CLI startup — put SLACK_WEBHOOK=... there).
---
 .archon/workflows/repo-triage.yaml | 100 +++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/.archon/workflows/repo-triage.yaml b/.archon/workflows/repo-triage.yaml
index 0928f3f3d8..f146627908 100644
--- a/.archon/workflows/repo-triage.yaml
+++ b/.archon/workflows/repo-triage.yaml
@@ -1330,6 +1330,104 @@ nodes:
       Keep the digest scannable — a maintainer should be able to assess
       "did anything need my attention?" in under 30 seconds.
 
+      # Post to Slack (optional)
+
+      AFTER writing `digest.md`, check the env:
+
+          echo "SLACK_WEBHOOK=${SLACK_WEBHOOK:-<unset>}"
+
+      If `SLACK_WEBHOOK` is unset or empty → print
+          "Slack post skipped: SLACK_WEBHOOK not set."
+      and finish. This is the normal path when Slack isn't wired.
+
+      If set, prepare a COMPACT Slack-flavoured variant and post it to
+      the webhook. Rules:
+
+      ## Length budget
+
+      Keep the Slack payload under ~3,500 characters. The full digest
+      stays on disk at `$ARTIFACTS_DIR/digest.md`; Slack gets a summary
+      + the comment-URL index. Never send the whole digest.md to Slack.
+
+      ## Slack mrkdwn rules (NOT standard Markdown)
+
+      - Bold: `*bold*` (NOT `**bold**`)
+      - Italics: `_italic_`
+      - Links: `<https://url|text>` (NOT `[text](url)`)
+      - Lists: use `•` or `-` at line start — no numbered lists
+      - No `##` headers — use a `*Bold line*` instead
+      - No tables — convert to bulleted key/value lines
+      - Code: single-backtick inline, triple-backtick blocks
+
+      ## Payload shape
+
+      Write the Slack text to `$ARTIFACTS_DIR/digest-slack.txt` FIRST
+      (so it lands as a traceable artifact), then read it back into a
+      JSON payload via `jq`:
+
+      ```
+      jq -cn --rawfile t "$ARTIFACTS_DIR/digest-slack.txt" \
+        '{text: $t, mrkdwn: true}' > "$ARTIFACTS_DIR/slack-payload.json"
+      ```
+
+      ## Template for the Slack text
+
+      ```
+      *Repo-triage digest — <now-iso>*
+      <if dry run: _(dry run — no mutations)_>
+
+      *Headline*
+      • Labels applied: <N>
+      • Dedup clusters (open↔open): <N>
+      • Closed-issue matches: <N>
+      • Auto-closed: <N>
+      • PR `Closes #X` suggestions: <N>
+      • Related cross-refs: <N>
+      • Closed-PR duplicates: <N>
+      • PR template nudges: <N>
+      • Stale nudges: <N>
+
+      *Comments posted this run*  (click to jump to GitHub)
+      • #<N> dup of #<canon> → <https://github.com/<slug>/issues/<N>#issuecomment-<id>|comment>
+      • #<N> may be resolved by #<closed> → <URL|comment>
+      • PR #<N> `Closes #<X>` → <URL|comment>
+      • (list every comment — if the total would push past 3,500 chars,
+         collapse the largest category to a single line:
+         "...plus N more related cross-refs")
+
+      *Pending* (3-day clock running)
+      • #<N> → #<canonical>, <M>d elapsed
+      • PR #<N> → closed #<X>
+
+      *Full digest:* `$ARTIFACTS_DIR/digest.md`
+      ```
+
+      Omit sections whose list is empty — don't print a header followed
+      by "none".
+
+      ## Posting
+
+      If `DRY_RUN=1`:
+          Print `[DRY] would POST to Slack (<bytes> chars):` followed by
+          the full payload text. Do NOT curl.
+
+      Otherwise:
+          curl -sS -X POST -H 'Content-Type: application/json' \
+            --data "@$ARTIFACTS_DIR/slack-payload.json" \
+            "$SLACK_WEBHOOK"
+
+      Capture stdout+stderr. Slack returns `ok` on success, otherwise an
+      error body like `invalid_payload` / `channel_not_found`.
+
+      ## Failure handling
+
+      Slack posting is a side channel, not the source of truth. If curl
+      fails (non-zero exit, non-`ok` body), log the error to stdout but
+      do NOT fail the node — the digest.md on disk is authoritative.
+      Append a line to the node's stdout:
+
+          Slack post FAILED: <curl error or Slack response body>
+
       # Guardrails
 
       - No gh calls here. No comments. No closes. Synthesis only.
@@ -1337,3 +1435,5 @@ nodes:
         corresponding section: "(output unavailable)". Don't invent numbers.
       - Preserve `(DRY RUN)` markers — readers need to know if counts are
         hypothetical.
+      - Slack posting is best-effort; digest.md on disk is the source
+        of truth.

From 882414e7664011af662ce0d7b4e9c008eb440cca Mon Sep 17 00:00:00 2001
From: Rasmus Widing <rasmus.widing@gmail.com>
Date: Mon, 20 Apr 2026 11:33:52 +0300
Subject: [PATCH 3/3] fix(workflows/repo-triage): address PR #1293 review
 feedback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Critical (3):
- `gh issue close --reason "not planned"` (space, not underscore) — the
  CLI expects lowercase with a space; `not_planned` fails at runtime.
  Fixed in both auto-close paths (triage-issues step 8, closed-dedup-
  check step 7).
- link-prs step 7 state save was sparse `{ sha, processedAt, related,
  fullyAddresses }`, overwriting `commentIds` / `templateNudgedAt` /
  `templateAdherence`. Changed to explicit merge that spreads existing
  entry first so per-run captured fields survive.
- Corrupt-JSON state files previously treated as first-run default
  (silent `pendingDedupComments` reset → 3-day clock restarts forever).
  All five state-load sites now abort loudly on JSON.parse throw;
  ENOENT/empty continue to default-shape.

Important (7):
- Sub-agents (`brief-gen`, `closed-brief-gen`, `pr-brief-gen`,
  `pr-issue-matcher`) emit `ERROR: <reason>` on gh failures rather than
  partial/fabricated JSON. Orchestrator detects the sentinel, logs the
  failed ID + first 200 chars of raw response, tracks in a failed-list,
  and aborts the cluster/match pass if ≥50% of items failed (avoids
  acting on bad data).
- `pr-brief-gen` now sets `diffTruncated: true` when the 30k-char diff
  cap hits; link-prs verify pass downgrades any `fully-addresses` claim
  to `related` when either side's brief was truncated.
- 3-day auto-close validates `postedAt` parses as ISO-8601 before the
  elapsed-time comparison; corrupt timestamps are logged and skipped,
  never acted on.
- `gh issue close` failure path no longer drops state — sets
  `closeAttemptFailed: true` on the entry for next-run retry. Only
  drops on exit 0.
- `closed-pr-dedup-check` idempotency check (`gh pr view --json comments`)
  now aborts the post on fetch failure rather than falling through —
  prevents double-posts on gh hiccups.
- `triage-agent` label pass has preflight `test -f` check for
  `.claude/agents/triage-agent.md`; skips the pass with a clear log if
  the file is missing rather than firing Task calls that fail obscurely.
- `brief-gen` template-adherence wording flipped from "Ignore … as
  'filled'" (ambiguous, read as affirmative) to explicit "A section
  counts as MISSING when …", matching the `pr-issue-matcher` phrasing.

Minor:
- `stale-nudge` idempotency check uses substring "has been quiet for"
  instead of a prefix check that never matched (posted body starts
  with @<author>).
- `closed-dedup-check` distinguishes "upstream crashed" (missing/corrupt
  triage-state.json, or `lastRunAt == null`) from "legitimately quiet
  day" (state present, briefs empty) — different log lines.
- Slack curl adds `-w "\nHTTP_STATUS:%{http_code}"` + `2>&1` so TLS /
  4xx / 5xx errors are visible in captured output.
- `stateReason` values from `gh issue view --json stateReason` are
  UPPERCASE (`COMPLETED`, `NOT_PLANNED`); documented and instruct
  sub-agent to normalize to lowercase for consistency.

Docs:
- CLAUDE.md repo-level `.archon/` tree now lists `state/`.
- archon-directories.md tree adds `state/` + `scripts/` (both were
  missing) with purpose descriptions.

Deferred (worth doing as a follow-up, not blocking):
- DRY/SKIP preamble duplication (~30-50 lines across 5 nodes).
- Explicit `BASELINE_IS_EMPTY` capture in link-prs (current derived
  check works but is a load-bearing model instruction).
- Digest `WARNING` prefix block when upstream nodes are missing
  outputs — today's "(output unavailable)" sub-line is functional.
- Pre-existing README workflow-count (17 → 20) and table gaps — not
  caused by this PR.
---
 .archon/workflows/repo-triage.yaml            | 213 +++++++++++++++---
 CLAUDE.md                                     |   1 +
 .../docs/reference/archon-directories.md      |   4 +
 3 files changed, 183 insertions(+), 35 deletions(-)

diff --git a/.archon/workflows/repo-triage.yaml b/.archon/workflows/repo-triage.yaml
index f146627908..30d1520b98 100644
--- a/.archon/workflows/repo-triage.yaml
+++ b/.archon/workflows/repo-triage.yaml
@@ -51,10 +51,19 @@ nodes:
           - `quality: "good"` = most template sections have real content.
           - `quality: "partial"` = headers present but several sections look blank/placeholder.
           - `quality: "empty"` = body has nothing matching the template shape.
-          - Ignore whitespace / HTML comment placeholders like `<!-- ... -->` as "filled".
+          - A section counts as MISSING when its body is empty, whitespace-only,
+            or contains only HTML-comment placeholders like `<!-- ... -->`.
+            Such sections must go in `sectionsMissing`, NOT `sectionsFilled`.
 
           Be terse. If the issue body is empty, set area='unknown' and
           quality='empty'.
+
+          ERROR HANDLING — if the `gh issue view` call fails (auth,
+          rate limit, network, or non-zero exit), do NOT emit JSON.
+          Instead print exactly one line on stdout:
+              ERROR: <one-line reason>
+          The orchestrator detects the `ERROR:` prefix and handles it
+          (logs, counts, may abort). Never emit partial/fabricated JSON.
     prompt: |
       You are the issue-triage orchestrator for the repository in the
       current working directory.
@@ -117,7 +126,17 @@ nodes:
       ```
       cat .archon/state/triage-state.json 2>/dev/null
       ```
-      Parse as JSON. On ENOENT or empty, start from the default shape above.
+      Parse handling:
+        - ENOENT (file missing) → start from default shape above.
+        - Empty file (zero bytes / whitespace only) → start from default shape.
+        - JSON.parse THROWS (corrupt state) → ABORT the node loudly.
+          Print: `[triage-issues] ABORT: .archon/state/triage-state.json
+          is corrupt — refusing to reset tracked state. Restore from a
+          backup (check git history if tracked, or a local timestamped
+          copy) or delete the file to start fresh.`
+          Then stop the node with a non-zero status. Do NOT fall through
+          to default — that would silently reset `pendingDedupComments`
+          and restart the 3-day auto-close clock indefinitely.
 
       ## 2. Fetch all open issues
       ```
@@ -143,6 +162,18 @@ nodes:
           → needs BRIEF. Otherwise reuse the cached brief.
 
       ## 4. LABEL PASS — parallel fan-out to triage-agent
+
+      PREFLIGHT: verify the on-disk sub-agent definition exists before
+      attempting any Task call:
+
+          test -f .claude/agents/triage-agent.md
+
+      If missing, SKIP the whole label pass (do not attempt Task calls
+      that would fail obscurely at runtime). Log:
+          "[triage-issues] label pass skipped: .claude/agents/triage-agent.md
+           missing — install the skill-adjacent agent file to enable labeling."
+      Continue to the brief pass — labeling is a nice-to-have, not a blocker.
+
       Spawn the existing on-disk `triage-agent` sub-agent in PARALLEL (a
       single assistant turn with multiple Task tool calls — this matters
       for speed). Per-task prompt:
@@ -168,9 +199,20 @@ nodes:
       If `$ARTIFACTS_DIR/issue-templates.md` is empty, omit the template
       block — brief-gen will return `quality: "no-template-context"`.
 
-      Parse each response as JSON. If parsing fails, skip that issue.
-      Merge results into `state.briefs[N]` with a freshly computed sha
-      and `briefedAt = now-iso`. Preserve the `templateAdherence` field.
+      Parse each response as JSON. On parse failure OR when the response
+      starts with `ERROR:` (sub-agent signalling a gh/auth/rate-limit
+      problem — see brief-gen prompt):
+        - Log the failed issue number and the first 200 chars of the
+          raw response.
+        - Track in a `failedBriefs` array for the summary (`failed=N`
+          with the list of numbers).
+        - Do NOT merge into state (keep the previous cached brief).
+      Merge successful results into `state.briefs[N]` with a freshly
+      computed sha and `briefedAt = now-iso`. Preserve `templateAdherence`.
+
+      If `failedBriefs.length > 0` AND the failures look systemic
+      (≥50% of briefs this run failed), ABORT before the cluster pass
+      — a broken briefing run produces bad clusters. Report the counts.
 
       ## 6. CLUSTER PASS — detect duplicates
       Using fresh + cached briefs:
@@ -214,12 +256,20 @@ nodes:
           the cached bot login.
         - If ANY non-bot reply after `postedAt` → drop entry from state
           (humans are engaged).
+        - VALIDATE `postedAt` parses as ISO-8601 first. If it doesn't
+          parse (corrupt state), LOG and SKIP this entry — do NOT close
+          on a bad timestamp, do NOT skip silently. Leave the entry in
+          state for operator review.
         - Else if `now - postedAt >= 3 days`:
             - Post closing comment on #N:
                   "Auto-closing: no reply within 3 days of the duplicate
                    check. Please reopen if this is still relevant."
-            - `gh issue close <N> --reason not_planned`
-            - Drop entry from state.
+            - `gh issue close <N> --reason "not planned"` — capture
+              exit code. If non-zero (network, rate limit, issue
+              already-closed-elsewhere), DO NOT drop state: set
+              `closeAttemptFailed: true` on the entry for retry next
+              run, and log the failure.
+            - ONLY drop entry from state on close success (exit 0).
         - Else → keep the entry as-is (will be revisited next run).
 
       ## 9. SAVE
@@ -293,12 +343,17 @@ nodes:
             "primarySymptom": "one short sentence — the core symptom",
             "area": "single best-guess area tag (same vocabulary as open briefs)",
             "closedAt": "<ISO timestamp>",
-            "stateReason": "completed | not_planned | duplicate | null",
+            "stateReason": "completed | not_planned | duplicate | null (normalize gh CLI's UPPERCASE output to lowercase)",
             "resolvedByPr": "<PR number if identifiable from closing thread, else null>"
           }
 
-          Be terse. If `stateReason` is `not_planned` or `duplicate`, that
-          matters for the match verdict downstream — include it honestly.
+          Be terse. If `stateReason` (normalized to lowercase) is
+          `not_planned` or `duplicate`, that matters for the match
+          verdict downstream — include it honestly.
+
+          ERROR HANDLING — if `gh issue view` fails, print exactly:
+              ERROR: <one-line reason>
+          on a single stdout line. Do NOT emit partial/fabricated JSON.
     prompt: |
       You check whether any currently OPEN issue duplicates a recently
       CLOSED one. A reporter may have filed a bug that was fixed months
@@ -336,9 +391,19 @@ nodes:
             "pendingDedupComments": { ... }
           }
 
-      If the file is missing or `briefs` is empty, print
-          "No open-issue briefs available from triage-issues — skipping."
-      and exit. (This guards against a failed upstream.)
+      Distinguish "upstream didn't run / crashed" from "upstream ran
+      with nothing to process" via `lastRunAt`:
+
+        - File missing OR JSON.parse throws → treat as upstream-crashed.
+          Print: "[closed-dedup-check] SKIP: triage-state.json missing
+          or corrupt — upstream triage-issues node likely failed. Fix
+          that run before retrying."
+        - File present with `lastRunAt == null` → same upstream-crashed
+          message.
+        - File present with `lastRunAt` set AND `briefs` empty → print
+          "No open-issue briefs to cross-match — nothing to do." and exit.
+          (This is a legitimate quiet day.)
+        - Otherwise → proceed.
 
       # State file (this node)
 
@@ -363,7 +428,11 @@ nodes:
 
       ## 1. Read both state files
       - Read `.archon/state/triage-state.json` — grab `briefs` (open-issue briefs).
-      - Read `.archon/state/closed-dedup-state.json` — default on ENOENT.
+      - Read `.archon/state/closed-dedup-state.json`:
+          ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+          (same rule as triage-issues step 1: never silently reset
+          tracked state; corrupt file means a backup restore or explicit
+          deletion, never a reset).
 
       ## 2. Fetch recently-closed issues (last 90 days)
       Compute cutoff:
@@ -374,8 +443,11 @@ nodes:
             --json number,title,body,labels,stateReason,closedAt \
             --search "closed:>${CUTOFF}" > "$ARTIFACTS_DIR/closed-issues.json"
 
-      Filter out any closed issue whose `stateReason` is `duplicate` — those
-      are noise for our matching (they were already dedup'd against canonical).
+      Filter out any closed issue whose `stateReason` (case-insensitive) matches `duplicate`
+      — those are noise for our matching (they were already dedup'd against canonical).
+      Note: `gh issue view --json stateReason` returns UPPERCASE (`COMPLETED`, `NOT_PLANNED`,
+      `DUPLICATE`), while the `gh issue close --reason` flag wants lowercase with a space
+      (`"completed"`, `"not planned"`). Lowercase-compare downstream.
 
       ## 3. Classify work
       For each closed issue:
@@ -389,8 +461,10 @@ nodes:
 
           "Brief closed issue #<N>."
 
-      Parse each JSON response. On parse failure, skip that issue. Merge
-      into `state.closedBriefs`.
+      Parse each JSON response. On parse failure OR `ERROR:` sentinel:
+      log the issue number + first 200 chars, track in `failedClosedBriefs`,
+      skip. Merge successes into `state.closedBriefs`. Abort the cluster
+      pass if ≥50% failed (same rule as triage-issues).
 
       ## 5. CROSS-CLUSTER PASS — match open vs closed
       For each OPEN issue brief (from triage-state.json):
@@ -439,12 +513,17 @@ nodes:
         - Fetch: `gh issue view <O> --json comments`
         - Find comments AFTER `postedAt` whose author is NOT the bot.
         - If reporter replied → drop entry (engaged).
+        - VALIDATE `postedAt` parses as ISO-8601 first. If not: log and
+          skip this entry; never close on a bad timestamp.
         - Else if `now - postedAt >= 3 days`:
             - Post closing comment:
                   "Auto-closing: no reply within 3 days of the closed-match
                    check. Please reopen if your case is NOT resolved by
                    #<matchedClosed>."
-            - `gh issue close <O> --reason not_planned`
+            - `gh issue close <O> --reason "not planned"` — capture exit
+              code. On non-zero: set `closeAttemptFailed: true` on the
+              entry for retry, log the failure, do NOT drop state.
+            - Only drop entry on exit 0.
             - Drop entry from state.
         - Else → keep as-is.
 
@@ -516,6 +595,15 @@ nodes:
 
           Be terse. Don't quote commit messages verbatim unless they are
           the only information available.
+
+          If the diff was truncated (you hit the 30,000-char limit when
+          reading `gh pr diff`), set `diffTruncated: true` on the brief
+          output so the orchestrator knows to be more conservative about
+          `fully-addresses` claims.
+
+          ERROR HANDLING — if `gh pr view` or `gh pr diff` fails, print:
+              ERROR: <one-line reason>
+          on a single stdout line. Do NOT emit partial/fabricated JSON.
     prompt: |
       You find OPEN PRs that duplicate or supersede a recently-CLOSED PR.
       A contributor may have missed that a similar change was already
@@ -563,7 +651,10 @@ nodes:
       ```
       cat .archon/state/closed-pr-dedup-state.json 2>/dev/null
       ```
-      Parse JSON; default on ENOENT.
+      Parse JSON:
+        ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+        (never silently reset tracked state; corrupt file means a backup
+        restore or explicit deletion, never a reset).
 
       ## 2. Fetch PRs
       Compute the cutoff:
@@ -597,8 +688,10 @@ nodes:
       Per-task prompt template:
           "Brief PR #<N> — state=<open|closed>."
 
-      Parse each JSON response. Skip on parse failure. Merge into the
-      appropriate `{open,closed}Briefs` bucket.
+      Parse each JSON response. On parse failure OR `ERROR:` sentinel:
+      log the PR number + first 200 chars, track in `failedBriefs`, skip.
+      Merge successes into the appropriate `{open,closed}Briefs` bucket.
+      Abort the cluster pass if ≥50% failed.
 
       ## 5. CROSS-CLUSTER PASS — match open vs closed
       For each OPEN PR brief:
@@ -631,8 +724,11 @@ nodes:
                  closed on <date> (<stateReason>). You may want to read
                  the discussion there before pushing further."
 
-        - Idempotency: fetch `gh pr view <O> --json comments` and skip if
-          a comment with the same body already exists.
+        - Idempotency: fetch `gh pr view <O> --json comments`. If the
+          fetch fails (non-zero exit), SKIP POSTING and log the error —
+          never fall through to post-anyway (that would double-post on
+          every gh hiccup). Only when the fetch succeeds AND no existing
+          comment has the same body do we proceed.
 
         - Post: `gh pr comment <O> --body "..."`. Capture comment ID.
 
@@ -743,6 +839,10 @@ nodes:
 
           Default bias: when the PR description doesn't explicitly claim
           to close the issue, mark it `related`, never `fully-addresses`.
+
+          ERROR HANDLING — if `gh pr view` or `gh pr diff` fails, print:
+              ERROR: <one-line reason>
+          on a single stdout line. Do NOT emit partial/fabricated JSON.
     prompt: |
       You are the PR-to-issue linker for the repository in the current
       working directory.
@@ -819,7 +919,10 @@ nodes:
       ```
       cat .archon/state/pr-state.json 2>/dev/null
       ```
-      Parse JSON; default on ENOENT.
+      Parse JSON:
+        ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+        (never silently reset tracked state; corrupt file means a backup
+        restore or explicit deletion, never a reset).
 
       ## 2. Fetch
       ```
@@ -863,9 +966,12 @@ nodes:
            PR_TEMPLATE (for templateAdherence scoring):
            <file contents>"
 
-      Keep the issue list compact. Parse each response as JSON. If parsing
-      fails for a given PR, skip it. Preserve the full `templateAdherence`
-      object in `state.linkedPrs[<pr>]` for the digest downstream.
+      Keep the issue list compact. Parse each response as JSON. On parse
+      failure OR `ERROR:` sentinel: log the PR number + first 200 chars,
+      track in `failedMatches`, skip that PR. Preserve the full
+      `templateAdherence` object in `state.linkedPrs[<pr>]` for the
+      digest downstream. Abort the downstream passes if ≥50% of PRs
+      failed matching (same half-failure rule as the briefing passes).
 
       ## 5. VERIFY PASS — confirm any "fully-addresses"
       Haiku is optimistic; Sonnet (you) owns the final judgment. For each
@@ -879,6 +985,12 @@ nodes:
 
       When in doubt, downgrade.
 
+      Additional rule for PR-vs-closed-PR matches (`closed-pr-dedup-check`
+      feeds this pattern too): if either side's brief has
+      `diffTruncated: true`, the evidence is partial — downgrade any
+      `fully-addresses`-shaped claim to `related` by default, since we
+      can't be confident about unseen diff regions.
+
       ## 6. ACT PASS — comment + record
       Before posting ANY comment, check idempotency: fetch existing
       comments on the target (`gh pr view <pr> --json comments` /
@@ -979,10 +1091,28 @@ nodes:
       Do NOT nudge PRs with `quality: "good"` or `"no-template-context"`.
 
       ## 7. SAVE
-      For every PR processed this run (success or skip), write/refresh
-      `state.linkedPrs[<pr>]` with:
-          { sha, processedAt: <now-iso>, related: [...], fullyAddresses: [...] }
-      Update `state.lastRunAt`. Write `.archon/state/pr-state.json`.
+      For every PR processed this run (success or skip), MERGE into
+      the existing `state.linkedPrs[<pr>]` entry (do NOT replace — that
+      would lose `commentIds` / `templateNudgedAt` / `templateAdherence`
+      captured earlier in this run AND the baseline grandfather flag).
+
+      Merge semantics (spread existing first, then apply this run's updates):
+
+          const existing = state.linkedPrs[<pr>] ?? {};
+          state.linkedPrs[<pr>] = {
+            ...existing,                              // preserves commentIds, templateNudgedAt,
+                                                       // templateAdherence, any prior sha history
+            sha: <new-sha>,
+            processedAt: <now-iso>,
+            related: <this-run-related-array>,
+            fullyAddresses: <this-run-fullyAddresses-array>,
+            templateAdherence: <this-run-adherence-or-existing>,
+            // any commentIds/templateNudgedAt captured during steps 6 + 6b
+            // are already in `existing` and survive the spread
+          };
+
+      Update `state.lastRunAt`. Write `.archon/state/pr-state.json` in
+      ONE Write call at the end of the node.
 
       ## 8. Summary
           ## PR-issue linker — <now>
@@ -1060,7 +1190,10 @@ nodes:
       ```
       cat .archon/state/stale-nudge-state.json 2>/dev/null
       ```
-      Parse JSON; default on ENOENT.
+      Parse JSON:
+        ENOENT / empty → default shape. JSON.parse throw → ABORT loudly
+        (never silently reset tracked state; corrupt file means a backup
+        restore or explicit deletion, never a reset).
 
       ## 2. Fetch stale items
       Compute cutoff (STALE_DAYS ago):
@@ -1103,7 +1236,10 @@ nodes:
             is needed — just drop a note.
 
       Idempotency: `gh {issue,pr} view <N> --json comments` — skip if any
-      existing comment already starts with "this {issue,pr} has been quiet".
+      existing comment CONTAINS the substring "has been quiet for" (a
+      prefix check fails because the posted body starts with `@<author>`,
+      not the phrase). If the fetch itself fails, SKIP POSTING rather
+      than fall through to post-anyway.
 
       Post: `gh issue comment <N> --body "..."` / `gh pr comment <N> --body "..."`.
       Capture the comment ID from the returned URL (the number after
@@ -1414,7 +1550,14 @@ nodes:
       Otherwise:
           curl -sS -X POST -H 'Content-Type: application/json' \
             --data "@$ARTIFACTS_DIR/slack-payload.json" \
-            "$SLACK_WEBHOOK"
+            -w "\nHTTP_STATUS:%{http_code}\n" \
+            "$SLACK_WEBHOOK" 2>&1
+
+      The `-w "\nHTTP_STATUS:%{http_code}"` appends the HTTP status code
+      so TLS/connection/4xx/5xx errors are visible in the captured output.
+      Redirect stderr to stdout (`2>&1`) so TLS errors land in the same
+      stream. Slack returns `ok` (body) + `HTTP_STATUS:200` on success.
+      Treat anything else as failure.
 
       Capture stdout+stderr. Slack returns `ok` on success, otherwise an
       error body like `invalid_payload` / `channel_not_found`.
diff --git a/CLAUDE.md b/CLAUDE.md
index ed72a6f148..ac8e10b28c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -565,6 +565,7 @@ curl http://localhost:3637/api/conversations/<conversationId>/messages
 ├── commands/       # Custom commands
 ├── workflows/      # Workflow definitions (YAML files)
 ├── scripts/        # Named scripts for script: nodes (.ts/.js for bun, .py for uv)
+├── state/          # Cross-run workflow state (gitignored — never in git)
 └── config.yaml     # Repo-specific configuration
 ```
 
diff --git a/packages/docs-web/src/content/docs/reference/archon-directories.md b/packages/docs-web/src/content/docs/reference/archon-directories.md
index a718824c3a..b0b04f5df2 100644
--- a/packages/docs-web/src/content/docs/reference/archon-directories.md
+++ b/packages/docs-web/src/content/docs/reference/archon-directories.md
@@ -51,12 +51,16 @@ any-repo/.archon/
 │   └── execute.md
 ├── workflows/                # Workflow definitions (YAML files)
 │   └── pr-review.yaml
+├── scripts/                  # Named scripts for script: nodes (.ts/.js for bun, .py for uv)
+├── state/                    # Cross-run workflow state (gitignored)
 └── config.yaml               # Repo-specific configuration
 ```
 
 **Purpose:**
 - `commands/` - Slash commands (auto-loaded on clone)
 - `workflows/` - YAML workflow definitions, discovered recursively at runtime
+- `scripts/` - Named scripts referenced by `script:` nodes
+- `state/` - Cross-run memory written by workflows (e.g. `repo-triage` dedup state). Gitignored; never committed.
 - `config.yaml` - Project-specific settings
 
 ### Docker: `/.archon/`