Source repository

• 1:
• 1.1:
• 1.2:

bazel_agent bazel run //tools/openspec -- list --specs

1 -

Repository evolution

This OpenSpec workspace describes evolution of the alwaldend/src repository itself: its shared structure, build system and development workflows. specs/repository/spec.md records that contract; changes/ records proposed and completed changes to it.

Each component owns a separate OpenSpec workspace beside its source:

• projects/<project>/openspec/ holds that project’s specs and changes.
• infra/<project>/openspec/ holds that infrastructure project’s specs and changes.
• infra/src/openspec/ holds the repository’s own specs and changes.

Select the narrowest owner of the requested behavior. A project change belongs in that project’s workspace, including when it has a standalone Bazel module. Changes to shared repository structure belong here. Work spanning owners keeps each affected contract with its owner and links related changes. Component READMEs and build declarations retain their existing authority.

Run OpenSpec

The pinned CLI runs from the Git worktree root. It selects infra/src by default; use OPENSPEC_PROJECT for a component:

bazel_agent bazel run //tools/openspec -- list --specs
OPENSPEC_PROJECT=projects/agents bazel_agent bazel run //tools/openspec -- list
OPENSPEC_PROJECT=infra/vault bazel_agent bazel run //tools/openspec -- list --specs

Use new change, status, instructions, validate, and archive with the same owner selection. The packaged OpenSpec skill documents continuation and acceptance. No global install or assistant configuration rewrite is needed. The CLI isolates configuration and disables telemetry.

Repository validation checks every component workspace as well as this one:

bazel_agent bazel test //infra/src/openspec/validation:validate_test //infra/src/openspec/validation:archive_test

Validation checks artifact structure and, for archives, task completion. Requirement acceptance still needs evidence from the owning implementation. Infrastructure specs describe checked-in definitions, not observed deployment.

Maintain work

In the selected workspace, changes/<name>/proposal.md states outcome and scope, design.md records decisions and continuation, tasks.md records remaining actions, and specs/<capability>/spec.md contains requirement deltas. Read an existing matching change before creating another. Keep temporary notes, raw logs and validation receipts under ignored out/<task>/.

On interruption, preserve the candidate, evidence, execution state and next action. Keep blocked or unfinished work explicit. OpenSpec files and Git do not supply the deprecated goal store’s transaction locks or evidence verdicts; one coordinator owns a change and reconciles concurrent edits.

After acceptance, validate and archive the change in its owning workspace, then inspect the resulting baseline specs. Specifications and generated instructions neither expand user authority nor introduce an approval gate.

Goal migration

migration.md maps the nine maintained goals to their current owner-local changes. It records a repository workflow migration; the actual history and work state live with Agents, MCP Cordis and Renders. Original history, checksums and acceptance states are preserved. Historical deltas were archived without applying them to current specs. Reimu Fumo remains open and blocked.

The goal skill is disabled and the goal CLI is deprecated compatibility tooling. New maintained work uses the owning OpenSpec workspace.

1.1 -

Goal migration to OpenSpec

On 2026-09-08, all nine tracked maintained project goal records at source commit 550d7e79b1f5fdbc2b6017b75178471d6914082f were migrated into native OpenSpec changes. Each change now lives in its owning project’s openspec/ workspace. Eight completed records are imported as archived history. The Reimu Fumo change remains open with blocked execution and no accepted candidate.

The machine-readable inventory maps all 222 tracked source files (834,320 bytes) to byte-identical provenance snapshots. Test fixtures and ignored task scratch are outside the maintained-record inventory.

Record mapping

Mapping and acceptance

• Objective and scope map to proposal.md; accepted plans, decisions, rejected approaches, and constraints map to design.md.
• The latest acceptance criteria map to tasks.md and meaningful capability delta requirements. Each YAML criterion keeps its stable ID and revision in migration.json; original revisions, attempts, review verdicts, and evidence remain in provenance.
• Completed task checkboxes reproduce explicit historical acceptance reviews. They do not revalidate today’s source. The Markdown Cordis record declares Complete and no failing criteria; its absent execution field stays unavailable rather than being guessed.
• Reimu acceptance and continuation tasks remain unchecked. A supported authorized unblock can change execution while the outcome remains open until every required criterion passes.
• Completed records were placed directly in their owner’s openspec/changes/archive/2026-09-08-<id>/. No archive or spec-sync command applied their historical deltas. Current baseline specifications were derived separately from maintained owner source. Do not reapply historical deltas.
• Historical Phase 5 acceptance includes an explicit fixture-gap inventory. Its accepted review and still-pending prose are both retained; migration does not claim the missing infrastructure fixtures were implemented.

Provenance and navigation

Each change has migration.json, a checksum inventory at provenance/manifest.json, original record bytes at provenance/source/, and a provenance navigation guide. The old agent goal landing and BUILD file are also retained under the repository-agent-system archive. The historical BUILD snapshot uses .original to preserve bytes without creating a new Bazel package.

