| name | maintain-artifacts |
| description | Use when a ddd-expert phase needs to inspect DDD artifacts or apply an already accepted artifact transaction; validates declared phase-operation compatibility, layout, templates, and model-design revisions without making domain or tactical decisions. |
Maintain Artifacts
Execute the DDD artifact protocol inside the currently active phase. This is a shared in-process workflow, not a separate agent or trusted caller boundary. It owns no business fact or Tactical Design decision and never asks the user to supply one.
Operation input
Every operation states:
authority: explore, shape, codify, or guard;operation: inspect, apply-model, or apply-design;- the affected context names and stable lower-kebab-case slugs when known.
An inspect operation needs no expected revision. When its context scope is omitted, inspect the complete artifact root.
An apply operation additionally states:
- the expected pre-state of every path in its write set: absent, or an observed content fingerprint plus any Model revision;
- exact accepted terminal content for every changed semantic section, explicit removals, and evidence that the owning phase's write gate passed;
- for
apply-design, the exact current Model revision for every affected context.
Reject absolute slugs, path separators, . or .. segments, and any slug that can escape its context directory.
| Operation | Allowed authority | Filesystem effect |
|---|
inspect | Any phase | Read-only |
apply-model | Explore | Root README, Context Map, and affected Models only |
apply-design | Shape | Affected Designs and newly empty context directories only |
Codify and Guard can never run an apply operation. Treat an invalid operation input as an internal protocol error: write nothing, correct it in the active phase, and retry the operation.
Workflow
- Load the contract: read the Artifact Layout and only the templates needed by the operation.
- Inspect current state: verify the artifact root, accepted context directories, safe slugs, template residue, frontmatter, links, and Model-to-Design revision links. Read every file in an intended write set before changing any.
- Compare before apply: require every expected path pre-state to match. For
apply-design, also require the delegated Model revision to equal the current Model revision. A stale or missing Design is a valid pre-state for apply-design; the operation exists to create or repair it. On mismatch, write nothing and report revision_conflict with expected and observed state.
- Prepare one transaction: assemble complete files from the templates, exact accepted terminal content, explicit removals, and unaffected current content. Do not rename terms, infer replacements, decide that a statement is superseded, omit a section on semantic grounds, or turn a summary delta into new domain or tactical prose. Return an invalid operation input to the active phase when exact content is missing.
- Apply the authorized write set:
apply-model: bootstrap the root README and Context Map when needed; update navigation, relationships, and affected Models; start a new Model at revision 1 and increment an existing revision once only when accepted model facts change; never touch a Design.apply-design: create, update, move, or delete affected Designs as required by the accepted context topology and set each retained Design's based_on_model_revision to the exact current Model revision; a proven no-semantic-change revalidation may update only this field; never touch Explore-owned artifacts.
- Verify the result: re-read the full write set, confirm layout, links, no placeholders/comments, accepted language and distinctions, expected terminal content, authorized paths only, and revision invariants. Report any partial filesystem failure as
blocked with exact observed state; do not conceal it as success.
- Resume the phase: expose the operation status, observed and written revisions, changed paths, validation evidence, and any required route to the active phase. Do not replace that phase's completion response.
Context topology changes
Explore may accept a context rename, split, merge, or removal. apply-model updates only Explore-owned files and leaves any old Design untouched. It returns changed with a pending_design_reconciliation observation. Shape then accepts the tactical consequence and apply-design creates, moves, rewrites, or deletes affected Designs. Remove an obsolete context directory only after it is empty.
This two-step state is intentional. Until Shape completes it, Codify treats affected Designs as unavailable authority and Guard reports the evidence gap while continuing independent review.
Inspect result
Return structural observations only; semantic sufficiency belongs to the active phase:
ready: the applicable files and revision links are structurally valid;uninitialized: the artifact root does not yet exist;missing_model: an accepted context has no readable Model;missing_design: a Model has no Design; this is valid between Explore and the first successful Shape;stale_design: a Design references a different Model revision;pending_design_reconciliation: context topology and retained Designs are temporarily out of alignment;invalid_layout: a root file, path, slug, link, frontmatter field, or template constraint is invalid.
Inspection never decides that business facts are contradictory or that a Tactical Design covers the Model. It reports paths, revisions, and concrete structural evidence so the active phase can decide whether to clarify, route, implement, or review.
Apply result
Return one of:
changed: list every changed path, resulting revision, and structural observation such as pending_design_reconciliation;no_change: cite the evidence that made writing unnecessary;revision_conflict: report expected and observed pre-state without writing;blocked: identify the external failure and exact resulting filesystem state.
Never write implementation progress, review findings, task history, or phase status into DDD artifacts.
References
