Skip to content

docs(workflow): C001 trigger-issue draft (PR #381) mixes link bases — one pointer is dead, and the checker strips the fenced draft so it cannot catch it #382

Closed

Description

@dezren39

Finding

PR #381 added a Stage 1 "Trigger Issue Draft" to doc/2026-10-19T06-09-02Z_research_research-intake-to-implementation/concepts/C001-transcript-preservation.md whose three Context Pointers use two different link bases, so no single place the draft can be read or copied from makes all three resolve — and the validation the PR cites cannot catch it, because the draft sits inside a fenced code block that the checker strips before link-checking.

Evidence

  • PR: docs(workflow): prepare research angles and trigger issue for C001 #381 (merged, commit 25bc8067af63ad1aa969da302eb943934e96e983), still present on current main in the same file.
  • Draft Context Pointers (file lines 75–77 on main):
    • [main.md](../main.md#c001) — resolves only relative to concepts/ (→ package main.md, which does exist, with an <a id="c001"> anchor).
    • [transcript.txt](../transcript.txt) — likewise resolves only relative to concepts/.
    • [concepts/C001-transcript-preservation.md](concepts/C001-transcript-preservation.md) — resolves only relative to the package root; relative to concepts/ it points at concepts/concepts/C001-transcript-preservation.md, which does not exist.
    • Verified by path resolution against current main: from concepts/ the first two exist and the third does not; from the package root the third exists and the first two escape to doc/main.md / doc/transcript.txt, which do not exist. Copied verbatim into a GitHub issue (its stated purpose — S1 drafts are the handoff for the research trigger), all three relative links resolve against the issue URL and break.
  • The checker is blind to this by construction: scripts/research_workflow.py prose()/unfenced() strips fenced blocks, and links() runs on prose() output, so the ```markdown draft is exempt from check_link. Reproduced on a clean origin/main snapshot: python3 scripts/research_workflow.py check --repo-root . returns "ok": true while the broken pointer above is present — the same command PR docs(workflow): prepare research angles and trigger issue for C001 #381's body cites as its validation.

Why it matters

Stage 1's whole output is a self-contained, zero-context handoff (planning/workflow/stages.md: S1 = "trigger issue drafting"; C004: trigger issues are "zero-context handoff briefs for dedicated research workers"). A Stage 2 / handoff worker who follows the draft's own Concept Document pointer from the concept file's directory hits a nonexistent path, and one who pastes the draft into an issue gets three dead links. The workflow's link integrity guarantee — the thing check exists to enforce for every other link in the package — silently does not apply to the one artifact meant to leave the package.

Acceptance criteria

  • The C001 trigger draft's Context Pointers all resolve from the draft's intended consumption point (e.g. make the Concept Document pointer C001-transcript-preservation.md / ./C001-transcript-preservation.md if the base is concepts/, or convert all three pointers to full repo-relative/blob URLs if the base is a GitHub issue) — one consistent base, verified by path resolution.
  • scripts/research_workflow.py check (or an equivalent documented check) validates links inside fenced workflow:issue trigger drafts, or the concept doc records explicitly that draft links are unchecked and must be resolved when the issue is created.
  • Re-running the check on the fixed tree passes, and deliberately breaking a pointer inside the draft makes the (extended) check fail.

Found by the pr-diff-review job reviewing PR #381 (merged) in developing-today/code. Cross-repo check: this research package and scripts/research_workflow.py exist only in developing-today/code, so this is a single-repo issue. Deduped: no open or closed issue mentions C001, the trigger draft, or research_workflow link checking.

Activity

  1. added a commit that references this issue on Oct 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions