[Tech Debt] Tracked public docs link into gitignored .github/vendored-decisions/, so those links 404

[chris-prener]

Parent epic: #123 — [Epic K] Vendored Workflow Toolkit Adoption & Governance

User story

As a public reader of this repo's documentation, I want the links in tracked docs to resolve, so that I can follow a cited decision record instead of hitting a 404.

Motivation

This is a public CRAN package. Its docs are read by people who only have the GitHub web view — no clone, no local checkout. A growing number of tracked, publicly-visible files link into .github/vendored-decisions/, which .gitignore excludes. Those links 404 for every such reader.

The count is small now but grew during the sync in PR #117, and every future sync of the vendored toolkit will grow it further, because upstream docs cite ADRs freely.

Current pain

.gitignore (lines ~84–88) excludes the vendored tree:

.github/agents
.github/copilot-instructions.md
.github/skills
.github/VENDOR_MANIFEST.json
.github/vendored-decisions

Yet these tracked files link into .github/vendored-decisions/:

File	Refs	Public?
docs/decisions/README.md	2	yes
docs/playbooks/pick-up-stale-issue.md	2	yes
docs/playbooks/start-new-epic.md	2	yes
docs/requirements/commit-cadence-guidance.md	3	yes
docs/requirements/_template.md	1	yes
.github/copilot-instructions.md	2	yes (tracked despite being gitignored — force-added)
tests/meta/validate_closing_issue_preconditions.py	1	yes (code path, not a link)

Nine ADR files live in .github/vendored-decisions/ (ADR-0001 through ADR-0009); exactly one lives in tracked docs/decisions/ (ADR-0004-uds-crosswalk-internalization.md). So the overwhelming majority of the ADR corpus this repo's docs cite is invisible to the public. See the correction comment below for the full recount.

Two aggravating factors:

1. docs/decisions/README.md is the index. It is the one file whose entire job is pointing readers at decision records, and half its targets 404.
2. ADR numbers collide across the two directories. The real, verified collision is ADR-0004: docs/decisions/ADR-0004-uds-crosswalk-internalization.md and .github/vendored-decisions/ADR-0004-auto-filed-issue-protocol.md are different documents sharing a number, so a bare "ADR-0004" citation is ambiguous. (The ADR-0012 / ADR-0014 collisions originally described here do not exist — neither number is present in either directory. See the correction comment below.) (Filed upstream as pfizer-evgen/agentic-dev#397.)

Proposal

Pick one posture and apply it consistently:

A. Track .github/vendored-decisions/ (recommended). Remove it from .gitignore and commit the 11 ADRs. Links resolve; the public sees the decisions governing the workflow. Cost: +11 files of vendored content in the repo, needing .Rbuildignore coverage (^\.github$ is likely already excluded — verify) and re-committing on each sync. This is the only option that makes the citations correct rather than merely quiet.

B. Stop citing them from tracked docs. Replace every .github/vendored-decisions/... link in a tracked file with either plain text (per ADR-0007, not vendored here) or a link to the upstream repo. Cost: upstream is private, so an upstream link 404s for the public too — this option removes the broken links without giving the reader anything.

C. Track a generated index only. Keep the ADR bodies gitignored but commit a docs/decisions/vendored-index.md summarising each vendored ADR in a paragraph, and point tracked links there. Middle ground; adds a file that must be regenerated on sync.

Whichever is chosen, docs/decisions/README.md should state plainly which ADR directory is public and how the numbering works, and the collision between the two ADR-0012s / ADR-0014s should be called out for readers.

Note this interacts with the sync workflow: options A and C both create content that must be refreshed when bootstrap_repo/SKILL.md syncs, so whichever is picked should be recorded somewhere the next sync will see it.

Acceptance criteria

• A posture (A/B/C) is decided and recorded.
• No tracked, publicly-rendered file contains a relative link that 404s on github.com.
• docs/decisions/README.md explains the two-directory ADR layout and its public/private split.
• The ADR-0012 and ADR-0014 number collisions are disambiguated for readers.
• If option A: .Rbuildignore still excludes the added files from the CRAN tarball — verify with R CMD build that no .md from .github/ ships.
• The chosen posture is noted where the next vendored sync will encounter it.

Out of scope

• Renumbering ADRs — numbers are immutable once accepted, and the vendored ones are not ours to renumber. Disambiguation, not renumbering.
• Changing what the other gitignored vendored directories (.github/skills, .github/agents) do — those are not linked from tracked public docs and are genuinely internal tooling.
• Authoring new ADRs.

Codebase context

• Affected files: .gitignore, docs/decisions/README.md, docs/playbooks/{pick-up-stale-issue,start-new-epic}.md, docs/requirements/{commit-cadence-guidance,_template}.md, .github/copilot-instructions.md.
• Origin: PR chore: sync vendored agent toolkit to renamed upstream agentic-dev #117 Notes, follow-up 2 of 2. Surfaced during the vendored-toolkit sync ([Tech Debt] Sync vendored agent toolkit to renamed upstream pfizer-evgen/agentic-dev #116).
• Upstream counterpart: pfizer-evgen/agentic-dev#397 (ADR number collisions) and #391 (vendored docs linking into commonly-gitignored dirs).
• Sibling follow-up: [Tech Debt] Reconcile the GitHub label set with the vendored vocabulary the issue templates require #118 (label-set reconciliation).

Definition of Ready (mini-checklist)

• Motivation + current pain are concrete
• Acceptance criteria measurable
• Out of scope explicit
• Labels applied (Type + Priority + WSJF bucket) — WSJF bucket label does not exist; see [Tech Debt] Reconcile the GitHub label set with the vendored vocabulary the issue templates require #118
• Parent epic linked above (standalone)

[chris-prener]

Triage — 2026-08-10

• Route: Route 1 — re-parented from standalone to [Epic K] Vendored Workflow Toolkit Adoption & Governance #123 ([Epic K] Vendored Workflow Toolkit Adoption & Governance) via native sub-issue link.
• Assessment: DoR met. Re-parented because [Tech Debt] Reconcile the GitHub label set with the vendored vocabulary the issue templates require #118, [Tech Debt] Tracked public docs link into gitignored .github/vendored-decisions/, so those links 404 #119, and [Tech Debt] Resolve ADR-0014 numbering collision and adopt/decline gate-profile labels #120 share a root cause (vendored skills assuming infrastructure this repo never adopted), a file surface, and a decision dependency — see [Epic K] Vendored Workflow Toolkit Adoption & Governance #123's ## Dependencies. The original standalone justification correctly ruled out Epics H/I/J; Epic K did not exist at filing time. Labels unchanged (documentation, tech-debt, priority/medium).
• Sequencing: blocked by [Tech Debt] Resolve ADR-0014 numbering collision and adopt/decline gate-profile labels #120 — that issue resolves which ADR numbers are real and non-colliding, and this issue publishes links to them. Publishing against a corpus whose numbering is still in flux would need redoing.

Correction — factual drift in the issue body

Verified against the working tree at main today. Two claims in the Current pain section were wrong; I have corrected them inline in the body and recorded the evidence here.

1. ADR file counts were overstated.

The body claimed "Eleven ADR files live in .github/vendored-decisions/; three live in tracked docs/decisions/." Actual contents:

Directory	Count	Files
.github/vendored-decisions/	9	ADR-0001-mandatory-issue-retrospectives, ADR-0002-cross-repo-label-vocabulary, ADR-0003-now-next-later-roadmap-horizons, ADR-0004-auto-filed-issue-protocol, ADR-0005-issue-comment-as-plan-contract, ADR-0006-institutional-gate-vs-in-flight-critique, ADR-0007-directory-separated-adr-vendoring, ADR-0008-subdir-per-skill-layout, ADR-0009-repo-local-skill-coexistence
docs/decisions/	1	ADR-0004-uds-crosswalk-internalization

(Both directories also contain a _template.md and a README.md, which are not ADRs.)

This makes the public-invisibility problem worse than the body described, not better: 9 of the 10 actual ADRs are gitignored, not 11 of 14.

2. The cited collision does not exist; a different one does.

The body named ADR-0012 (verification-independence-invariant vs. hard-vs-soft-lifecycle-gate-enforcement) and ADR-0014 as colliding across the two directories. Neither number exists as a file in either directory. The real, verified collision is:

• docs/decisions/ADR-0004-uds-crosswalk-internalization.md
• .github/vendored-decisions/ADR-0004-auto-filed-issue-protocol.md

Two different documents, same number, different directories — exactly the ambiguity the body describes, just at a different number. This is the collision the acceptance criteria should target.

3. Related finding — the citation gap is much larger than the link-integrity gap.

While verifying the above I enumerated every ADR-NNNN reference across .github/skills/, .github/copilot-instructions.md, and docs/. Numbers ADR-0001 through ADR-0018 are cited. Only ADR-0001–ADR-0009 (vendored) and ADR-0004 (local) exist as files. So ADR-0010 through ADR-0018 are cited but absent from both directories:

Cited ADR	Cited by (sample)
ADR-0010	docs/WORKFLOW.md
ADR-0011	_partials/provider.md, _partials/profile.md, bootstrap_repo/SKILL.md, confluence_docs/SKILL.md
ADR-0012	pr_orchestrator/SKILL.md, pr_gate_qc/SKILL.md, _partials/plan-readiness-predicate.md
ADR-0013	epic/SKILL.md, workflow_audit/SKILL.md, _partials/workflow-audit-categories.md
ADR-0014	pr_orchestrator/SKILL.md, triage/SKILL.md, _partials/label-vocabulary.md
ADR-0015	triage/SKILL.md, backlog_grooming/SKILL.md, epic/SKILL.md
ADR-0016	.github/copilot-instructions.md (model-family routing), workflow_audit/SKILL.md
ADR-0017	pr_orchestrator/SKILL.md, _partials/tech-lead-review-checklist.md
ADR-0018	pr_orchestrator/SKILL.md

Scoping note: this issue's remit is link integrity in tracked public docs — making cited links resolve. The broader "9 cited ADRs have no file at all" gap is a content problem and belongs to #120, which already owns the adopt-vs-decline decision for that layer. Recorded here so the two issues do not each assume the other covered it. Epic K's AC2 spans both.

No repo files were modified in producing this comment — verification was read-only.

---

_{Co-authored-by: Copilot}

[chris-prener]

Implementation plan

Last updated: 2026-08-11T13:53:41Z by Developer
Status: drafting
Sync token: 5254162436:2026-08-11T13:58:28Z

Approach

This issue's own body requires a posture decision (A/B/C) to be made and recorded before any implementation work is scoped: option A (track .github/vendored-decisions/ publicly, removing it from .gitignore), B (stop citing gitignored ADRs from tracked docs), or C (track a generated summary index only). The issue notes the wrong choice is costly to reverse once public docs are updated, and that whichever is chosen must also be recorded so the next vendored sync doesn't silently re-diverge. This is a governance/documentation-posture decision affecting public-facing repo structure, out of Developer-persona scope. The plan for this issue is therefore to hand off to Tech Lead to make and record the decision; once it lands, this plan will be updated (via Update) with the concrete file changes that follow from the chosen option.

Files to touch

• None yet — no implementation files identified until Tech Lead records the posture decision.

Verification

• Tech Lead decision recorded (comment or ADR)
• If option A: verify with R CMD build that no .md from .github/ ships in the CRAN tarball
• Remaining verification steps TBD once the decision is recorded and this plan is updated

Risks / open questions

• Blocking: no tracked-doc edits should proceed until the posture is chosen, since options A/B/C touch different (and in places overlapping) files.
• docs/decisions/README.md needs to explain the two-directory ADR layout and disambiguate the ADR-0004 number collision regardless of which posture is chosen.

Where I left off

Not yet started — awaiting Tech Lead decision.

Decisions made

• 2026-08-11: authored against commit e0875c2
• 2026-08-11: identified that this issue requires a documentation-posture decision with public-facing consequences; routed to Tech Lead rather than proceeding on an assumed option