fix(#136): memory pipeline hardening + issue relinking (#135)

[alexosugo]

Description

Two related pieces of work on the memory distillation pipeline:

#135 — Issue resolution and relinking: replaces the buggy pr.prNumber-as-issue-number aliasing with proper GitHub issue resolution via closingIssuesReferences + title scope + body keywords, plus a one-off relink-issues tool to repair previously mislinked drafts.

#136 — Memory pipeline hardening (first-run post-mortem follow-through):

• CI guard rejecting mislinked/slug-contradicting drafts
• Cross-domain dedup (dedupeByIssueId) collapsing backport/multi-PR duplicates into a single canonical draft
• Prompt hardening (CONSTRAINTS block) and HTML boilerplate stripping
• Adaptive issue-body budget for near-empty PRs
• Confidence gradient replacing hardcoded 'medium'
• Per-run reconciliation report
• Unambiguous slug separator between conventional-commit type and issue number
• Fix for dedupeByIssueId's sort comparator: returned NaN (non-deterministic ordering) when two drafts for the same issue both lacked source_pr — flagged by roborev review #223, fixed with a stable path tiebreaker, regression tests added

#135
#136

Code review checklist

• Readable: Concise, well named, follows the style guide.
• Tested: Unit tests added/updated (dedup, distiller, gh-classify, issue-linkage, reconcile, relink-issues, run-pipeline, scraper)
• Backwards compatible: Works with existing data; includes a one-off relink-issues repair tool for previously mislinked drafts.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[Hareet]

Ah! I didn't realize there was a merge order dependency with #129 . Can you rebase with main?

[Hareet]

Some quick fixes and let's get this merged in. We will want to run the dedup on the memory/promote-* PRs when those are rebased and before they are merged.

Ran the suite locally on Node 22: build clean, 1057 tests passing (both new spec files execute in full), lint scoped to the PR's files clean.

Blockers:

• issue (blocking): AGENTS.md is unrelated boilerplate that contradicts repo policy. It is the stock beads/bd onboard template: it mandates git push ("Work is NOT complete until git push succeeds", "NEVER stop before pushing", "If push fails, resolve and retry until it succeeds"), git pull --rebase, and bd sync; says "Do NOT use external issue trackers" (we track in GitHub issues); and references docs/QUICKSTART.md and .beads/, neither of which exists in this repo. A checked-in AGENTS.md is exactly the file coding agents treat as authoritative, so this would actively instruct agents to violate the repo's no-commit/no-push constraints. Please drop it (along with the .dolt/ / *.db .gitignore lines that only make sense with beads) or replace it with a real project-specific AGENTS.md.
• issue: slugIssueNumber over-matches descriptive numbers, so the CI guard can reject valid drafts. /^\d+-[a-z]+-?(\d+)-/ (dedup.ts:85) accepts ANY word-then-number: 10043-fix-500-errors-on-login.md → 500, 9200-support-2-level-hierarchy.md → 2 (reproduced on Node 22). When that spurious number differs from the frontmatter issueNumber, ciGuardReason flags a correct draft as mislinked and open-review-pr drops it from promotion. relink-issues.ts already solves this with a conventional-commit type list (fix|feat|perf|…) — reuse that (or the shared module) so the two parsers cannot diverge.

Smaller:

• dedupeByIssueId (dedup.ts:153): drafts with a missing/non-scalar id all bucket under the shared '' key and get collapsed as duplicates of each other, silently deleting one. Unreachable in-pipeline today (schema validation requires id upstream), but the function is exported with no guard and the branch is untested.
• Cross-domain canonical selection is lowest-PR-number only; domainFit is never consulted, so a weak-fit lower-PR draft wins the domain over a strong-fit higher-PR one. Worth a tiebreaker or at least a doc note.
• reconcile's CI-guard/dedup buckets are structurally zero at the only wired call site: run-pipeline never invokes open-review-pr, and open-review-pr (which writes the CI guard: / duplicate of reasons) never calls reconcile. Either print a reconciliation at the end of open-review-pr too, or trim those buckets from the report.
• reconcile throws on a valid-JSON skip line without a string reason (entry.reason.includes, reconcile.ts:50) — parseSkipLogLine casts JSON.parse without shape-checking, and because reportOutcome runs unconditionally, one corrupt audit line turns a fully successful batch into exit(1). One typeof guard plus a test.
• When dedup adds source_prs[], rewriteFrontmatterOnDisk persists the fully normalized frontmatter, not a targeted insertion — key order/date quoting can reflow beyond the intended change. Cosmetic; it re-validates.
• nitpick: stray // ponytail: marker at run-pipeline.ts:484.
• nitpick: comment density — dedup.ts is ~48% comment lines and reconcile.ts ~57%, with @example blocks restating one-line bodies; this repo keeps comments minimal.

[alexosugo]

Updates

• Made duplicate-draft promotion retry-safe: pending drafts are removed only after the canonical review PR is created.
• Applied consolidated source_prs metadata only to the promoted copy, keeping pending drafts retryable if promotion fails.
• Scoped reconciliation summaries to records written during the current invocation.
• Preserved the source repository for provenance and related-issue links, including CHT Interoperability drafts.
• Added explicit, unambiguous issue tokens for Conventional Commit titles, including breaking changes.

Verification

• Focused regression coverage passes.
• Lint and TypeScript build pass.
• A live distillation of merged CHT Core PR #11331 produced a schema-valid draft with fully grounded file references.

[alexosugo]

@Hareet this is ready for another review.

[sugat009]

Substantial work, and the core design is right. resolveRealIssue classifying a number before trusting it, with one hop from PR to sole closing issue, is the correct shape, and flagForHuman on zero resolved issues is the correct failure mode. Checked against cht-core PR 9039, whose title says fix(#9024) where 9024 is an unrelated PR closing nothing: the chain drops the ref and flags for a human instead of mislinking. issueEqualsSourcePr is structurally right too, catching the pre-R1 shape by construction rather than by pattern.

One blocking problem: the file name and the guard disagree by design, so the guard rejects drafts where resolution did its most valuable work. The rest are gaps, plus a merge-order note for #127.

Two comments are anchored a little away from the code they discuss (the scraper.ts base-branch gate and discoverDraftsByDomain), because those lines fall outside this diff's hunks; the real line numbers are in the comment text.

[alexosugo]

@sugat009 thanks for the thorough review — every item is addressed and validated, and all CI checks (including the SonarCloud gate) are green on e2fd52f.

Blocking:

• Filename vs guard: draft filenames now derive from the resolved issueNumber; a title-versus-resolution mismatch is a warn audit entry, not a rejection. Validated against your simulation table and live cht-core PR 9039 — details on the thread.
• CI wiring: npm run check-pending now runs ciGuardReason + schema validation over _pending in unit_tests.yml on every PR.

Non-blocking:

• Base-branch gate added to the scraper; live-validated against 10767 and 10432 (both now rejected). Corpus cleanup for already-promoted drafts: Clean up promoted drafts distilled from PRs merged into abandoned feature branches #155.
• Corpus-wide id dedup: Dedup pending drafts against the promoted corpus, not just the current batch #153. Epic-vs-backport discrimination: dedupeByIssueId: distinguish multi-PR epics from backport cherry-picks #154. Both kept out of this PR to avoid changing dedup semantics under review.
• Empty source_prs no longer written; nitpicks (marker, doubled /**, stale docstrings) cleaned.

Merge order as you suggested: this PR first, #127 rebases on top. Ready for another look when you have time.

[sugat009]

Re-review at e2fd52f, full pass over all 23 changed files. This time with the pipeline model corrected: _pending/ is the staging area, and open-review-pr promotes drafts into domains/<domain>/issues/.

Retractions first. My earlier review was built against 0e5cd96 and I posted it hours after you had already pushed fixes. Four of those seven findings were fixed before I posted:

• filename now derives from the resolved issue number, not the title token (235ca7d)
• pending-draft guard wired into CI (6a7307c)
• PRs merged into non-default branches are excluded (a8deae2)
• source_prs omitted when empty (b8dddfd)

On the first of those: you shipped the warn-don't-reject shape instead of rejecting a title/issue mismatch. That is the better design and it is what we wanted. Sorry for the wasted round.

What is left. Two blockers in this PR's own code, both inline. Separately, three blockers already on main that this PR does not cause, but that stop its new CI guard from ever receiving input. I list those here because they change how you should read the guard, not because they are yours to fix in this PR.

Blockers already on main (not caused by this PR)

None of the three lives in a file this PR touches, so they are here rather than inline.

1. .husky/pre-commit fails the nightly commit step, and the hook does run in CI. package.json:14 is "postinstall": "husky install", and npm ci runs postinstall. husky 8.0.3's install() skips only when HUSKY=0, or when git or .git is unavailable, neither of which applies on a runner. .husky/pre-commit:4-9 then rejects any commit while the branch is master or main. The job log of run 31673806379 says, verbatim: > husky install / husky - Git hooks installed, then at step 7 You can't commit directly to master/main branch / husky - pre-commit hook exited with code 1 (error).

The clean way to state the scale: across the workflow's entire history, all 50 runs since it landed in c3b4bf6 on 2026-06-24, the scheduled pipeline has never once committed a draft. All 26 failed runs died at "Commit knowledge drafts" on this hook. All 24 green runs found 0 PRs and staged nothing, so the commit was skipped and the push was a no-op.

Smallest fix: env: { HUSKY: '0' } on that step (run-pipeline.yml:57). Keep the hook, it is useful locally.

2. Disabling the hook only moves the failure to git push (run-pipeline.yml:63). Ruleset 15146469 ("Main Branch Rule") is active on ~DEFAULT_BRANCH, has an empty bypass_actors, and carries a pull_request rule. Classic protection is off (branches/main/protection returns 404), which is why main looks unprotected. The other ruleset you will see in the list, 10342826 ("Main"), is disabled and not relevant.

This is not just configured, it is demonstrably evaluated on ref updates to refs/heads/main: the rule suite for the last such update (3642933719, b2571b9 to 041f132) evaluated pull_request, required_status_checks, non_fast_forward and deletion. It passed, because that update arrived through a merged PR. A direct push would not satisfy the pull_request rule. The same ruleset also requires the "Build, lint, and test" and "Lint PR title" checks, and the pipeline commits with [skip ci], so those two contexts would never report on a directly pushed commit either. I should be straight that no run has ever reached git push with a real commit, so this is the expected outcome rather than an observed one.

3. The nightly has no LLM key, so it cannot produce a draft. In run 31673806379, two of the three PRs died at the filter stage with filter: flag-for-human - LLM triage unavailable: no API key set (OPENROUTER_API_KEY or ANTHROPIC_API_KEY), and the third (#11319) passed the deterministic filter (filter: distill - Shared library change affecting multiple consumers), reached distilling..., and died there with distill: flag-for-human - Distill LLM unavailable: no API key set. repos/medic/cht-agent/actions/secrets returns total_count: 0, and the 3 org secrets visible to this repo are unrelated (BrowserStack, build history, Docker Hub), so secrets.OPENROUTER_API_KEY resolves to empty.

Across all 50 runs I checked every job log (none expired): 8 PRs reached the distill stage, all 8 flagged for human on the missing key, and 0 drafts were ever written. Note distiller.ts supports ANTHROPIC_API_KEY and the error message advertises it, but the workflow wires only OPENROUTER_API_KEY, so an Anthropic-only secret would still leave CI keyless.

Those three together mean agent-memory/_pending/ has never held a committed .md on main (only 8 .gitkeep files). So check-pending validates an empty directory today. The guard itself is correct. It just has no input yet, and it cannot reach the three mislink defects already sitting in domains/. That was the agreed scope, so this is fine.

Open questions

I am not confident enough to assert these, so I am asking rather than filing them.

1. Release branches. The gate treats any non-default base as unshipped. cht-core PR 11137 (fix(#11128): adds limit to Nouveau indexed strings) merged into 5.1.x on 2026-06-04; its merge commit f8f58ce is contained in tags 5.1.3, 5.1.3-beta.1 and 5.1.3-beta.2 and never reached master. That is real released work the gate excludes. Intended, or should 5.1.x-style release branches be allowed?
2. Long-lived feature branches. 10 of the newest 100 merged cht-core PRs went into 10707-dmp-2026-enhance-bikram-sambat-support-in-cht, whose umbrella PR 11211 is still open. The sharper case is one that already landed: the 10224-ui-extensions umbrella merged to master via PR 11050 on 2026-06-23 and its branch is deleted, yet PRs 11105 and 10909 still report baseRefName: 10224-ui-extensions, so the gate rejects them permanently even though their work is on master. Acceptable, or should the corpus pick such PRs up once the umbrella lands?
3. Epic semantics. Is dropping non-canonical epic members intended, or should a genuine multi-PR epic keep one entry per PR? See the inline comment on dedup.ts:129.
4. _skipped.ndjson truncation. This PR empties the file (7 lines to 0 bytes). All 7 removed rows are prNumber: 1 with reason "LLM triage skipped", so I read it as deliberate cleanup. Confirming, because #127 made the same truncation in ba6ef06 and then reverted it in 766f008.
5. --repo and the schema. run-pipeline accepts any --repo owner/repo and buildFrontmatter derives id/issueUrl from it, while schema.json permits only medic/cht-core and medic/cht-interoperability. Should the CLI reject other repos up front?
6. Merge order with #127. This is not a risk, it is already a fact: git merge-tree on the two heads conflicts today, with src/scripts/run-pipeline.ts the only conflicted file and 5 conflict regions, one of them exactly the auditOffset/BatchState initialization in runPipeline. #127 changes that file by +58/-18. Whoever merges second must re-verify that the run-scoping of _skipped.ndjson survives the resolution.
7. Is a direct push to main the intended design at all? Ruleset 15146469 requires 1 approving review, and this repo already has open-review-pr.ts. Routing the nightly through a PR would make both the hook and the ruleset non-issues.

[sugat009]

question (blocking on the answer, not the code): Epics and backports are keyed identically, and members are dropped rather than merged.

The module docstring (:11-13) names backport cherry-picks, multi-PR epics and independent domain promotions together. For a backport cluster, collapsing is exactly right. On the 10792 cluster in the corpus today (three drafts, all in data-sync), this code keeps 10793, and cht-core confirms that is the master fix (97e3d45, an ancestor of origin/master), while 10798 (5.0.x) and 10799 (5.1.x) are release-branch backports outside master's ancestry. Correct member, no argument.

For an epic it is the opposite. The comparator reads only the integer from source_pr (:131-133), so the tiebreak is lowest-numbered, i.e. earliest-opened, not earliest-merged and not mainline-vs-backport. That usually selects the least representative fragment of an epic. And the survivor's source_prs then asserts provenance over content that was deleted rather than merged.

Two things follow, both yours to decide:

• Is dropping epic members intended, or should an epic keep one entry per PR (or be flagged for a human to merge)? A cheap discriminator is whether members' relatedFiles overlap: a backport cluster's do, an epic's do not.
• If the tiebreak's intent is "prefer the mainline fix over backports", PR number cannot express that: a backport opened before the master PR would win. Should it prefer the draft whose source PR merged into the default branch instead?

Related: dedup.spec.ts:161-171 is titled "collapses a multi-PR epic" but uses 10792/10793/10798/10799, which cht-core shows is a backport cluster (one Type: Bug issue, one master fix, two release-branch backports). The fixture also places them in tasks-and-targets, while the three real drafts are in data-sync. Was an epic fixture intended?

[sugat009]

issue (non-blocking): The promote commit never records the _pending deletions, so promotion is not idempotent.

git add (:459) receives only the domains/ copies from stageDrafts, and git commit (:460-461) has no -a. The _pending originals are removed by fs.unlinkSync at :473 with no subsequent git add. The only git add agent-memory/_pending/ anywhere in the tree is run-pipeline.yml:61, which belongs to the pipeline workflow and runs in a different job.

promoteDomain's add/commit/push/unlink shape is pre-existing on main, unchanged here apart from the frontmatterByPath threading. I am flagging it because this PR adds a second deleter, finalizeDedupDrops (:352-366, unlink at :360), which is new, so the uncommitted-deletion surface doubles.

The consequence is conditional, so stating it carefully: it needs _pending drafts to actually be tracked on main, which the CI path at run-pipeline.yml:61 would do but which has never yet happened. Once it does, a merged promote PR leaves the draft in _pending on main, any clone reflecting origin/main rediscovers it, and re-promotion stages nothing if every draft in that domain is already byte-identical on main. Then git commit exits 1 and promoteDomainSafely records failed, so that domain never drains. If even one draft in the domain is new or differs, the commit succeeds and the stale one is simply re-proposed. Note the recorded error reads Command failed: git commit -m feat(memory): promote ...; git's own "nothing to commit" text goes to stdout and is not captured.

Two notes so this is not overstated. I checked whether this already caused the 10792 triple and it did not: all three files arrived in the single commit fdf4af2, so that is three PRs resolving to one issue in one run. Second, :473 sits inside the try whose catch (:476-478) does if (pushed) deleteRemoteBranch(...), so an unlinkSync failure after gh pr create would delete the branch of the PR just created. Also pre-existing, also worth a guard.

Cleanest fix: stage the _pending paths as deletions on the promote branch so one PR both adds domains/ and drains _pending, and drop :473.

[sugat009]

issue (non-blocking): The buckets match free text, and one of them counts successes as failures.

bucket() keys on reason.includes('CI guard:') (:30) and reason.includes('duplicate of') (:31). Two consequences:

• formatReconciliation labels the total "N flagged/skipped". A decision: 'warn' row is written for a draft that was successfully created (distiller.ts:437), so a good run reports created drafts inside that flagged total. Suggest excluding warn, giving it its own bucket, or renaming the label.
• The LLM's own triage reason reaches the same log verbatim, when the triage decision is not distill (filter.ts:302), so a model that writes the words "duplicate of" in prose would be counted under dedupCollapses. Keying on decision plus a structured field would be sturdier than substring matching.

Also worth knowing: at run-pipeline's call site neither the CI guard nor dedup runs, so those two buckets have no producer there and read as zero except via exactly that free-text collision. The line is only meaningful from open-review-pr.

[sugat009]

issue (non-blocking): The title-vs-resolution warning never reaches a human-facing surface.

The mechanism is tested, so this is not about correctness: distiller.spec.ts asserts a warn entry exists and that its reason includes both #9024 and #9023, with a negative test for the agreeing case. The gap is downstream. The warning goes only to _skipped.ndjson, and nothing surfaces it to the person reviewing the draft: not the draft frontmatter, not buildPRBody, not the run summary except as an anonymous otherFlags count.

Suggest carrying it into the draft frontmatter (e.g. linkage_warning:) so buildPRBody can list it on the promote PR. That is where a human can actually act on it.

One aside on that test's fixture, since it names the 9039 shape in a comment: it stubs linkedIssues: [{ number: 9023 }]. The real cht-core PR 9039 never reaches that state. It has no closing refs, its title token #9024 is itself a PR whose own closing refs are empty, and the body's bare #9023 has no fixes/closes keyword, so linkedIssues comes back empty and distillPR returns flag-for-human at :502-503. The fixture is a fine unit test of the warning, but 9039 is not a live example of it, which is worth knowing if that shape is ever used to argue coverage.

[sugat009]

issue (non-blocking): A transient gh failure is cached as a permanent null, silently disabling the gate for the rest of the process.

catch { name = null } then defaultBranchCache.set(repo, name). Failing open on one lookup is the right call and the docstring says so. Caching that failure is not: one rate-limited gh repo view turns the base-branch gate off for every remaining PR in the batch, with no log line, and nothing resets the cache between PRs.

Suggest caching only successful lookups, plus a console.warn on failure.

[sugat009]

nitpick (non-blocking): DRAFT_SHAPE was not tightened along with the inline block.

:227 says relatedFiles and entities must come only from the Files changed list, and the inline spec carries that for both fields (:214 and :221). But DRAFT_SHAPE (:88-109) still describes entities as "<file or module path>" at :99 and relatedFiles loosely at :106, and createStructuredCliChain(draftSchema, DRAFT_SHAPE) (:141) sends it on the claude-cli path. structured-cli.ts:52-55 appends the shape after the whole buildPrompt output, so the loose wording is the last field-level spec the model sees, with only the provider's own JSON-only trailer (claude-cli.ts:368) behind it.

Scoping this so it does not over-reach: the broader wording in schema.json:175 and TEMPLATE.md:98 looks deliberate, not stale, because reconcile.ts:12-13 and :52-54 (added in this PR) explicitly allow entities to name a module or concept rather than a literal path, and hallucinationRate is reporting rather than a gate. DRAFT_SHAPE is the one clear divergence.

[sugat009]

note (non-blocking): Right guard, right place. One correction to how I described its reach, and one real gap.

I want to be accurate about the reach, because it is better than I first thought: check-pending scans the checked-out working tree (check-pending.ts:18, :63-67, relative to REPO_ROOT), not the PR diff. actions/checkout@v6 on a pull_request event checks out the merge ref, so any draft sitting in _pending/ on main is present in every PR's tree and is inspected. Promote PRs are covered too, since promoteDomain only unlinks the originals locally after the PR exists.

The real gap is timing: this workflow has no push trigger, and the pipeline's commit carries [skip ci] (run-pipeline.yml:62). So the guard never runs on the commit that adds a draft. A bad draft would fail the CI of the next unrelated PR instead of failing at the point of landing. Note a push trigger alone would not close that, because [skip ci] would still suppress it. Was [skip ci] deliberate there?

Also, check-pending currently scans a directory holding 8 .gitkeep files and zero drafts, so the step passes trivially today. Neither point is a defect in this PR.

[sugat009]

note (non-blocking): Consolidated smaller items, anchored here because the first few concern this function. Not worth their own threads.

• scraper.spec.ts:178 (stub :179-181, sole assertion :182) cannot fail. Its guard throw is swallowed by defaultBranch's own catch (scraper.ts:268-270) and the fail-open at :285. I checked by mutation: deleting scraper.ts:283 (if (!base) return;) leaves the suite at 1081 passing, unchanged from baseline, so the test does not detect the regression it names.
• stripBoilerplate: both production call sites are untested. Neutering either scraper.ts:90 (issue body) or :357 (PR body) leaves the suite at 1081 passing. Only the function itself is covered (scraper.spec.ts:1023-1040). It also removes comments with no separator, so adjacent words glue together, and scraper.spec.ts:1039 locks that in by asserting '<!-- a -->Keep this<!-- b -->and this<!-- c -->' becomes 'Keep thisand this'.
• The ~246-char figure in this rationale (:29) does not match the issue it cites. The leading PHI comment in cht-core #10912 measures 343 chars, and the bug-report template has been 343 at every revision that carries it. The rationale otherwise stands: against ISSUE_BODY_LIMIT = 500 a 343-char boilerplate comment really does push the root-cause sentence out of budget. Where does 246 come from?
• Only review bodies currently reach the distiller prompt un-stripped (distiller.ts:166-170, interpolated at :200), so that is the live prompt-contamination path and worth stripping. Issue comments reach no prompt at all: LinkedIssue.comments is written at scraper.ts:89-90 and read nowhere in src/, since buildPrompt uses only i.body. Is that field meant to be dead? If it is meant to feed the prompt, it needs both wiring and stripping.
• pipeline.ts:38: was repo?: string left optional deliberately to avoid touching ScrapedPR fixtures? scrapePR always sets it and distiller.ts:316 falls back with ??.
• scraper.ts:265 carries the NOSONAR S4036 marker, and it is one of six call sites in this file that shell out to gh: five direct execFileSync (:76, :159, :198, :236, :265) and one through the ghExec wrapper (:87). Fine if the Sonar gate is new-code-only, otherwise the siblings will surface eventually.
• uniqueBranchName (open-review-pr.ts:207) probes only local refs, and executeApply fetches only origin main (:531), so remote-tracking refs are stale too. A promote from a fresh clone, or one whose local branch was pruned, can collide with a branch that already exists on origin. No workflow runs open-review-pr today, so this is a local hazard for now.
• rewriteFrontmatterOnDisk can silently no-op, because hasFrontmatter (schema-utils.ts:50-53) strips a leading BOM while the rewrite regex at :295 is ^-anchored and does not, so a BOM-prefixed draft is admitted and rewritten to itself. And on a draft that already carries source_prs it injects a duplicate key, which is not cosmetic: I verified against the installed js-yaml 4.1.1 that it throws duplicated mapping key, and gray-matter 4.0.3 propagates it as a YAMLException, so the promoted file becomes unparseable. Nothing in the pipeline writes source_prs into _pending today, so this needs a hand-authored draft, and stageDrafts triggers on source_prs !== undefined alone (:423), with no dedup collapse required. Can a draft ever arrive there already carrying the key?
• A promotion that fails at stageDrafts/git add/git commit (open-review-pr.ts:458-461) leaves copies under agent-memory/domains/ in the operator's tree, staged rather than untracked if git add succeeded. If push or gh pr create fails instead, the copies are already committed and the residue is an abandoned local branch. Nothing cleans up either: the catch (:476-478) and the finally (:537-540) touch neither domains/ nor the local branch.
• source_prs behaves correctly (every non-null ref in the group is kept), but there is a coverage gap and a provenance oddity: when a strong-fit draft with no source_pr of its own wins the sort, it is stamped with a source_prs list that does not include itself. dedup.spec.ts:193-201 is the only mixed-group test and it asserts nothing about source_prs; its canonical does carry a source_pr, so the canonical-without-source_pr case is untested anywhere in the file.
• dedup.ts:19 imports its filename grammar from relink-issues.ts, so the CI guard at unit_tests.yml:34-35 now depends on a repair script. relink-issues.ts has an npm script (package.json:25) but appears in no workflow. Consider moving FILENAME_TOKEN_RE to a shared module.
• The new <pr>-issue-<n>-<slug>.md convention is a third grammar. On main the 110 drafts split 52 <number>-<slug>.md and 58 <pr>-<type><issue>-<slug>.md, with 0 in the new shape, while TEMPLATE.md:7 still documents <issue-number>-<short-slug>.md.
• docs/memory-seeding-runbook.md is stale on four points, three of them new here: :151-152 (force overwrite / same output path), :160 (_skipped.ndjson described as skip/flag-for-human only, now also warn), and :7-9 (merged PRs, now default-branch-only). The pre-existing one is :96 (a "2g memory limit" vs the compose default of 6g). :161 omitting npm run check-pending is an omission rather than a contradiction.
• #146 is half addressed. Done: the polluting call site (filter.spec.ts:229/:237) and the purge of all 7 fake prNumber: 1 rows. Not done: logPath on the four option-less filterPR calls (:190, :203, :216, the three DISTILL: cases, plus :245), and the NODE_ENV=test guard. Also the PR references #146 nowhere, so it will not auto-close. Do you want the remainder here or left on the issue?
• The exclusion message interpolates a branch name into a string that recordWorkerError later keyword-matches for rate limits. Currently harmless: 0 of cht-core's 916 remote branch names collide, and only 5 of the 14 keywords are reachable from a refname at all, since refnames cannot contain spaces. The realistic path is a stacked PR whose branch is slugged from an issue like #10705 or #11090, where ...-rate-limiter-... matches /rate[\s_-]?limit/. Brittle by construction rather than broken.
• Scope: 30 commits, 23 changed files, and 11 commits with no ticket reference. The PR body declares two issues, #135 and #136. Was the #135 relink-issues work meant to ship here, or split?

[alexosugo]

Design decisions for the memory pipeline

The review threads on this PR raised questions that are product decisions rather than code defects. I have written one decision per question in docs/memory-pipeline-decisions.md (now committed on this branch, so you can comment on individual lines under Files changed). Each decision is a proposal until a decider approves or objects.

Please react to the numbered decisions directly instead of the open threads. The full text follows.

docs/memory-pipeline-decisions.md (click to expand)

Memory pipeline: design decisions

Status: DRAFT — awaiting sign-off (posted to PR #138 on 2026-08-27)
Deciders: @alexosugo, @sugat009, @Hareet
Context: PR #138 review (rounds 1–3). The review surfaced questions that are
product decisions, not code defects. This doc records one decision per question so
future reviews argue against a written spec instead of re-negotiating in threads.
Each decision below is a proposal until a decider objects or approves.

A fact that frames everything: the nightly pipeline has never produced a draft in
production. All 50 scheduled runs since 2026-06-24 either found no PRs or died on
a missing LLM key, and the commit step has never succeeded (husky hook). Decisions
D1 and D2 exist to get one real end-to-end run, because until then every review
argues hypotheticals.

---

D1. The nightly promotes drafts through a PR, not a direct push to main

(Sugat Q7; dissolves the husky and ruleset blockers)

Decision: Replace the direct git commit && git push in run-pipeline.yml
with the existing promotion path: commit drafts to a branch and open a PR
(open-review-pr.ts already implements branch + PR creation). A human merges it.

Rationale:

• Ruleset 15146469 requires a PR with 1 approving review for main, with no
  bypass actors. A direct push can never succeed. Working around the ruleset
  (bypass actor for the bot) weakens the protection for no gain.
• The .husky/pre-commit hook that blocks the commit step becomes a non-issue on
  a branch; no HUSKY=0 workaround needed.
• Machine-written knowledge should get a human glance before it lands. The repo
  already believes this: promotion from _pending to domains/ goes through a
  review PR by design.

Consequences:

• [skip ci] on the pipeline commit is removed; the check-pending guard runs
  on the draft PR — closing the "guard never runs on the commit that adds a
  draft" gap (Sugat's note on unit_tests.yml).
• The nightly needs permissions: pull-requests: write and a branch-naming
  convention (memory/nightly-<date>), plus dedup of an already-open nightly PR
  (append to the existing branch rather than opening a second PR).

D2. CI gets OPENROUTER_API_KEY; the workflow also wires ANTHROPIC_API_KEY

Decision: Add the repo secret and pass both env vars in run-pipeline.yml,
since distiller.ts supports both and the error message advertises both.
Owner: whoever holds repo admin (secret cannot be added from a PR).

D3. Base-branch gate: exclusion is a skip, never an error

(Blocker on scraper.ts; fix agreed in review, recorded here as the contract)

Decision: A PR merged into a non-default branch is a normal, auditable
exclusion. It must write a _skipped.ndjson row and leave the run's exit code
untouched. Implementation: carry baseRefName on ScrapedPR and decide in the
filter (checkSkipRules), not by throwing from the scraper. PR #N is not merged moves to the same channel. A pipeline-level test asserts
failures === 0 plus one appended skip row for a batch containing an excluded PR.

Contract: an exclusion the design intends is never allowed to fail the run
or to skip the audit log. Anything that increments failures must be an actual
malfunction (gh failure, corrupt JSON, rate limit).

D4. Release branches (5.1.x style) are IN scope; the gate allows them

(Sugat Q1)

Decision: The gate accepts the default branch plus branches matching
/^\d+\.\d+\.x$/. Everything else is skipped (per D3).

Rationale: cht-core PR 11137 merged into 5.1.x, shipped in tags 5.1.3+,
and never reached master. That is real released work; excluding it loses
knowledge the corpus exists to hold. The backport-duplication risk is already
handled: dedup keys on issue id and keeps the mainline fix, so a master fix
plus its release-branch backports collapse to one entry.

Trade-off accepted: a release-branch PR whose fix later also lands on
master produces a transient duplicate until dedup collapses it.

D5. Long-lived feature branches stay OUT of scope; the umbrella PR represents them

(Sugat Q2)

Decision: PRs based on feature branches (e.g. 10224-ui-extensions,
10707-dmp-2026-...) are skipped permanently, even after the umbrella merges.
The umbrella PR itself (merged into master) is scraped and distilled, and its
linked epic issue carries the knowledge entry.

Rationale: member PRs describe intermediate states; the umbrella carries the
shipped result. Re-admitting members once the umbrella lands would need
merge-ancestry tracking for deleted branches — real complexity for marginal
knowledge. Revisit only if a distilled umbrella proves too coarse in practice.

D6. Dedup never destroys distilled content

(Blocker on open-review-pr.ts)

Decision: finalizeDedupDrops moves dropped drafts to
agent-memory/_pending/_collapsed/<domain>/ instead of unlinkSync. The audit
row keeps the dropped draft's title. check-pending and promotion ignore
_collapsed/. A human can merge content from _collapsed/ by hand and delete it.

Rationale: for backport clusters the drop loses nothing of value; for epics
it deletes disjoint work (cht-core issue 6543: four PRs, file sets overlapping on
exactly one file). Since the pipeline cannot yet tell the two shapes apart (D7),
it must not delete either.

D7. Epic vs backport discrimination is deferred to #154; interim rule below

(Sugat Q3, the blocking-on-the-answer question on dedup.ts)

Decision (interim):

• Dedup continues to collapse same-issue groups to one canonical entry.
• The tiebreak changes from lowest PR number to default-branch base first,
  then lowest PR number. "Prefer the mainline fix" is the actual intent, and
  PR number cannot express it (a backport opened before the master PR would win).
  baseRefName is available once D3 lands.
• When a group's members have effectively disjoint relatedFiles (pairwise
  overlap of at most one file), the group is flagged for human review instead of
  silently collapsed. That is the cheap epic detector Sugat proposed.
• Full merge-per-epic semantics (one entry per PR, or LLM-merged single entry)
  is dedupeByIssueId: distinguish multi-PR epics from backport cherry-picks #154's scope, informed by real corpus data after D1/D2 produce some.
• The dedup.spec.ts fixture titled "collapses a multi-PR epic" is renamed: the
  10792/10793/10798/10799 cluster is a backport cluster in cht-core, not an epic,
  and the real drafts live in data-sync, not tasks-and-targets. A true epic
  fixture (6543 shape) is added for the flag-for-human path.

D8. run-pipeline rejects repos outside the schema enum up front

(Sugat Q5)

Decision: --repo values other than medic/cht-core and
medic/cht-interoperability fail fast with a clear error, before any gh call.
The schema stays the single source of the allowed list. Widening the corpus to a
new repo is a schema change plus taxonomy review, not a CLI flag.

D9. Merge order: #138 lands first; #127 rebases

(Sugat Q6; already agreed in threads, recorded so it stops being re-asked)

Decision: #138 merges first. #127 rebases on top and its author re-verifies
that the run-scoping of _skipped.ndjson survives the resolution of the five
conflict regions in run-pipeline.ts (one is exactly the auditOffset/
BatchState initialization).

D10. _skipped.ndjson truncation in #138 was deliberate

(Sugat Q4)

Decision: Confirmed. All 7 removed rows were prNumber: 1 test pollution
("LLM triage skipped") written by a spec that ran without a logPath (#146).
The remainder of #146 (pass logPath in the four option-less filterPR spec
calls, NODE_ENV=test guard) stays on #146 and does not grow #138.

Post-rebase note (2026-08-27): #158 landed on main and gitignores
agent-memory/_skipped.ndjson. After the rebase the file is no longer in the #138
diff at all, so the truncation question is closed by main, not by this PR.

D11. Scope discipline for #138 and after

Decision: #138 takes only the D3 and D6 fixes (its two in-PR blockers) plus
the D7 interim tiebreak if reviewers want it in the same PR; otherwise D7 ships
with #154. Everything else here lands as follow-up PRs referencing this doc:
D1+D2 (pipeline-to-PR), D4 (release-branch gate), D5 (no change needed — it is
the current behaviour, kept), D8 (CLI guard). Non-blocking review findings
(reconcile buckets, warn surfacing via linkage_warning: frontmatter, transient
defaultBranch cache, stale runbook lines) become small issues, not #138 commits.

Validation practice (applies to all of the above): every behavioural change
gets a test at the pipeline boundary, not only the unit boundary — the D3 test
shape (failures === 0 + audit row) is the model. Unit tests prove mechanisms;
pipeline tests prove the mechanism is wired to the right channel.

---

Open items this doc does NOT decide

• Whether LinkedIssue.comments (written, never read) should feed the distiller
  prompt or be deleted. Needs a distillation-quality judgement; owner: Context analysis agent doesn't load memory-pipeline drafts (wrong path + schema) #135 scope.
• The filename-grammar consolidation (three conventions on main; 0 files in the
  new <pr>-issue-<n>-<slug>.md shape yet). Harmless until the corpus is
  regenerated; decide alongside Dedup pending drafts against the promoted corpus, not just the current batch #153.

[alexosugo]

Rebased on main at 2311664. Conflict in test/scripts/filter.spec.ts resolved as @sugat009 described (kept { logPath, skipLlm: true }). agent-memory/_skipped.ndjson is gitignored by #158, so it left the diff. Locally: npm run lint, tsc, npm run check-pending, and 1100 tests pass.

Scope (D11)

I diffed the PR against the decisions doc. The PR contains no code for D1, D2, D4, D5, D7 or D8. The only work left is the two in-PR blockers:

Decision	Change	Test
D3	baseRefName on ScrapedPR; skip rule in checkSkipRules; PR #N is not merged moves to the same channel; scraper stops throwing	runPipeline batch with one excluded PR: failures === 0 and one appended skip row
D6	finalizeDedupDrops moves drops to _pending/_collapsed/<domain>/; check-pending and promotion ignore _collapsed/	dropped file exists under _collapsed/, audit row carries its title

I recommend not splitting the existing 30 commits. Sugat re-reviewed all 23 files at e2fd52f and named exactly two blockers, both listed above. Splitting would restart review on code that already passed. Everything else in the doc lands as follow-up PRs that reference it.

Open questions (approve / object per item)

Only points the doc does not settle, or where a reviewer proposed two shapes:

1. D6 shape (@sugat009): you proposed either _collapsed/ or copying drops onto the promote branch. The doc picks _collapsed/. Approve, or do you want the promote-branch copy?
2. D7 interim (@sugat009, @Hareet): ship the default-branch-first tiebreak and the disjoint-relatedFiles human flag in this PR, or defer both to dedupeByIssueId: distinguish multi-PR epics from backport cherry-picks #154? The doc allows either. My default is defer, to keep fix(#136): memory pipeline hardening + issue relinking (#135) #138 to D3+D6.
3. D4 (@sugat009): release branches (5.1.x) in scope, in a follow-up PR. Approve or object?
4. D5 (@sugat009): feature-branch member PRs stay out permanently; the umbrella PR represents them. Approve or object?
5. D1 + D2 (@Hareet): the nightly opens a PR instead of pushing to main, and needs OPENROUTER_API_KEY as a repo secret. Approve the direction, and who adds the secret?
6. D8 (@sugat009): --repo outside the schema enum fails fast. Approve or object?
7. Context analysis agent doesn't load memory-pipeline drafts (wrong path + schema) #135 relink work (@sugat009, from your scope note): keep it in this PR since it is already reviewed. Approve or ask for a split?

D3, D9 and D10 need no answer: D3's shape is your stated preference (filter-side), D9 is agreed, and D10 is closed by main.

Verification standard (proposed, for this PR and future rounds)

Full text is committed in docs/memory-pipeline-decisions.md so it can be reviewed line by line. Summary: every behavioural claim in review gets a test at runPipeline or openReviewPR that asserts the exit signal and the audit row. Unit tests prove a mechanism exists; boundary tests prove it reaches the right channel.

Verification standard in full (click to expand)

The problem this solves

Review rounds on #138 follow the same pattern: a mechanism is fixed and with a proving unit test, but upon reviewing and tracing it through the pipeline and it's found to have ended up in the wrong channel.

The D3 blocker is the clearest case. The base-branch gate works: scraper.spec.ts
proves the scraper rejects a PR merged into a feature branch. But the rejection
travels as a ScraperError. In run-pipeline.ts that path increments failures and
exits 1. The nightly dies and no audit row is written. The unit test passed; the
behaviour was still wrong.

The same shape appears in other review findings:

Finding	Unit test says	Pipeline says
Base-branch gate	Scraper rejects the PR	Whole batch fails, no audit row
scraper.spec.ts:178	Guard throws	Throw is swallowed by the fail-open catch; the test cannot fail
stripBoilerplate	Function strips comments	Neither production call site is covered
warn audit entry	Entry is written	Nothing reads it; a human never sees it

The standard

A behavioural claim is "fixed" only when a test at the pipeline boundary proves it.

The pipeline boundary is runPipeline (nightly path) and openReviewPR (promotion
path). Those two functions are where a decision becomes observable: an exit code, a
written draft, a row in _skipped.ndjson, or a git action.

Each boundary test asserts two things:

1. The exit signal. For runPipeline: state.failures and whether process.exit
   was called. For openReviewPR: the returned status per domain.
2. The audit row. One appended entry in _skipped.ndjson with the expected
   decision and a reason that names the case.

If a change alters neither the exit signal nor the audit trail, it is not a
behavioural change and a unit test is enough.

Why this shape

• It is already the house pattern. test/scripts/run-pipeline.spec.ts has
  "processes every PR and does not exit when all succeed" and "records a failure and
  exits 1 when a PR throws". The D3 test is a third sibling. No new harness.
• It ends "which channel" arguments. The open blockers are all about channel:
  error versus skip, delete versus move, log versus surface. A boundary test names the
  channel in its assertion.
• It gives the review a citation. A reviewer writes "covered by
  runPipeline › skips a non-default-base PR without failing the batch" instead of
  re-tracing the code.
• It exposes tests that cannot fail. Delete the guard, run the test, watch it
  fail. That mutation check is how the scraper.spec.ts:178 gap was found.

Applied to the two open blockers

D3

runPipeline([excludedPR, normalPR])
  → failures === 0
  → process.exit not called
  → _skipped.ndjson gained one row: { prNumber: excludedPR, decision: 'skip', reason: /non-default branch/ }
  → normalPR still produced a draft

D6

openReviewPR(domain with two same-issue drafts)
  → canonical promoted
  → dropped draft exists at _pending/_collapsed/<domain>/<file>
  → dropped draft no longer in _pending/<domain>/
  → audit row: { decision: 'skip', reason: /duplicate of .* "<dropped title>"/ }
  → check-pending over the tree passes (ignores _collapsed/)

Cost

One extra it block per behavioural change, about 15 to 30 lines. The runPipeline
tests already stub processSinglePR; the D3 test needs a stub that returns a skip
decision and writes the row. No new fixtures, no new frameworks.

What it does not cover

• Distillation quality. Whether a draft is good is a judgement, not an assertion.
• Live gh behaviour. Boundary tests stub gh. Live checks (like the 10767/10432
  validation) stay a manual step, recorded in the PR comment.
• Workflow YAML. run-pipeline.yml steps are not reachable from mocha. D1 needs a
  real run to prove itself.

In one sentence

Every behavioural claim in review gets a test at runPipeline or openReviewPR that
asserts the exit signal and the audit row. Unit tests prove a mechanism exists;
boundary tests prove it reaches the right channel.

[alexosugo]

Here are D3 and D6 with their boundary tests, per the verification standard above.

D3 — 95e9c84. The scraper no longer throws on a non-default base. ScrapedPR now carries baseRefName and defaultBranch; checkSkipRules returns Merged into non-default branch '<base>' (default is '<default>'). filterPR writes the audit row and returns skip, so state.failures is untouched, exit code stays 0, --resume sees the PR as handled, and reconcile counts it under otherFlags. Fail-open is unchanged: no baseRefName → no lookup; lookup failure → defaultBranch undefined → no skip.

Boundary test: run-pipeline.spec.ts › skips a PR merged into a non-default branch without failing the batch (D3). It runs the real filterPR against a temp audit log with a two-PR batch and asserts: process.exit not called, only the mainline PR distilled, exactly one row { prNumber: 20, decision: 'skip', reason: /non-default branch/ }. Mutation check done: with the rule removed the test fails on expected [ 20, 21 ] to deeply equal [ 21 ].

One deviation from the D3 text: PR #N is not merged stays a ScraperError. An unmerged PR has no mergeSha/mergedAt, so it cannot become a ScrapedPR for the filter to skip. It is reachable only through an explicit --pr, where an error to the operator is the right signal; the nightly lists merged PRs only.

D6 — d74f29a. finalizeDedupDrops renames the dropped draft to _pending/_collapsed/<domain>/<file> instead of unlinkSync. The audit row now reads duplicate of <id> — collapsed into <ref>; "<dropped title>" moved to _collapsed/<domain>/<file>. discoverDraftsByDomain iterates CHT_DOMAINS and check-pending reads one level deep, so neither ever sees _collapsed/; both now have a test that says so.

Boundary test: open-review-pr.spec.ts › apply promotes the lowest-PR-numbered canonical with source_prs and moves the duplicate to _collapsed (D6) asserts the file is byte-identical at its new path, discoverDraftsByDomain returns nothing, and the audit row carries the dropped title and path.

Gate chain, local: npm run lint, tsc, npm run check-pending, npm test (1104 passing). Diff for both: 10 files, +120/−31.

[sugat009]

I reviewed the new work at c0d01d0. Both round-2 blockers are fixed, with tests at the
pipeline boundary. For D3: ScrapedPR now carries baseRefName and defaultBranch. The filter
decides, and the scraper no longer throws. The spec covers the skip and the fail-open case. For
D6: finalizeDedupDrops moves drops to _pending/_collapsed/<domain>/. The audit row keeps the
title. check-pending ignores _collapsed/. Writing the decisions down was the right move.

Gates at head: tsc clean, 1104 tests pass, validate-schema 167/0/3. Merge onto main is
clean.

What blocks: the decision doc ships in this PR and disagrees with the code it ships with, in
three places. D3 says the unmerged-PR error moves to the skip channel. The code keeps the throw,
with a good reason. The D6 test sketch says decision: 'skip'. The code and the shipped test say
flag-for-human. D7 says the dedup fixture "is renamed". It is not. Each has a one-click fix
inline, on the doc or on the test. Two more items are inline. The retargeted scraper spec still
cannot fail, which breaks the verification standard this same doc commits to. And the D6 catch
swallows every move failure, not only the already-gone case.

Also inline: the D4 example is wrong. PR 11137 (5.1.x, issue #11128) has a master twin. That
twin, #11133, merged the same day. So the pair shows a backport, not lost knowledge. And the
framing paragraph says 50 scheduled runs. The count was 64 on the doc's date and is 68 today.

The audit trail needs a durable home. D3 and D6 rest on audit rows. But _skipped.ndjson is
untracked since #158, and CI has never persisted it. A row that dies with the CI runner is not an
audit trail. Proposal, for the decisions doc as a new decision: un-ignore the file. First close
the #146 remainder, so a test run can never write to it again. That remainder is logPath in
the four option-less filterPR spec calls, plus a NODE_ENV=test guard. Real rows then ride the D1 nightly PR next
to the drafts they explain. A manual run also writes the file, and that is intended. A human-run
exclusion is still an exclusion. This reverses part of #158. The reversal is safe once the
test-pollution half is fixed. Implementation goes to a follow-up PR per D11, not into #138.

As a decider, here are my reactions to the decisions, one line each:

• D1 approved. The nightly opens a PR. This also gives the audit rows a home (see above).
• D2 approved. Hareet owns the admin step of adding the secret.
• D3 approved, with the amendment in comment 1. The unmerged-PR error stays a throw. One
  behavior change to know: the base-branch gate now lives in the filter, so --force bypasses
  it. The old scraper throw did not allow that. It is intended. A person who passes --force
  knows what they do. Comment 1's text records it.
• D4 approved. The rule stays simple: default branch plus the N.N.x regex. Comment 4 fixes
  the example.
• D5 approved. One big PR into master carries the knowledge better than its member PRs.
• D6 approved as shipped. The audit channel is flag-for-human (comment 2). When there is
  doubt, ask the human.
• D7 approved as deferred to #154, all three parts. D6 removed the destructive edge, so
  waiting for real corpus data is the simple option. Take the fixture rename now (comment 7).
• D8 approved.
• D9 approved. #138 first. Note #127 now carries my REQUEST_CHANGES, so it waits anyway.
• D10 approved. Ruled earlier, and #158 closed it on main.
• D11 approved, with two amendments. Comment 5 adds three items to the follow-up list. The
  audit-trail proposal above becomes a new numbered decision in this file.

[sugat009]

issue (non-blocking): This test cannot fail for the property in its title. The
defaultBranch fail-open catch swallows the stub's throw. This is the same hole my round-2
comment named on the old test at :178. Your own verification standard says: delete the guard,
run the test, watch it fail. This test fails that standard on the day it ships. Record calls
instead of throwing:

Suggested change

	it('does not look up the default branch when metadata carries no baseRefName', () => {
	const { scrapePR } = loadWithBase(metaWithBase(), () => {
	throw new Error('repo view must not be called');
	});
	const pr = scrapePR(7);
	expect(pr.baseRefName).to.be.undefined;
	expect(pr.defaultBranch).to.be.undefined;
	});
	it('does not look up the default branch when metadata carries no baseRefName', () => {
	const repoViewCalls: number[] = [];
	const { scrapePR } = loadWithBase(metaWithBase(), () => {
	repoViewCalls.push(1);
	return DEFAULT_MASTER();
	});
	const pr = scrapePR(7);
	expect(repoViewCalls).to.have.length(0);
	expect(pr.baseRefName).to.be.undefined;
	expect(pr.defaultBranch).to.be.undefined;
	});

[sugat009]

I reviewed the delta c0d01d0..0d2b28a at 0d2b28a. All nine round-3 suggestions are in. Eight
are byte-identical. The catch fix moved into moveToCollapsed with the same behavior, and your
new test proves it: it fails when I revert the catch to swallow everything. The retargeted
scraper test now fails when the lookup runs without a baseRefName. I checked both by mutation.

D12 matches the audit-trail decision from my round-3 review. Approved. Its precondition is right:
four option-less filterPR calls remain in filter.spec.ts (:208, :221, :234, :263).

Gates on a fresh npm ci at head: tsc clean, 1105 tests pass, nyc thresholds pass, lint clean,
validate-schema 167/0/3. Merge onto current main is clean. CI is green, SonarCloud included.

Approving. Two nitpicks inline, both one click. After this merges, #127 rebases once per D9.

[sugat009]

@Hareet, your CHANGES_REQUESTED from 16 July is the last block on this PR. I approved at 0d2b28a today. Can you re-review, or approve if your July points are resolved?

[Hareet]

Re-reviewed at 8235a08: all of my July points are addressed. AGENTS.md and the beads .gitignore lines are gone. slugIssueNumber now shares relink's FILENAME_TOKEN_RE (descriptive numbers like fix-500-… no longer trip the CI guard). Drafts with a missing id stay separate. domainFit is the first tiebreaker. open-review-pr prints its own reconciliation. reconcile tolerates a missing reason. source_prs is inserted as a single key. Each fix has a test. Locally on Node 22: build clean, 1106 passing, lint and check-pending clean.

Two non-blocking notes for later: run-pipeline's CI-guard/dedup counts are always 0 at that call site, and the tighter token regex drops relink's filename cross-check on 8740-7599-forms-module-uplifted-enketo.md (its metadata is already correct).

Approving! Thanks for getting all this in