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.md — pituitary 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:
- 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.
- 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.
Problem
check-doc-drift,check-compliance, andcheck-terminologyall require aspec_bundlesource to anchor against. For projects that haven't adopted thespec_bundledirectory structure — i.e., projects whose design lives in flat root-level markdown files likeARCHITECTURE.mdandREADME.md—pituitary discovercorrectly classifies these asmarkdown_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_bundlelayout. That migration is non-trivial and probably blocks adoption on existing codebases evaluating pituitary.Reproduction
dusk-network/stromahas all its design at the repo root (ARCHITECTURE.md,README.md,BENCHMARKS.md) plusdocs/vector-backend-v4.md. All flat markdown.git clone https://github.com/dusk-network/stroma /tmp/stroma cd /tmp/stroma pituitary discoverResult:
.pituitary/pituitary.tomlis created with two sources, bothkind = \"markdown_docs\"— one forscripts/READMEs and one for root-levelAGENTS.md/ARCHITECTURE.md/README.md. Nospec_bundlesource. No anchor.…has no spec to anchor against.
Suggested direction
Allow a flat markdown file to act as the drift-check anchor. Two plausible shapes:
markdown_docssource. Something like[[sources]] kind = \"markdown_docs\"; is_spec_anchor = true; anchor_files = [\"ARCHITECTURE.md\"]. The named files become synthetic specs for governance purposes.spec_anchor. Wraps one or more markdown files as synthetic spec_bundles. Less ambiguous than overloadingmarkdown_docs.Either way, drift reports could then say e.g. "
README.mddrifts fromARCHITECTURE.md: schema version stated as 9 in README, 8 in ARCHITECTURE" without needing aspecs/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.