feat(platformctl): implement `lint --cross-refs` to catch INDEX/ADR/runbook integrity drift automatically #767

New issue

Closed

opened 2026-06-08 23:19:51 +02:00 by ollama · 0 comments

ollama commented

2026-06-08 23:19:51 +02:00

Collaborator

Spec sources (whitelist)

modules/INDEX.yaml — cross-reference against module manifests
modules/*/module.yaml — all 88 module manifests
modules/*/runbook.md — existence check vs module manifest
decisions/ — all ADR files
MAP.md — references to ADRs
AGENTS.md — references to ADRs
README.md — references to ADRs
state/ — references to ADRs
control-plane/platformctl/cli.py — where to add subcommand
schema/module.schema.json — module structure

Extracted context

Multiple cross-reference integrity issues have been found in audits:

INDEX.yaml lifecycle drifted from module manifests (#752)
Duplicate ADR-0023 (#756)
Phantom ADR references in MAP.md (fixed in #748)
Runbooks with no parent module (potential)

A lint command would catch these early, before they become issues.

Scope

Implement platformctl lint --cross-refs that checks:

INDEX.yaml vs modules: every module in INDEX.yaml has a matching module.yaml, and every module.yaml has an INDEX.yaml entry. Lifecycle, criticality, area, host match.
ADR numbering: no duplicate numbers, no gaps in sequence (warning), all referenced ADRs exist.
ADR references: all ADR-00XX references in repo docs point to existing files.
Runbook coverage: every module.yaml has a runbook.md, every runbook.md has a parent module.yaml.

Exit codes: 0=all clean, 3=validation errors, 0 with warnings=advisory findings.

Acceptance criteria

platformctl lint --cross-refs catches all 4 check types
Detects the known issues: INDEX.yaml drift, duplicate ADR, orphan runbooks
JSON output for CI integration
715+ existing tests still green
CI workflow note: add cross-ref lint as prebuild check

Do NOT read

Full repo — only files needed for implementation

Agent notes

Recommended executor: Gemini 3.1 Pro (new platformctl command)
Size: Medium (~200 lines)
Review tier: tier/medium (new CI-enforceable command)
Audit ref: state/audit/deepseek-2026-06-08-multiperspective.md §Improvement #5

## Spec sources (whitelist) - `modules/INDEX.yaml` — cross-reference against module manifests - `modules/*/module.yaml` — all 88 module manifests - `modules/*/runbook.md` — existence check vs module manifest - `decisions/` — all ADR files - `MAP.md` — references to ADRs - `AGENTS.md` — references to ADRs - `README.md` — references to ADRs - `state/` — references to ADRs - `control-plane/platformctl/cli.py` — where to add subcommand - `schema/module.schema.json` — module structure ## Extracted context Multiple cross-reference integrity issues have been found in audits: - INDEX.yaml lifecycle drifted from module manifests (#752) - Duplicate ADR-0023 (#756) - Phantom ADR references in MAP.md (fixed in #748) - Runbooks with no parent module (potential) A lint command would catch these early, before they become issues. ## Scope Implement `platformctl lint --cross-refs` that checks: 1. **INDEX.yaml vs modules**: every module in INDEX.yaml has a matching module.yaml, and every module.yaml has an INDEX.yaml entry. Lifecycle, criticality, area, host match. 2. **ADR numbering**: no duplicate numbers, no gaps in sequence (warning), all referenced ADRs exist. 3. **ADR references**: all `ADR-00XX` references in repo docs point to existing files. 4. **Runbook coverage**: every module.yaml has a runbook.md, every runbook.md has a parent module.yaml. Exit codes: 0=all clean, 3=validation errors, 0 with warnings=advisory findings. ## Acceptance criteria - [ ] `platformctl lint --cross-refs` catches all 4 check types - [ ] Detects the known issues: INDEX.yaml drift, duplicate ADR, orphan runbooks - [ ] JSON output for CI integration - [ ] 715+ existing tests still green - [ ] CI workflow note: add cross-ref lint as prebuild check ## Do NOT read - Full repo — only files needed for implementation ## Agent notes - Recommended executor: Gemini 3.1 Pro (new platformctl command) - Size: Medium (~200 lines) - Review tier: tier/medium (new CI-enforceable command) - Audit ref: state/audit/deepseek-2026-06-08-multiperspective.md §Improvement #5

ollama referenced this issue from a pull request that will close it,

2026-06-08 23:31:21 +02:00

feat(platformctl): automated truth-verification layer — lint --cross-refs + drift-check #772