pdurlej/platform

Fork 0

feat(platformctl): add cross-reference lint #783

Merged

pdurlej merged 3 commits from codex/issues/767-cross-ref-lint into main

2026-06-17 23:14:35 +02:00

codex commented

2026-06-10 23:46:41 +02:00

Collaborator

Canary status: missing - fire canary 3+3 manually before merge

Canary Context Pack

Product story

Operators and future agents need a deterministic prebuild check for repository metadata drift instead of rediscovering INDEX/module, ADR, and runbook inconsistencies through ad hoc audits.

What changed

Added platformctl lint --cross-refs [--json].
Checks modules/INDEX.yaml against module manifests for missing entries and lifecycle/criticality/area/host drift.
Checks ADR duplicate numbers, ADR sequence gaps as warnings, and missing local ADR references in markdown docs/state/decisions.
Checks module runbook coverage and orphan runbooks.
Added fixture-based tests for clean output, module/index drift, ADR duplicates, missing ADR references, ADR gap warnings, runbook coverage, and CLI JSON behavior.

Why it changed

Issue #767 asks for a CI-ready lint command that catches cross-reference integrity drift before it turns into repeated audit work.

Files touched

control-plane/platformctl/cli.py
control-plane/platformctl/cross_refs.py
control-plane/platformctl/tests/test_cross_refs.py

Relevant context

Issue #767 spec sources: modules/INDEX.yaml, module manifests/runbooks, decisions/, MAP.md, AGENTS.md, README.md, state/, docs/, control-plane/platformctl/cli.py.
GLM scout was used for scope/false-positive mapping; it hallucinated Go paths, so only the risk notes were retained.
Kimi red-team was attempted for false positives but timed out; implementation uses the conservative mitigations already identified: ADR gaps are warnings, repeated missing ADR references are deduplicated per file, and scanning is limited to markdown reference surfaces.

Runtime evidence

No live runtime access. This is filesystem-only linting.

Known constraints

Real current repo is not clean under the new check. A read-only run currently reports 10 errors and 5 warnings: one openclaw-mail-gateway INDEX/module host drift, missing ADR references for ADR-0008/0012/0027/0028, and ADR gap warnings for 0008/0009/0012/0014/0015.
The command is not wired into required branch protection in this PR.

Explicit out-of-scope

No autofix of INDEX.yaml, ADR docs, or runbooks.
No CI/branch-protection change.
No live runtime, Forgejo mutation, or issue/comment writes.

Requested decision

Approve the linter surface and tests. Existing findings should be fixed in follow-up PRs/issues, not hidden in this implementation PR.

Merge blockers

Any live/runtime mutation.
Exit 3 for warnings-only cases.
No JSON output for CI consumers.
Undeduplicated missing-ADR noise that makes findings unreadable.

Spec sources read

Issue #767 body from Forgejo.
control-plane/platformctl/cli.py for command registration conventions.
control-plane/platformctl/manifest.py for module metadata shape.
modules/INDEX.yaml for index structure.
decisions/ filenames for ADR numbering convention.
control-plane/platformctl/tests/test_validate.py for CLI/test style.

Verification

UV_CACHE_DIR=/Users/pd/Developer/platform/.uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests/test_cross_refs.py -q -> 7 passed
UV_CACHE_DIR=/Users/pd/Developer/platform/.uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests -q -> 734 passed
UV_CACHE_DIR=/Users/pd/Developer/platform/.uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev python -m platformctl.cli lint --cross-refs --json -> exit 3 with 10 errors / 5 warnings on current repo state
git diff --check -> passed

Closes #767

