0.2.0

Author: zachbutton

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
 	"name": "pyrs",
 	"description": "Your context engineering doesn't survive the session. Pyrs gives AI agents persistent architectural contracts that do.",
-	"version": "0.1.9",
+	"version": "0.2.0",
 	"author": {
 		"name": "Zach Button"
 	}

README.md

@@ -6,16 +6,16 @@ Defines the pyramid-first discipline: all changes to code must originate in pyra
 
 ## Concepts
 
-- **Pyramid-first.** The path is always: describe the change conceptually (new or update), verify alignment (audit), then implement (implement or tighten). Code is never modified outside this flow.
-- **Bootstrap exception.** When adopting pyrs on existing code or capturing manually-written code, bootstrap reverses the flow — it reads code and produces pyramids. Once bootstrap completes, the pyramid-first rule applies to all future changes.
+- **Pyramid-first.** The path is always: describe the change conceptually (spec), verify alignment (sane), then apply the code (apply). Code is never modified outside this flow.
+- **Ingest exception.** When capturing pyramids from existing code, ingest reverses the flow — it reads code and produces pyramids. Use it when adopting pyrs, when capturing manually-written code, or when re-ingesting code that has evolved.
 - **Strict scoping.** Implementation is bounded by the target pyramid. An agent implementing a pyramid builds only what that pyramid describes. Dependencies that don't exist yet get placeholders, not implementations.
 - **Provenance tracking.** Code and tests generated from pyramids carry provenance comments (`// PYRS: identifier`) so the connection between concept and code is traceable. Unbuilt dependencies get `// PYRS_TODO` placeholders with runtime logging.
 - **Opt-out for code markers.** A pyramid (or any ancestor) can include a constraint prohibiting code markers. This opt-out is inherited by all descendants and causes provenance comments and placeholders to be omitted entirely.
-- **The audit loop.** The feedback loop between pyramids and code: define or revise a concept, audit for hierarchy fit, implement or tighten the code, review for drift. This loop runs continuously across sessions.
+- **The audit loop.** The feedback loop between pyramids and code: define or revise a concept (spec), check for hierarchy fit (sane), apply the code (apply), check for drift (diff). This loop runs continuously across sessions.
 
 ## Contracts
 
-- All code changes flow through `implement` or `tighten` — these are the only routes from pyramid to code.
+- All code changes flow through `apply` — this is the only route from pyramid to code.
 - Implementation scope is strictly bounded by the target pyramid. No parent scope, no child scope, no undocumented extras.
 - Unbuilt dependencies produce `PYRS_TODO` placeholders with meaningful runtime logging, unless the pyramid opts out of code markers.
 - Code generated from a pyramid carries `PYRS: identifier` provenance comments, unless the pyramid opts out of code markers.
@@ -24,12 +24,12 @@ Defines the pyramid-first discipline: all changes to code must originate in pyra
 
 ## Relationships
 
-- Parent: [Pyrs](./index.md)
-- See Also: [Pyramid Model](./pyramid-model/index.md) — the change flow operates on the structures defined by the model
-- See Also: [Commands](./commands/index.md) — commands are the mechanism through which the change flow is executed
+- Parent: [Pyrs](../index.md)
+- See Also: [Pyramid Model](../pyramid-model/index.md) — the change flow operates on the structures defined by the model
+- See Also: [Commands](../commands/index.md) — commands are the mechanism through which the change flow is executed
 
 ## Constraints
 
-- The change flow must not allow direct code modification outside of `implement` and `tighten`. Bootstrap does not modify code — it only reads code and produces pyramids.
+- The change flow must not allow direct code modification outside of `apply`. Ingest does not modify code — it only reads code and produces pyramids.
 - Placeholders must not silently degrade — they must produce visible runtime output so missing pieces are noticed, not ignored.
 - The agent must never silently resolve ambiguity during any phase of the flow. Probing over assuming is non-negotiable.

pyramids/change-flow.md pyramids/change-flow/index.mdpyramids/change-flow.md renamed to pyramids/change-flow/index.md

