Skip to content

Support flat markdown files as drift-check anchors (not just spec_bundles) #403

@autholykos

Description

@autholykos

Problem

check-doc-drift, check-compliance, and check-terminology all require a spec_bundle source to anchor against. For projects that haven't adopted the spec_bundle directory structure — i.e., projects whose design lives in flat root-level markdown files like ARCHITECTURE.md and README.mdpituitary discover correctly classifies these as markdown_docs, but there is no anchor source available, so the drift checks have nothing to compare against.

Net effect: pituitary's flagship governance features are unreachable for any project that hasn't first migrated its design docs into the spec_bundle layout. That migration is non-trivial and probably blocks adoption on existing codebases evaluating pituitary.

Reproduction

dusk-network/stroma has all its design at the repo root (ARCHITECTURE.md, README.md, BENCHMARKS.md) plus docs/vector-backend-v4.md. All flat markdown.

git clone https://github.com/dusk-network/stroma /tmp/stroma
cd /tmp/stroma
pituitary discover

Result: .pituitary/pituitary.toml is created with two sources, both kind = \"markdown_docs\" — one for scripts/ READMEs and one for root-level AGENTS.md/ARCHITECTURE.md/README.md. No spec_bundle source. No anchor.

pituitary check-doc-drift --scope all

…has no spec to anchor against.

Suggested direction

Allow a flat markdown file to act as the drift-check anchor. Two plausible shapes:

  1. Opt-in flag on markdown_docs source. Something like [[sources]] kind = \"markdown_docs\"; is_spec_anchor = true; anchor_files = [\"ARCHITECTURE.md\"]. The named files become synthetic specs for governance purposes.
  2. New source kind spec_anchor. Wraps one or more markdown files as synthetic spec_bundles. Less ambiguous than overloading markdown_docs.

Either way, drift reports could then say e.g. "README.md drifts from ARCHITECTURE.md: schema version stated as 9 in README, 8 in ARCHITECTURE" without needing a specs/ migration.

Discovered while

Building a per-project research advisor (workbench/hippocampus-backed corpus + chatbot) that ingests project docs + a generated implementation memo for stroma. Wanted pituitary to verify that the memo doesn't contradict ARCHITECTURE.md and that ARCHITECTURE.md itself doesn't drift from current code (real drift was found by hand: schema 9 vs 8, vector storage table renamed, etc.). Pituitary is the right tool conceptually, but currently can't run on stroma's layout.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions