Emit a human-readable YAML repository plan with sealed provenance #203

New issue

Closed

opened 2026-08-05 18:57:29 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-05 18:57:29 +00:00

Member

What to build

Replace the generated JSON repository plan with a deterministic, human-readable YAML v2 contract at ~/.agent-compose/repository-plan.yaml.

The plan remains machine-owned, but an operator must be able to inspect it directly. It records the projects root, role selections, residency union, and the exact provenance of every policy input used to compile those selections.

The YAML contract includes:

format: agent-compose.repositories.v2
projects_root: /absolute/projects/root

inputs:
  - identity: example/operating-context
    revision: "<full-git-sha>"
    policy:
      path: .agents/roles.kdl
      sha256: "sha256:<content-digest>"

roles:
  example-role:
    - identity: example/context
      scope: global
      source: example/operating-context

residency:
  - identity: example/context
    path: /absolute/projects/root/example/context
    scope: role-union
    reason: selected globally by repository policy

Use a bounded safe-YAML subset. Do not admit aliases, custom tags, duplicate keys, or ambiguous scalar coercion. Keep a single steady-state format rather than writing JSON and YAML in parallel.

Acceptance criteria

Agent Compose writes ~/.agent-compose/repository-plan.yaml with format agent-compose.repositories.v2.
Output is deterministic, owner-qualified, sorted, and written atomically.
The document records each policy source identity, full source revision, policy path, and SHA-256 content digest.
Role selections and the residency union retain their existing provenance fields and strict path safety.
Schema validation rejects unknown fields, duplicate keys, unsafe YAML features, unsafe paths, unsorted identities, and incomplete provenance.
Fixtures prove that a globally selected repository appears in every role and in residency.
Agent Compose stops writing the JSON plan after the migration boundary.
Product documentation and docs/FEATURES.md describe the human-readable YAML contract and provenance guarantee.
Repository validation passes through declared Ward verbs.

Blocked by

None - can start immediately.

## What to build Replace the generated JSON repository plan with a deterministic, human-readable YAML v2 contract at `~/.agent-compose/repository-plan.yaml`. The plan remains machine-owned, but an operator must be able to inspect it directly. It records the projects root, role selections, residency union, and the exact provenance of every policy input used to compile those selections. The YAML contract includes: ```yaml format: agent-compose.repositories.v2 projects_root: /absolute/projects/root inputs: - identity: example/operating-context revision: "<full-git-sha>" policy: path: .agents/roles.kdl sha256: "sha256:<content-digest>" roles: example-role: - identity: example/context scope: global source: example/operating-context residency: - identity: example/context path: /absolute/projects/root/example/context scope: role-union reason: selected globally by repository policy ``` Use a bounded safe-YAML subset. Do not admit aliases, custom tags, duplicate keys, or ambiguous scalar coercion. Keep a single steady-state format rather than writing JSON and YAML in parallel. ## Acceptance criteria - [ ] Agent Compose writes `~/.agent-compose/repository-plan.yaml` with format `agent-compose.repositories.v2`. - [ ] Output is deterministic, owner-qualified, sorted, and written atomically. - [ ] The document records each policy source identity, full source revision, policy path, and SHA-256 content digest. - [ ] Role selections and the residency union retain their existing provenance fields and strict path safety. - [ ] Schema validation rejects unknown fields, duplicate keys, unsafe YAML features, unsafe paths, unsorted identities, and incomplete provenance. - [ ] Fixtures prove that a globally selected repository appears in every role and in residency. - [ ] Agent Compose stops writing the JSON plan after the migration boundary. - [ ] Product documentation and `docs/FEATURES.md` describe the human-readable YAML contract and provenance guarantee. - [ ] Repository validation passes through declared Ward verbs. ## Blocked by None - can start immediately.

coilyco-ops referenced this issue from coilyco-flight-deck/agentic-os

2026-08-05 18:57:41 +00:00

Fail closed when the repository plan is stale or incomplete #903

coilyco-ops added the

autonomy

headless

priority

labels

2026-08-05 18:58:03 +00:00

coilyco-ops referenced this issue from a commit

2026-08-05 21:18:34 +00:00

feat: emit YAML repository plan