Canary status: missing - fire canary 3+3 manually before merge ## Canary Context Pack ### Product story Operators and future agents need a deterministic prebuild check for repository metadata drift instead of rediscovering INDEX/module, ADR, and runbook inconsistencies through ad hoc audits. ### What changed - Added `platformctl lint --cross-refs [--json]`. - Checks modules/INDEX.yaml against module manifests for missing entries and lifecycle/criticality/area/host drift. - Checks ADR duplicate numbers, ADR sequence gaps as warnings, and missing local ADR references in markdown docs/state/decisions. - Checks module runbook coverage and orphan runbooks. - Added fixture-based tests for clean output, module/index drift, ADR duplicates, missing ADR references, ADR gap warnings, runbook coverage, and CLI JSON behavior. ### Why it changed Issue #767 asks for a CI-ready lint command that catches cross-reference integrity drift before it turns into repeated audit work. ### Files touched - `control-plane/platformctl/cli.py` - `control-plane/platformctl/cross_refs.py` - `control-plane/platformctl/tests/test_cross_refs.py` ### Relevant context - Issue #767 spec sources: `modules/INDEX.yaml`, module manifests/runbooks, `decisions/`, `MAP.md`, `AGENTS.md`, `README.md`, `state/`, `docs/`, `control-plane/platformctl/cli.py`. - GLM scout was used for scope/false-positive mapping; it hallucinated Go paths, so only the risk notes were retained. - Kimi red-team was attempted for false positives but timed out; implementation uses the conservative mitigations already identified: ADR gaps are warnings, repeated missing ADR references are deduplicated per file, and scanning is limited to markdown reference surfaces. ### Runtime evidence No live runtime access. This is filesystem-only linting. ### Known constraints - Real current repo is not clean under the new check. A read-only run currently reports 10 errors and 5 warnings: one `openclaw-mail-gateway` INDEX/module host drift, missing ADR references for ADR-0008/0012/0027/0028, and ADR gap warnings for 0008/0009/0012/0014/0015. - The command is not wired into required branch protection in this PR. ### Explicit out-of-scope - No autofix of INDEX.yaml, ADR docs, or runbooks. - No CI/branch-protection change. - No live runtime, Forgejo mutation, or issue/comment writes. ### Requested decision Approve the linter surface and tests. Existing findings should be fixed in follow-up PRs/issues, not hidden in this implementation PR. ### Merge blockers - Any live/runtime mutation. - Exit 3 for warnings-only cases. - No JSON output for CI consumers. - Undeduplicated missing-ADR noise that makes findings unreadable. ## Spec sources read - Issue #767 body from Forgejo. - `control-plane/platformctl/cli.py` for command registration conventions. - `control-plane/platformctl/manifest.py` for module metadata shape. - `modules/INDEX.yaml` for index structure. - `decisions/` filenames for ADR numbering convention. - `control-plane/platformctl/tests/test_validate.py` for CLI/test style. ## Verification - `UV_CACHE_DIR=/Users/pd/Developer/platform/.uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests/test_cross_refs.py -q` -> 7 passed - `UV_CACHE_DIR=/Users/pd/Developer/platform/.uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests -q` -> 734 passed - `UV_CACHE_DIR=/Users/pd/Developer/platform/.uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev python -m platformctl.cli lint --cross-refs --json` -> exit 3 with 10 errors / 5 warnings on current repo state - `git diff --check` -> passed Closes #767

codex added 1 commit

2026-06-10 23:46:41 +02:00

feat(platformctl): add cross-reference lint

platformctl plan / auto-apply scope (pull_request) Waiting to run

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Waiting to run

Details

python-ci / Python 3.11 (pull_request) Waiting to run

Details

python-ci / Python 3.12 (pull_request) Waiting to run

Details

python-ci / Python 3.13 (pull_request) Waiting to run

Details

patchwarden-pr-sanity / collect-diff (pull_request) Has been cancelled

Details

base-is-main / guard (pull_request) Successful in 2s

Details

canary-required / collect-diff (pull_request) Successful in 4s

Details

canary-required / canary (pull_request) Waiting to run

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 3s

Details

patchwarden-client-dry-run / dry-run (pull_request) Waiting to run

Details

