Skip to content

bug: 21 pre-existing corpus citations fail validate.py's file-resolution check on origin/launchpad #1951

New issue
New issue
Closed
Closed
bug: 21 pre-existing corpus citations fail validate.py's file-resolution check on origin/launchpad#1951
Labels
area:docsThe MkDocs knowledge layer and its contentby:agentFiled or authored by an AI agent, not a humanneeds-triageType unclear or required content missing — a human must looktype:bugExists and behaves incorrectly

Description

@serina-mcfall
serina-mcfall
opened on Aug 31, 2026

Problem

At origin/launchpad revision cad6c375fdcc590158c1456c9fc7875f0f84a844, a full
python3 launchpad/project-intelligence/corpus/validate.py run (no --root, so it
validates the whole launchpad/docs/corpus/ tree) exits 1 with 21 FAIL lines, all
of the form "does not resolve to a real file in the repository". None of these are in
a node I authored or touched — they are pre-existing on origin/launchpad before this
task's change. Found while completing issue #699 (capabilities/activity/activity-feed.md)
and confirmed by stashing that new file and re-running against a clean origin/launchpad
checkout, which reproduces the identical 21 failures.

Related to #1631, which documents that the validator's exit code is corpus-wide and
not a verdict on any single node — this issue is the concrete list of currently-broken
citations that fact implies, so a future corpus-wide validate.py run is not silently
assumed clean.

Affected nodes (FAIL lines at the above revision)

  • architecture-containers-postgres — evidence entry 9, citation 1; entry 16, citation 2
  • architecture-context-human-user — evidence entry 2, citation 2; entry 3, citation 2; entry 4, citations 2 and 3
  • architecture-flows-event-ingestion — evidence entry 4, citation 2; entry 19, citation 1; entry 21, citation 2
  • architecture-flows-workflow-execution — evidence entry 13, citation 1; entry 31, citation 1
  • architecture-principles-community-is-security-boundary — evidence entry 7, citations 1 and 2; entry 14, citation 2
  • corpus-template-data-entity — evidence entry 16, citation 2; entry 22, citation 2
  • corpus-template-datastore — evidence entry 19, citation 1; entry 22, citation 2
  • corpus-template-invariant — evidence entry 9, citations 1 and 2; entry 13, citation 1

Reproduction

python3 launchpad/project-intelligence/corpus/validate.py

Exit code 1; the FAIL lines above are printed among the output (also a long list of
non-fatal UNVERIFIED notices for commit/URL/graph-edge citations, which are expected
and not part of this bug).

Impact

