arch-enforce · diff
git:20260909.66f3572 to git:20260914.24a8dbb
36 added, 56 removed. Audit A to A.
---
name: arch-enforce
description: >-
- CI enforcement gate. Reads arch-validate JSON output and emits a structured
- enforcement decision. Use in CI pipeline only, not for human review.
+ CI enforcement gate. Evaluates a validation/v1 result against the gate
+ policy with the deterministic `archharness enforce` command — never by
+ hand-computed scores. Use in CI pipeline only, not for human review.
Inputs: validate_result.json and arch-gate-policy.yaml. Outputs:
- enforce_result.json with exit_code for pipeline consumption.
+ enforce_result.json (enforcement/v1) with a process exit code.
---
> **Locating shared resources.** References in this file to `standards/`,
- > `tools/`, `config.yaml`, and `templates/` are relative to the ArchHarness
+ > `schemas/`, `tools/`, and `config.yaml` are relative to the ArchHarness
> resource root. Determine the root, in order: (1) the `ARCHHARNESS_HOME`
> environment variable, (2) the output of `python -m archharness root` (the
> pip-installed package bundles these resources under its `data` directory),
> (3) the current working directory when it already contains `config.yaml` and
> `tools/` (the repository checkout). Prefix shared paths with that root
> whenever the working directory is not the resource root.
You are a compliance enforcement officer, not a reviewer. You do not
- evaluate diagrams. You apply policy to a validation result and emit
- a binary decision with audit trail.
+ evaluate diagrams and you do not compute scores by hand. You run the
+ deterministic gate and report its decision with audit trail.
## Step 0 — YAML pre-flight validation (fail-closed)
- Before reading any files, validate that all architecture standards YAML
- files are syntactically correct. This is a non-destructive syntax check —
- no files are modified.
+ Before anything else, confirm the standards and policy files parse:
- Run:
- ```
- python tools/yaml_validate.py standards/*.yaml config.yaml
+ ```bash
+ archharness validate-yaml config.yaml standards/*.yaml schemas/*.json
```
- - **Exit code 0** → all YAML is valid; proceed to Step 1.
- - **Exit code 1** → YAML syntax error detected. The diagnostic output
- shows the file path, line number, column, and specific error message.
- The pipeline MUST block here (fail-closed). Do NOT proceed to
- enforcement — if the policy file is corrupt, enforcement is unreliable.
-
- This pre-flight catches corrupted standards files, accidental binary
- blobs, truncated downloads, and merge-conflict markers before they
- cause silent enforcement failures.
-
- ## Step 1 — Load policy
-
- Read `standards/arch-gate-policy.yaml` — load thresholds, override
- conditions. (Already confirmed syntactically valid by Step 0.)
+ - **Exit code 0** → proceed to Step 1.
+ - **Non-zero** → the pipeline MUST block here. If the policy file is
+ corrupt, enforcement is unreliable. Do NOT proceed.
- ## Step 2 — Load validation result
+ ## Step 1 — Run the deterministic gate
- Read `validate_result.json` — load score, gate_decision, issues.
+ ```bash
+ archharness enforce --validation validate_result.json \
+ --policy standards/arch-gate-policy.yaml \
+ --output enforce_result.json
+ ```
- ## Step 3 — Apply policy
+ Omit `--policy` to use the bundled default policy. The command validates
+ the input against `schemas/validation-v1.schema.json`, applies the
+ `enforcement_bounds` (block/warn thresholds, must_fix rule), binds the
+ validation SHA and policy digest, and writes `enforce_result.json`
+ (`schemas/enforcement-v1.schema.json`).
- - score < policy.block_threshold → BLOCK
- - must_fix count > 0 AND policy.must_fix_zero_required → BLOCK
- - otherwise → PASS (or WARN if score < policy.warn_threshold)
+ ## Step 2 — Interpret the exit code (process-level, not JSON)
- ## Step 4 — Output enforce_result.json
+ - **Exit 0, `decision: PASS`** → total_score >= warn_threshold and must_fix == 0. Continue.
+ - **Exit 0, `decision: WARN`** → total_score >= block_threshold but below warn, must_fix == 0. Continue with review.
+ - **Exit 1, `decision: BLOCK`** → score below block_threshold OR must_fix > 0. Halt the pipeline: fix findings and re-validate.
+ - **Exit 2** → invalid input, schema, or policy. Fix the files, not the score.
- ```json
- {
- "decision": "PASS | BLOCK | WARN",
- "exit_code": 0 | 1,
- "pre_flight": {
- "yaml_validation_passed": true,
- "files_checked": ["standards/arch-gate-policy.yaml", ...],
- "validator_version": "tools/yaml_validate.py v1.0"
- },
- "policy_version": "...",
- "applied_rules": [...],
- "override_available": true | false,
- "override_requires": "...",
- "audit_entry": {
- "timestamp": "...",
- "diagram_hash": "...",
- "score": 0.0,
- "decision": "..."
- }
- }
- ```
+ Never invent a decision by reading the validation JSON yourself. If the
+ command and your own reading disagree, the command wins — report the
+ discrepancy as a tooling issue.
## CI pipeline integration example (GitHub Actions)
```yaml
- name: YAML Syntax Pre-flight
- run: python tools/yaml_validate.py standards/*.yaml config.yaml
- # exits 1 if any YAML is invalid → blocks the pipeline
+ run: archharness validate-yaml config.yaml standards/*.yaml
+ - name: Enforce gate
+ run: archharness enforce --validation validate_result.json --output enforce_result.json
+ # exit 1 on BLOCK → fails the job; exit 2 on corrupt input
```