patchwarden-pr-sanity / sanity (pull_request) Has been cancelled

Details

0f01159478

ollama added 1 commit

2026-06-10 23:58:44 +02:00

Merge remote-tracking branch 'origin/main' into codex/issues/767-cross-ref-lint-merge

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 18s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 17s

Details

python-ci / Python 3.11 (pull_request) Successful in 40s

Details

base-is-main / guard (pull_request) Successful in 1s

Details

canary-required / collect-diff (pull_request) Successful in 4s

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 3s

Details

python-ci / Python 3.12 (pull_request) Successful in 43s

Details

python-ci / Python 3.13 (pull_request) Successful in 42s

Details

patchwarden-client-dry-run / dry-run (pull_request) Failing after 16s

Details

canary-required / canary (pull_request) Successful in 14s

Details

patchwarden-pr-sanity / sanity (pull_request) Has been cancelled

Details

6ad731aa75

# Conflicts:
#	control-plane/platformctl/cli.py

codex referenced this pull request

2026-06-11 00:01:20 +02:00

fix(modules): align openclaw mail gateway index host #786

codex referenced this pull request

2026-06-11 00:14:03 +02:00

docs(agent-readiness): clean stale ADR references #787

ollama added 1 commit

2026-06-11 00:23:09 +02:00

Merge remote-tracking branch 'origin/main' into codex/issues/767-cross-ref-lint-refresh

canary-required / collect-diff (pull_request) Successful in 4s

Details

platformctl plan / auto-apply scope (pull_request) Successful in 20s

Details

python-ci / Python 3.11 (pull_request) Successful in 41s

Details

python-ci / Python 3.13 (pull_request) Successful in 42s

Details

pyfallow / Pyfallow gate (control-plane) (pull_request) Successful in 19s

Details

python-ci / Python 3.12 (pull_request) Successful in 43s

Details

canary-required / canary (pull_request) Successful in 14s

Details

base-is-main / guard (pull_request) Successful in 2s

Details

patchwarden-pr-sanity / collect-diff (pull_request) Successful in 4s

Details

patchwarden-client-dry-run / dry-run (pull_request) Failing after 20s

Details

patchwarden-client-dry-run / collect-diff (pull_request) Successful in 4s

Details

patchwarden-pr-sanity / sanity (pull_request) Successful in 5m47s

Details

be9acfd62b

patchwarden commented

2026-06-11 00:36:31 +02:00

First-time contributor

Patchwarden PR sanity

Status: advisory_findings
PR: 783
Commit: be9acfd62badbd1ade6ebea62bf352ea05cd27e4
Security-sensitive label: missing
Authority: advisory model review plus deterministic blockers only
3+3 canary: still alive; this does not replace it

Deterministic findings

No deterministic findings.

Model reviewers

`global-glm` / `glm-5.1:cloud`

Status: ok
Verdict: OK
Findings: none

`global-deepseek` / `deepseek-v4-pro:cloud`

Status: ok
Verdict: OK
Findings: none

`redteam` / `kimi-k2.6:cloud`

Status: ok
Verdict: NOT_OK
high Malformed YAML causes linter crash instead of findings
- Evidence: control-plane/platformctl/cross_refs.py _check_modules: index_entry.get('classification', {}).get('lifecycle')andmanifest.get('spec', {}).get('classification', {})assume nested dicts; if INDEX.yaml setsclassification: null or mo
- Next: Use defensive coercion like (payload.get('metadata') or {}).get('id') and (manifest.get('spec') or {}).get('classification', {}) throughout, so schema drift is captured as findings rather than unhandled exceptions.

Policy notes

GLM 5.1 + DeepSeek V4 Pro are the operator-required model mix for this bot.
Optional red-team model is enabled only when PLATFORMCTL_PR_SANITY_REDTEAM_MODEL is configured.
Auto-merge is not enabled here.

