using-control-json

name	using-control-json
description	Use when executing an existing v1 compiled run.control.json/runtime.control.json chain.

Using Control JSON

Legacy v1 compatibility only. New runs use $using-commitment-control-json.

Overview

This is not bounded_runtime. Bounded runtime goals use .agents/skills/using-bounded-control-json.

It supports official generation-aware runs with requirements.control.json, run.control.json, and the current gen-N/runtime.control.json. Load all generation control_refs; the plan remains policy authority and runtime is its validated projection.

Read references/runtime-control-json-protocol.md before executing, reporting status, or preparing completion evidence. Gate result semantics follow ../references/transition-gate-protocol.md.

Operating Contract

1. Validate file presence, parsing, hashes, steps, generation, verifier, and write authority. Stop on inconsistent JSON.
2. All approved control JSON is read-only during runtime.
3. Write control output only to progress.jsonl, runtime-status.json, and final-report.json; evidence stays under authorized evidence paths.
4. Append one JSON object per line to progress.jsonl. Runtime must use append_progress_event.py. Direct writes to progress.jsonl are invalid. Record observations; do not mutate approved JSON.
5. final-report.json does not grant verifier permission to itself. Run the structural verifier before goal_achieved: true; Counterexample Gate supplies semantic review.
6. Never satisfy source requirements with weaker evidence. Propose an amendment when strategy cannot complete a blocking requirement.
7. Facts that should have been known before design or planning are information-sufficiency issues; observe/amend, or stop if anchors or authority change.
8. /goal is a pointer, not control fact. Resolve current_generation at execution; old concrete runtime paths are stale after a switch.
9. For required_single_manifest, bind completion/review/verification events and final report to one content-addressed evidence subject. Manifest run:/repo: references must resolve to actual bytes, every required work-package component must be represented, and subject_id must equal the canonical manifest-content hash. Reject mixed, unresolved, or stale subjects.
10. Expanded step events execute the projected plan policy. Respect ordered work packages; bind action_alignment_ref, produced artifact hashes, and required evidence paths. Source-file lists are not an authority gate: implementation may discover any repository files needed to produce the approved state change, subject to semantic non-goals and live/destructive gates. Tests are not mandatory progress fields and do not impose test-first ordering, a test quota, a package frontier, or a completion condition. A later started/failed/blocked event revokes the earlier pass for that step and invalidates downstream package credit until rerun.

Gate Roles

Structural gates are schema checks, control_chain_guard, validate_control_chain, and verify_runtime_progress. They prove shape, hashes, coverage, and progress, not quality approval.

Quality gate means counterexample-gate: an independent reviewer tries to disprove the target decomposition, runtime strategy, blocked claim, or completion claim. It must execute the requirements-approved contract, every per-outcome gate, and for schema 1.3.0+ every required result path. Runtime must not invent or weaken these gates.

Runtime may add or run tests when useful, but developer-authored tests do not replace Counterexample Gate. A discovered counterexample may be retained as a regression test when it protects a real failure, a named critical invariant, or materially lowers repeated observation cost; retention is optional.

Reviewed Replanning

When strategy cannot produce a blocking outcome, do not substitute readiness, compatibility, or weaker evidence. Append a control.amendment.proposed event with the current runtime_generation, reason, triggering observation, affected strategy stages, affected_source_requirements, anchor-change flags, and a patch_ref to the next candidate strategy.

Anchor-preserving tactical amendments are reviewed into a new generation by the orchestrator only when run.control.json.strategy_policy is reviewed_replanning. Under frozen_strategy, an amendment proposal reports that the approved strategy does not fit and requires a human decision before continuing. The orchestrator must not synthesize its own approved review; it can switch generations only after the complete generation plan and patch have an approved independent amendment review, then it switches automatically. Proposals that change requirements.control.json, semantic_base, required outcomes, what counts as done, work coverage, commitment authority, or forbidden actions are not amendments and return to human commitment.

Completion Posture

If validation, progress append, status write, or verifier execution cannot be completed, report goal_achieved: false with the missing JSON, missing evidence, or failing verifier condition. Component completion is only progress evidence until the verifier permits the final claim.