Platform Definition v1
Platform Definition v1
This document defines the minimum standard for this repository to qualify as a governed AI engineering platform template.
Scope
This platform standard covers:
- ExecPlan-driven execution
- agent/human governance
- deterministic validation
- canonical graph-backed work state
- machine-readable rule authority
- signed finalization and audit evidence
Core Invariants
These invariants are mandatory:
- All meaningful work originates from an ExecPlan in
.agent/execplans/. - Agents draft and implement under governed branches; humans finalize with SSH-signed authority events.
- Validation outputs are deterministic and machine-readable.
- Enforced rules live in
spec/and are consumed by code from canonical machine-readable artifacts. - The remaining-work graph is the canonical work-state authority.
- Projection surfaces such as
TODO.md, queue docs, and provider boards are non-authoritative. - Validation tests declared in ExecPlans are executable by one governed runner.
- Finalized plans and merge-backed completion state must be reconcilable from repository evidence.
Execution Surface
- human/operator entrypoints:
bin/* - canonical implementation logic:
src/platform_tools/* - canonical rule inventory:
spec/rule-registry.yaml - canonical work-state authority:
artifacts/planner/research/remaining-work-graph.json
Data Contracts
- ExecPlan: markdown plus YAML frontmatter defined by
.agent/PLANS.md - Rule registry: canonical machine-readable inventory of enforced, derived, human-gated, backlog, and deprecated rules
- Rule graph: relationship projection over the rule registry
- Remaining-work graph: canonical slice readiness, gating, and reconciliation state
- Queue doc: human-readable mirror of remaining-work graph metadata
- TODO: optional projection only
- Health report: deterministic machine-readable repo summary
- Test report: deterministic per-test pass/fail with expected and actual exits
Required Commands
Minimum required command surface:
bin/execplan-validatebin/run-local-cibin/execplan-testbin/repo-health-checkbin/rule-graph-checkbin/remaining-work-graph-check
bin/sync-todos remains supported as a projection command, not as a canonical workflow authority.
Acceptance Checklist
A repository qualifies as this template only when all checks pass:
bin/execplan-validate .agent/execplans/*.mdexits0on valid inputs.- validator output is deterministic and machine-readable.
- branch roles and protected-branch restrictions are enforced.
spec/rule-registry.yamlexists and active enforced rules are registered there.bin/rule-graph-checkvalidates the graph projection against the rule registry.bin/remaining-work-graph-checkvalidates canonical work-state and queue-projection reconciliation.bin/execplan-testexecutesvalidation.testsblocks from ExecPlans.bin/run-local-ciruns the governed check chain in deterministic order.- repo health does not depend on deprecated projection surfaces being authoritative.
- finalized plans and completion state can be derived from signed merge-backed evidence.
Current Direction
Current platform work is focused on consolidation rather than bootstrap gaps:
- unify rule authority under
spec/rule-registry.yaml - keep the rule graph as a validated projection rather than a separate rule source
- treat TODO as projection-only
- formalize draft self-review, additive PR structure, and implementation handoff
- keep graph and queue state reconciled as governed workflow evidence
Platform Completion
Platform-layer work is complete only when:
- rule, workflow, and projection authority are machine-readable and internally consistent
- graph-backed execution and merge reconciliation are canonical
- human authority boundaries remain explicit and machine-detectable
- documentation explains current runtime truth rather than preserving obsolete historical gap maps