@@ -0,0 +1,39 @@
+# Apply
+
+## Purpose
+
+Produce or update code from a pyramid using incremental test-driven development. Apply is the only route from concept to code — it handles both building from scratch and updating existing code to match a revised pyramid.
+
+## Concepts
+
+- **Syntax:** `::apply P` — P is an `@`-prefixed pyramid reference targeting the pyramid to implement or re-align code to. P may be identifier form (for example, `@auth.oauth` or `@root.auth.oauth`) or a direct pyramid `index.md` link (for example, `@./pyramids/auth/oauth/index.md`).
+- **Building from scratch.** When no code exists for the pyramid, the agent reads the pyramid, detects the project's test framework, and works through red/green cycles incrementally — one contract at a time, never in batch.
+- **Updating to match revisions.** When code already exists and the pyramid has been revised via ::spec, the agent compares the updated pyramid against existing code, identifies gaps, and tightens incrementally. Code the pyramid no longer describes is removed.
+- **Strict TDD.** Write a failing test for a contract, make it pass, move to the next contract. Non-negotiable and step-by-step.
+- **Strict scoping.** Only what the target pyramid describes. Not the parent's behavior, not the children's behavior, not helpful extras.
+- **PYRS_TODO placeholders.** Unbuilt dependencies get `// PYRS_TODO: ./pyramids/[path]` placeholders with runtime logging rather than guessed implementations.
+- **PYRS provenance comments.** Generated code carries comments linking back to the source pyramid, unless the pyramid opts out.
+- **Post-apply diff reconciliation.** If the target pyramid has a sibling `diff.md`, apply runs a same-target diff pass after code updates so the report is either refreshed with remaining gaps or deleted when fully reconciled.
+
+## Contracts
+
+- Apply is the only command that produces or modifies code.
+- Apply uses incremental TDD — one contract at a time, red then green, no batching.
+- Implementation scope is strictly bounded by the target pyramid.
+- Unbuilt dependencies produce PYRS_TODO placeholders with meaningful runtime logging, unless the pyramid opts out of code markers.
+- Generated code carries PYRS provenance comments, unless opted out.
+- When updating, code the pyramid no longer describes is removed.
+- After apply mutates code for target P, if sibling `diff.md` exists for P before or after the mutation, apply must run a same-target diff pass before final output.
+
+## Relationships
+
+- Parent: [Code Output](../index.md)
+- See Also: [Spec](../../pyramid-output/spec/index.md) — spec revises pyramids, apply updates code to match
+- See Also: [Mend](../../pyramid-output/mend/index.md) — mend patches pyramids, then routes to apply for the code fix
+
+## Constraints
+
+- Apply must not modify pyramids. It consumes pyramids and produces code.
+- The agent must not skip TDD or batch multiple contracts.
+- Placeholders must not be replaced with guesses. Only a subsequent apply of the dependency's pyramid replaces a placeholder.
+- Post-apply diff refresh must be limited to the target scope. Apply must not trigger broad diff sweeps unless the user explicitly requested that scope.

pyramids/commands/code-output/apply/index.md

@@ -0,0 +1,36 @@
+# Code Output
+
+## Purpose
+
+Commands that produce or update code from pyramids. This is the only route from concept to code in the system, using incremental test-driven development to ensure code matches contracts.
+
+## Concepts
+
+- **Apply** is the single command that produces and modifies code. It handles both building a pyramid's concept from scratch and updating existing code to conform to a revised pyramid.
+- **Test-driven development.** Apply follows strict TDD: write a failing test for a contract, make it pass, move to the next contract. This is non-negotiable and step-by-step — the agent does not batch multiple contracts into one implementation pass.
+- **Strict scoping.** The agent implements only what the target pyramid describes. Not the parent's behavior. Not the children's behavior. Not helpful extras. Scope discipline is what makes the pyramid system trustworthy.
+- **Placeholders for unbuilt dependencies.** When a child or See Also reference hasn't been implemented, the agent leaves a `// PYRS_TODO: ./pyramids/[path]` placeholder with runtime logging rather than guessing at the dependency's behavior.
+- **Post-apply diff refresh.** When the target pyramid already has a sibling `diff.md`, apply runs a same-target diff pass after code changes so the report is immediately updated or removed.
+
+## Contracts
+
+- Apply is the only command that produces or modifies code.
+- Apply uses incremental TDD — one contract at a time, red then green, no batching.
+- Implementation scope is strictly bounded by the target pyramid. No parent scope, no child scope, no undocumented behavior.
+- Unbuilt dependencies produce PYRS_TODO placeholders with meaningful runtime logging, unless the pyramid opts out of code markers.
+- Generated code carries PYRS provenance comments linking back to the source pyramid, unless opted out.
+- After apply mutates code for target P, if sibling `diff.md` exists for P before or after the mutation, apply runs a same-target diff pass before final output.
+
+## Relationships
+
+- Parent: [Commands](../index.md)
+- Children:
+  - [Apply](./apply/index.md) — produce or update code from pyramids
+- See Also: [Change Flow](../../change-flow/index.md) — apply is the code-producing step of the change flow
+
+## Constraints
+
+- Code output commands must not modify pyramids. They consume pyramids and produce code.
+- The agent must not skip TDD or batch multiple contracts. The incremental discipline is what ensures each contract is independently verified.
+- Placeholders must not be replaced with guesses. Only a subsequent apply of the dependency's pyramid replaces a placeholder.
+- Post-apply diff refresh must stay target-scoped. Code output commands must not run broad multi-target diff sweeps unless the user explicitly requested that scope.