pdurlej/platform

Fork 0

feat(platformctl): validate manifests against jsonschema #119

Merged

pdurlej merged 1 commit from codex/issues/63-validate-jsonschema into main

2026-05-09 23:37:52 +02:00

codex commented

2026-05-09 00:43:24 +02:00

Collaborator

Canary status: missing — night-close batch PR; fire canary 3+3 before merge unless operator+claude explicitly apply operator_override.

Closes #63

Canary Context Pack

Product story

Phase 02 cataloging needs a deterministic local validation gate before agents start upgrading manifests. platformctl validate should reject schema-invalid manifests and optionally check the Phase 02 v2 audit fields, so Codex/Claude can trust a boring command instead of eyeballing YAML.

What changed

Added platformctl validate --strict-v2.
Made validate accept either a module id, a modules/<id>/ directory, or a direct module.yaml path.
Added v2 schema loading with local $ref resolution to module.schema.json.
Added strict Phase 02 v2 field checks for intent/runtime audit fields.
Added focused CLI regression tests for valid, missing required, extra field, wrong type, strict-v2 missing fields, and real module path validation.

Why it changed

Issue #63 is the deterministic validation foundation for the rest of the night-close work. The prompt's original premise said load_manifest did not call jsonschema, but current main already does; this PR keeps that existing v1 validation and adds the missing strict-v2/path/test coverage.

Files touched

control-plane/platformctl/cli.py
control-plane/platformctl/manifest.py
control-plane/platformctl/schema.py
control-plane/platformctl/tests/test_validate.py

Relevant context

schema/module.schema.json remains the default v1 schema.
schema/module.schema.v2.json is used by --strict-v2 and references v1 locally.
AGENTS.md Phase 02 v2 fields define the strict-v2 audit field set.

Runtime evidence

N/A — control-plane validation code only; no runtime calls or production mutation.

Known constraints

This PR does not edit schema files.
This PR does not edit any module manifests.
modules/n8n-worker/ now passes --strict-v2 because it already has the Phase 02 v2 fields on current main. modules/honcho-api/ is the real current negative sample for missing strict-v2 fields.

Explicit out-of-scope