# Patchwarden PR sanity - Status: `advisory_findings` - PR: `783` - Commit: `be9acfd62badbd1ade6ebea62bf352ea05cd27e4` - Security-sensitive label: `missing` - Authority: advisory model review plus deterministic blockers only - 3+3 canary: still alive; this does not replace it ## Deterministic findings No deterministic findings. ## Model reviewers ### `global-glm` / `glm-5.1:cloud` - Status: `ok` - Verdict: `OK` - Findings: none ### `global-deepseek` / `deepseek-v4-pro:cloud` - Status: `ok` - Verdict: `OK` - Findings: none ### `redteam` / `kimi-k2.6:cloud` - Status: `ok` - Verdict: `NOT_OK` - **`high`** Malformed YAML causes linter crash instead of findings - Evidence: `control-plane/platformctl/cross_refs.py `_check_modules`: `index_entry.get('classification', {}).get('lifecycle')` and `manifest.get('spec', {}).get('classification', {})` assume nested dicts; if INDEX.yaml sets `classification: null` or mo` - Next: Use defensive coercion like `(payload.get('metadata') or {}).get('id')` and `(manifest.get('spec') or {}).get('classification', {})` throughout, so schema drift is captured as findings rather than unhandled exceptions. ## Policy notes - GLM 5.1 + DeepSeek V4 Pro are the operator-required model mix for this bot. - Optional red-team model is enabled only when `PLATFORMCTL_PR_SANITY_REDTEAM_MODEL` is configured. - Auto-merge is not enabled here.

codex referenced this pull request

2026-06-11 00:52:42 +02:00

ci(patchwarden): soft-fail advisory review failures #789

codex added the

labels

2026-06-11 08:14:18 +02:00

pdurlej commented

2026-06-17 23:14:23 +02:00

Owner

operator_override / PR-zero queue collapse evidence for #783.

I rechecked this PR as a local non-committed merge onto the current origin/main after PRs #786/#787/#790/#784 were already merged:

git merge --no-commit --no-ff codex/issues/767-cross-ref-lint in a scratch worktree merged cleanly.
git diff --check HEAD passed.
UV_CACHE_DIR=/tmp/platform-uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests/test_cross_refs.py -q -> 7 passed.
UV_CACHE_DIR=/tmp/platform-uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests -q -> 756 passed.
platformctl lint --cross-refs --json on the integrated tree now reports 0 errors / 5 warnings and exits 0; earlier openclaw/ADR-reference errors were removed by preceding PR-zero merges.

This is aligned with the live queue-collapse scope and safe to merge despite pending/stale CI checks.

operator_override / PR-zero queue collapse evidence for #783. I rechecked this PR as a local non-committed merge onto the current `origin/main` after PRs #786/#787/#790/#784 were already merged: - `git merge --no-commit --no-ff codex/issues/767-cross-ref-lint` in a scratch worktree merged cleanly. - `git diff --check HEAD` passed. - `UV_CACHE_DIR=/tmp/platform-uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests/test_cross_refs.py -q` -> 7 passed. - `UV_CACHE_DIR=/tmp/platform-uv-cache PYTHONPATH=control-plane uv run --project control-plane --extra dev pytest control-plane/platformctl/tests -q` -> 756 passed. - `platformctl lint --cross-refs --json` on the integrated tree now reports 0 errors / 5 warnings and exits 0; earlier openclaw/ADR-reference errors were removed by preceding PR-zero merges. This is aligned with the live queue-collapse scope and safe to merge despite pending/stale CI checks.

pdurlej merged commit 2ff9d1f372 into main

2026-06-17 23:14:35 +02:00

pdurlej referenced this pull request from a commit

2026-06-17 23:14:37 +02:00

Merge pull request #783 from codex/issues/767-cross-ref-lint

pdurlej referenced this pull request

2026-06-17 23:17:19 +02:00

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

pdurlej referenced this pull request

2026-06-17 23:17:52 +02:00

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