Among preserved Markdown links, 47 links depend on the former location; companion navigation tables resolve them where the referenced artifact exists. 46 historical targets are unavailable in the checkout. Original bytes and historical Git identities are not rewritten to disguise unavailable scratch or superseded paths.

The former maintained goal directories are removed; native OpenSpec work is the continuation surface. Provenance files are excluded from generic formatting so their source digests remain stable. The migration inventory is import evidence, not an alternate work scheduler or mutable status catalog.

1.2 -

Repository Evolution Specification

Purpose

Define how the alwaldend/src monorepo evolves its shared structure, build system and development workflows. Component behavior is specified in each owner’s local OpenSpec workspace. This baseline was inspected at source revision 550d7e79b1f5fdbc2b6017b75178471d6914082f on 2026-09-08 and incorporates the OpenSpec migration delivered with this specification. Changes in infra/src record repository evolution; they do not collect unrelated component work or claim runtime health or deployed infrastructure.

Sources: repository map, agent policy, root build, project boundary, infrastructure boundary, tool boundary, and OpenSpec workflow.

Requirements

Requirement: Component ownership and source boundaries

The repository MUST keep component purpose and publication boundaries in the nearest owner README, executable and dependency structure in BUILD and MODULE files, and agent policy in the applicable AGENTS.md chain. Specifications SHALL describe component requirements with links to these owners.

Scenario: Select an implementation owner

• WHEN a change affects a project, tool or infrastructure component
• THEN its owning documents and Bazel workspace determine the affected paths and supported consumers
• AND a repository-wide catalog or specification does not grant broader publication or execution authority

Requirement: Reproducible Bazel development

Repository agent build and test operations MUST use bazel_agent bazel in the owning workspace with pinned dependencies and the repository’s shared agent configuration. Generated dependency and catalog files MUST be updated through their owning generator.

Scenario: Change a shared dependency

• WHEN an implementation adds an external build input
• THEN its owner records an immutable version and integrity information
• AND applicable generated locks and package checks validate the declared dependency through the pinned build workflow

Requirement: Isolated implementation and evidence

Repository modifications MUST use a dedicated feature branch and linked worktree. Task scratch MUST remain under ignored out/<task>/ in the applicable workspace. Acceptance SHALL identify the candidate and relevant checks and representative output before delivery.

Scenario: Finish a repository change

• WHEN an authorized implementation is ready for delivery
• THEN task-owned changes pass applicable formatting, quality and semantic checks and are committed and published through the repository procedure
• AND unrelated edits, scratch and protected data are excluded

Requirement: Declarative infrastructure authority

Persistent infrastructure configuration MUST be defined in checked-in owning infrastructure code. Infrastructure operations MUST require the user’s exact operation and scope authorization; an implementation validation request SHALL NOT authorize live deployment.

Scenario: Validate an infrastructure specification

• WHEN an agent adds or updates an infra component specification
• THEN it inspects source and runs applicable offline checks
• AND it does not infer deployed state or execute live apply or deployment from the existence of the specification

Requirement: OpenSpec coverage and work state

Each direct project in projects/ and infra/ SHALL keep its baseline specifications and maintained changes in its own openspec/ workspace. infra/src/openspec SHALL describe evolution of the repository itself, including shared structure, build system and development workflows. The repository root SHALL NOT collect component specifications or change records. Maintained work SHALL preserve outcome, decisions, tasks and requirement deltas. Existing task authority MUST survive workflow transitions.

Scenario: Change a component contract

• WHEN a change affects a project’s supported behavior
• THEN its specifications and change artifacts remain in that project’s openspec/ directory
• AND the pinned CLI and context routing select that owner workspace

Scenario: Evolve the repository itself

• WHEN a change affects the monorepo’s shared structure or development workflow
• THEN infra/src/openspec records its repository requirements and evolution
• AND component contracts remain with their respective owners

Scenario: Resume unfinished maintained work

• WHEN an agent resumes a named OpenSpec change
• THEN it reads that owner’s change artifacts, candidate, evidence and next action
• AND unfinished or blocked acceptance remains explicit until evidence supports completion

Scenario: Validate a standalone project

• WHEN a project has its own Bazel module
• THEN repository OpenSpec validation still checks its declared local workspace
• AND a successful repository check does not omit that project’s requirements

Requirement: Legacy goal migration and deprecation

The migration SHALL preserve all tracked maintained goal history and its recorded acceptance and execution states with source-to-change mappings and checksums. The goal skill MUST be disabled for discovery and the goal tool MUST identify itself as deprecated compatibility functionality.

Scenario: Inspect a migrated historical record

• WHEN a reader follows a legacy goal’s migration entry
• THEN its OpenSpec change exposes the original history and status
• AND historical completion does not establish acceptance for a different candidate or automatically apply old specification deltas