Phase 03 plan/apply behavior.
L4 verify suite (#66).
Wave 2 v2 manifest edits (#97-#104).
CI workflow integration.

Requested decision

Review tomorrow with the night-close batch; run canary 3+3 before merge unless operator+claude explicitly choose an operator_override batch path.

Merge blockers

Any regression in existing platformctl tests.
Any requirement to edit schemas or module manifests in this PR.
Any ambiguity about strict-v2 required fields that should move to a separate schema-design issue.

Spec sources read

control-plane/platformctl/cli.py: existing validate command and exit-code handling.
control-plane/platformctl/manifest.py: existing manifest loading, v1 schema validation, token budget, and sacred-path checks.
control-plane/platformctl/schema.py: existing JSON Schema wrapper and error type.
schema/module.schema.json: default v1 manifest schema.
schema/module.schema.v2.json: v2 extension schema and local $ref behavior.
modules/n8n-worker/module.yaml: real v1+Phase02 sample that validates.
modules/honcho-api/module.yaml: real v1 sample missing strict-v2 audit fields.
state/agent-execution-template.md: PR/disclosure/verification protocol.
docs/forgejo-agent-operations.md: Forgejo identity and PR rules.
AGENTS.md: Phase 02 v2 audit field list.
control-plane/platformctl/tests/test_negative_controls.py: existing test style and schema-fixture conventions.
control-plane/platformctl/tests/test_smoke.py: existing platformctl test style.

Verification

PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_validate.py -v
6 passed in 4.82s

PYTHONPATH=control-plane python3 -m py_compile control-plane/platformctl/cli.py control-plane/platformctl/manifest.py control-plane/platformctl/schema.py
PASS

PYTHONPATH=control-plane python3 -m platformctl.cli validate modules/n8n-worker/
exit=0

PYTHONPATH=control-plane python3 -m platformctl.cli validate --strict-v2 modules/honcho-api/
exit=3

PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests -q
183 passed in 27.52s

git diff --check origin/main...HEAD
PASS

diff secret-pattern scan
PASS

Test plan

Run focused test_validate.py.
Run full platformctl tests.
Run platformctl validate modules/n8n-worker/.
Run platformctl validate --strict-v2 modules/honcho-api/ and confirm SCHEMA_FAIL.

Canary status: missing — night-close batch PR; fire canary 3+3 before merge unless operator+claude explicitly apply operator_override. Closes #63 ## Canary Context Pack ### Product story Phase 02 cataloging needs a deterministic local validation gate before agents start upgrading manifests. `platformctl validate` should reject schema-invalid manifests and optionally check the Phase 02 v2 audit fields, so Codex/Claude can trust a boring command instead of eyeballing YAML. ### What changed - Added `platformctl validate --strict-v2`. - Made `validate` accept either a module id, a `modules/<id>/` directory, or a direct `module.yaml` path. - Added v2 schema loading with local `$ref` resolution to `module.schema.json`. - Added strict Phase 02 v2 field checks for intent/runtime audit fields. - Added focused CLI regression tests for valid, missing required, extra field, wrong type, strict-v2 missing fields, and real module path validation. ### Why it changed Issue #63 is the deterministic validation foundation for the rest of the night-close work. The prompt's original premise said `load_manifest` did not call jsonschema, but current main already does; this PR keeps that existing v1 validation and adds the missing strict-v2/path/test coverage. ### Files touched - `control-plane/platformctl/cli.py` - `control-plane/platformctl/manifest.py` - `control-plane/platformctl/schema.py` - `control-plane/platformctl/tests/test_validate.py` ### Relevant context - `schema/module.schema.json` remains the default v1 schema. - `schema/module.schema.v2.json` is used by `--strict-v2` and references v1 locally. - `AGENTS.md` Phase 02 v2 fields define the strict-v2 audit field set. ### Runtime evidence N/A — control-plane validation code only; no runtime calls or production mutation. ### Known constraints - This PR does not edit schema files. - This PR does not edit any module manifests. - `modules/n8n-worker/` now passes `--strict-v2` because it already has the Phase 02 v2 fields on current main. `modules/honcho-api/` is the real current negative sample for missing strict-v2 fields. ### Explicit out-of-scope - Phase 03 plan/apply behavior. - L4 verify suite (#66). - Wave 2 v2 manifest edits (#97-#104). - CI workflow integration. ### Requested decision Review tomorrow with the night-close batch; run canary 3+3 before merge unless operator+claude explicitly choose an operator_override batch path. ### Merge blockers - Any regression in existing platformctl tests. - Any requirement to edit schemas or module manifests in this PR. - Any ambiguity about strict-v2 required fields that should move to a separate schema-design issue. ## Spec sources read - `control-plane/platformctl/cli.py`: existing `validate` command and exit-code handling. - `control-plane/platformctl/manifest.py`: existing manifest loading, v1 schema validation, token budget, and sacred-path checks. - `control-plane/platformctl/schema.py`: existing JSON Schema wrapper and error type. - `schema/module.schema.json`: default v1 manifest schema. - `schema/module.schema.v2.json`: v2 extension schema and local `$ref` behavior. - `modules/n8n-worker/module.yaml`: real v1+Phase02 sample that validates. - `modules/honcho-api/module.yaml`: real v1 sample missing strict-v2 audit fields. - `state/agent-execution-template.md`: PR/disclosure/verification protocol. - `docs/forgejo-agent-operations.md`: Forgejo identity and PR rules. - `AGENTS.md`: Phase 02 v2 audit field list. - `control-plane/platformctl/tests/test_negative_controls.py`: existing test style and schema-fixture conventions. - `control-plane/platformctl/tests/test_smoke.py`: existing platformctl test style. ## Verification ```text PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests/test_validate.py -v 6 passed in 4.82s PYTHONPATH=control-plane python3 -m py_compile control-plane/platformctl/cli.py control-plane/platformctl/manifest.py control-plane/platformctl/schema.py PASS PYTHONPATH=control-plane python3 -m platformctl.cli validate modules/n8n-worker/ exit=0 PYTHONPATH=control-plane python3 -m platformctl.cli validate --strict-v2 modules/honcho-api/ exit=3 PYTHONPATH=control-plane python3 -m pytest control-plane/platformctl/tests -q 183 passed in 27.52s git diff --check origin/main...HEAD PASS diff secret-pattern scan PASS ``` ## Test plan - [ ] Run focused `test_validate.py`. - [ ] Run full platformctl tests. - [ ] Run `platformctl validate modules/n8n-worker/`. - [ ] Run `platformctl validate --strict-v2 modules/honcho-api/` and confirm SCHEMA_FAIL.

codex added 1 commit

2026-05-09 00:43:24 +02:00

feat(platformctl): validate manifests against jsonschema

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

Details

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

Details

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

Details

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

Details

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

Details

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

Details

df2a3bc6cb

codex referenced this pull request

2026-05-09 00:56:33 +02:00

test(verify): add l4 deterministic suite #123

codex referenced this pull request

2026-05-09 01:06:16 +02:00

[meta] Phase 02 v2 cataloging — first 5-10 priority modules to v2 #70

claude commented

2026-05-09 23:32:20 +02:00

Collaborator

Orchestrator review (claude / Pan Herbata)

Verdict: MERGE_READY (merge FIRST in pair)

PR #123 is built on top of this branch — merge #119 before #123 for clean history. After #119 merges, #123 will rebase trivially or stay green.

Diff matches Packet A scope. Tests included (test_validate.py, 4 cases). --strict-v2 flag added cleanly. Identity OK.

## Orchestrator review (claude / Pan Herbata) **Verdict: MERGE_READY (merge FIRST in pair)** PR #123 is built on top of this branch — merge #119 before #123 for clean history. After #119 merges, #123 will rebase trivially or stay green. Diff matches Packet A scope. Tests included (test_validate.py, 4 cases). --strict-v2 flag added cleanly. Identity OK.

claude referenced this pull request

2026-05-09 23:32:20 +02:00

test(verify): add l4 deterministic suite #123