Every corpus-authoring task in the current batch (Feature #613 and siblings) that runs
this validator locally sees a non-zero exit unrelated to its own new node, which is
exactly the false-attribution risk #1631 flags for the corpus-review skill. A human
or agent fixing these 21 citations needs to open each node, find what the citation
meant to point at, and correct or remove it — that is out of scope for any single
document-authoring task and belongs in its own fix.

Impacted components

  • launchpad/docs/corpus/architecture/containers/postgres.md
  • launchpad/docs/corpus/architecture/context/human-user.md
  • launchpad/docs/corpus/architecture/flows/event-ingestion.md
  • launchpad/docs/corpus/architecture/flows/workflow-execution.md
  • launchpad/docs/corpus/architecture/principles/community-is-security-boundary.md
  • launchpad/docs/corpus/templates/data-entity.md
  • launchpad/docs/corpus/templates/datastore.md
  • launchpad/docs/corpus/templates/invariant.md

Activity

  1. github-actions
    added
    needs-triageType unclear or required content missing — a human must look
    on Aug 31, 2026

  2. github-actions commented on Aug 31, 2026

    @github-actions
    github-actionsBot
    on Aug 31, 2026 – with GitHub Actions

    Issue body check failed — this issue is missing required content.

    • No type: label. Every issue needs exactly one.

    Templates: .github/ISSUE_TEMPLATE/ · Triage rules: launchpad/AGENTS.md

    Edit the issue to fix — this check re-runs automatically.

  3. serina-mcfall
    added 2 commits that reference this issue on Aug 31, 2026

    docs(corpus): document capabilities/agents/persona (#715)

    bcedbc0

    fix(corpus): resolve review-final's two Feature #613 findings

    d4f1b2b
  4. serina-mcfall
    added
    type:bugExists and behaves incorrectly
    by:agentFiled or authored by an AI agent, not a human
    area:docsThe MkDocs knowledge layer and its content
    and removed
    needs-triageType unclear or required content missing — a human must look
    on Sep 1, 2026
  5. github-actions
    added
    needs-triageType unclear or required content missing — a human must look
    on Sep 1, 2026

  6. github-actions commented on Sep 1, 2026

    @github-actions
    github-actionsBot
    on Sep 1, 2026 – with GitHub Actions

    Issue body check failed — this issue is missing required content.

    • Missing section: Observed behaviour
    • Missing section: Expected behaviour
    • Missing section: Environment

    Templates: .github/ISSUE_TEMPLATE/ · Triage rules: launchpad/AGENTS.md

    Edit the issue to fix — this check re-runs automatically.

  7. github-actions commented on Sep 1, 2026

    @github-actions
    github-actionsBot
    on Sep 1, 2026 – with GitHub Actions

    Issue body check failed — this issue is missing required content.

    • Missing section: Observed behaviour
    • Missing section: Expected behaviour
    • Missing section: Environment

    Templates: .github/ISSUE_TEMPLATE/ · Triage rules: launchpad/AGENTS.md

    Edit the issue to fix — this check re-runs automatically.

  8. github-actions commented on Sep 1, 2026

    @github-actions
    github-actionsBot
    on Sep 1, 2026 – with GitHub Actions

    Issue body check failed — this issue is missing required content.

    • Missing section: Observed behaviour
    • Missing section: Expected behaviour
    • Missing section: Environment

    Templates: .github/ISSUE_TEMPLATE/ · Triage rules: launchpad/AGENTS.md

    Edit the issue to fix — this check re-runs automatically.

  9. github-actions commented on Sep 1, 2026

    @github-actions
    github-actionsBot
    on Sep 1, 2026 – with GitHub Actions

    Issue body check failed — this issue is missing required content.

    • Missing section: Observed behaviour
    • Missing section: Expected behaviour
    • Missing section: Environment

    Templates: .github/ISSUE_TEMPLATE/ · Triage rules: launchpad/AGENTS.md

    Edit the issue to fix — this check re-runs automatically.

  10. serina-mcfall commented on Sep 1, 2026

    @serina-mcfall
    serina-mcfall
    on Sep 1, 2026
    Author

    Root cause found

    Traced this while investigating why "Validate the real corpus" was red on
    several open corpus PRs. All 21 FAIL lines resolve to the exact same root
    cause: upstream commit a3730784f — refactor(db): extract domain stores from database runtime (#6987), merged 2026-08-28 — moved
    crates/buzz-db/src/*.rs into two new subdirectories:

    • data-access modules → crates/buzz-db/src/store/*.rs
    • connection/runtime internals → crates/buzz-db/src/runtime/*.rs

    That refactor was already on origin/launchpad before every affected corpus
    document was authored, so the 21 citations were stale from the moment they
    were written, not broken later by a race. validate.py is correctly
    reporting real breakage — not a validator bug.

    Old → current path map (covers all 21 citations)

    Cited (stale) path Current path
    crates/buzz-db/src/migration.rs crates/buzz-db/src/runtime/migration.rs
    crates/buzz-db/src/replica_fence.rs crates/buzz-db/src/runtime/replica_fence.rs
    crates/buzz-db/src/user.rs crates/buzz-db/src/store/user.rs
    crates/buzz-db/src/channel.rs crates/buzz-db/src/store/channel.rs
    crates/buzz-db/src/deletion.rs crates/buzz-db/src/store/deletion.rs
    crates/buzz-db/src/event.rs crates/buzz-db/src/store/event.rs
    crates/buzz-db/src/workflow.rs crates/buzz-db/src/store/workflow.rs
    crates/buzz-db/src/thread.rs crates/buzz-db/src/store/thread.rs
    crates/buzz-db/src/push.rs crates/buzz-db/src/store/push.rs

    Currently blocking

    I checked live CI status on every open corpus PR. These three are red on
    validate with these exact same 21 errors, and the 8 affected files are
    byte-identical across all three branches (confirmed via
    git hash-object) — the stale content was carried into all three from a
    shared point, not authored independently three times:

    Parent features

    The 8 affected documents split across two parent Features — worth fixing
    under whichever owns the majority, or as a standalone cross-cutting fix
    referencing both:

    • feature: canonical Buzz architecture corpus exists #608 (feature: canonical Buzz architecture corpus exists) — owns 5 of
      the 8 documents / 14 of the 21 citations: architecture-containers-postgres,
      architecture-context-human-user, architecture-flows-event-ingestion,
      architecture-flows-workflow-execution,
      architecture-principles-community-is-security-boundary
    • feature: documentation corpus contract is executable #605 (feature: documentation corpus contract is executable) — owns the
      3 templates/* documents / 7 citations: corpus-template-data-entity,
      corpus-template-datastore, corpus-template-invariant

    Related

    This is also the reason PR #2001's test_committed_corpus_json_copies_match_a_fresh_packaging_run
    drift-guard test fails — its assertion diff shows the same
    migration.rs → runtime/migration.rs fingerprint. That's a separate bug
    (a stale packaged corpus.json under Feature #532), tracked as a new issue
    rather than folded in here since the fix and owning Feature differ.

    Also relevant: #1631, which is the process gap that let a corpus-wide
    validate.py failure like this one go unnoticed by individual node reviews
    — worth revisiting once these 21 citations are fixed, so the next upstream
    refactor doesn't reproduce this silently across another batch of PRs.

  11. serina-mcfall commented on Sep 1, 2026

    @serina-mcfall
    serina-mcfall
    on Sep 1, 2026
    Author

    Filed the sibling packaging-drift issue: #2004 (same upstream cause, different failure mechanism — #2001's committed corpus.json vs. a fresh just knowledge-package run).

  12. serina-mcfall commented on Sep 1, 2026

    @serina-mcfall
    serina-mcfall
    on Sep 1, 2026
    Author

    Also filed #2005 — the deeper process gap this exposed: PR #1952 (Feature #611, unrelated) independently re-drafted these same 8 shared node ids with different, conflicting citations. Its version happened to be more correct (verified against current code) so I used it as the basis for the merge fix here, but that was luck, not a guarantee.

  13. serina-mcfall
    added a commit that references this issue on Sep 1, 2026

    fix(corpus): repoint 21 evidence citations to post-refactor buzz-db p…

    2cc22a2

  14. serina-mcfall commented on Sep 4, 2026

    @serina-mcfall
    serina-mcfall
    on Sep 4, 2026
    Author

    Already fixed — 0 FAIL lines at current origin/launchpad HEAD

    Investigated per the agentic-debugging / root-cause-analysis process before touching anything.

    Re-ran the exact reproduction (python3 launchpad/project-intelligence/corpus/validate.py, no --root) against current origin/launchpad HEAD (aef93f2c2a), in a clean worktree from origin/launchpad:

    PASS  corpus validation found no errors; 593 item(s) reported unverified

    Exit code 0, zero FAIL/ERROR lines. All 21 citations named in this issue (across all 8 affected nodes) currently resolve to real files at valid line ranges — verified each one directly against the filesystem.

    Root cause of the discrepancy with the 21 originally reported: this issue was filed against revision cad6c375f, a commit that is an ancestor of current launchpad HEAD but is not a descendant of commit 81fd0e120f ("docs(corpus): repoint citations broken by sync-upstream-2026-08-31 buzz-db reorg", authored by Serina, Aug 31 13:06). That commit already re-pointed all 21 of these exact citations (same 8 nodes, same evidence-entry numbers) after the sync-upstream-2026-08-31 buzz-db reorg (ed133f4c5) moved event.rs, channel.rs, user.rs, thread.rs, workflow.rs, push.rs, deletion.rs, migration.rs, and replica_fence.rs into store//runtime/ submodules. cad6c375f's branch forked before 81fd0e120f landed, so the issue's reproduction (taken on that stale base) still showed the break; by the time both merged into launchpad, the fix was already present.

    Also checked issue #2004's migration.rs → runtime/migration.rs lead specifically — that move is exactly what 81fd0e120f already repointed (architecture-containers-postgres entries 9/16, corpus-template-datastore entry 19).

    No code change needed — nothing to fix. Recommend closing as already-resolved-by-81fd0e120f, or as a duplicate/stale report. Leaving that call to a human per this session's process (not closing it myself).

  15. tucktuck101
    closed this as completedin 2cc22a2on Sep 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsThe MkDocs knowledge layer and its contentby:agentFiled or authored by an AI agent, not a humanneeds-triageType unclear or required content missing — a human must looktype:bugExists and behaves incorrectly

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions