Sdd Archive

<!-- MEMORY-CONTRACT v1 -->

Memory contract. This command persists across sessions through engram

(registered as an MCP server in this tool). Use this tool's own engram memory

tools to honor the rules below — do not assume any other persistence layer.

>

- Recall before acting: on a continuation keyword ("listo", "dale",

"ready", "where did we leave off"), first search engram for prior work on

this change before starting fresh; summarize what you found, then continue.

- Validate after saving: after any save, search engram back for the key or

a unique phrase — a "saved" tool response is NOT proof. Retry once; if it

still fails, tell the user the save failed. Never report "saved" on the tool

response alone.

- Summarize at close: before ending, write a session summary (goal, work

done, decisions, next steps, files). Recovery is never automatic.

- If engram is unreachable (not installed / not on PATH): emit a visible

warning that engram was not found and that this work will NOT persist. DO NOT

report memory as saved; DO NOT proceed silently as if it had persisted.

Purpose

Archiving is the final step of the SDD cycle. It validates completeness, saves a closure record, and updates the project memory layer. It is irreversible — confirm with the user before executing.

Process

Step 1 — Verify it is archivable

Completeness Check

Before reading the verify report, check for required SDD artifacts on disk. An artifact exists if its disk file docs/sdd/{change-name}/{type}.md is present (disk existence IS the completeness signal now). Only if a disk file is absent do you fall back to searching prior work for sdd/{change-name}/{type} (legacy change) — an artifact still counts as present if that search returns results.

CRITICAL artifacts (block with no proceed option): proposal, tasks

WARNING artifacts (present two-option prompt): design, specs

Check order:

1. Check CRITICAL artifacts first. If any are absent:

CRITICAL — Cannot archive "[change-name]"

The following artifacts are required for a valid SDD cycle but are missing:
  - proposal   (required — CRITICAL)
  - tasks      (required — CRITICAL)

Return and complete the missing phases before archiving.
No proceed option is available.

List only the artifacts that are actually absent. Halt immediately. Do NOT evaluate WARNING artifacts.

2. If CRITICAL passes, check WARNING artifacts. If any are absent:

WARNING — Incomplete cycle detected for "[change-name]"

The following artifacts are missing:
  - design     (recommended — WARNING)
  - specs      (recommended — WARNING)

Choose:
  1. Return and complete the missing phases (/sdd-spec, /sdd-design)
  2. Archive anyway — I acknowledge these phases were intentionally skipped

Reply 1 or 2:

List only the artifacts that are actually absent. Wait for the user to reply:

• Option 1 selected: halt. The user returns to complete the missing phases.
• Option 2 selected: record the skipped phases (for use in Step 4 closure)

and continue.

3. If all CRITICAL and WARNING artifacts are present: produce no output and continue immediately.

Note: exploration is explicitly excluded from this check. Its absence MUST NOT trigger any CRITICAL or WARNING output.

---

Read the verify report artifact if it exists:

• read docs/sdd/{change-name}/verify-report.md for full content.
• If the disk file is absent (legacy change): fall back to searching prior work

for sdd/{change-name}/verify-report and retrieve it.

If there are unresolved CRITICAL issues:

No archiving allowed.

The verification report has [N] critical issues:
- [issue 1]
- [issue 2]

Resolve the issues and run /sdd-verify again before archiving.

If there is no verification report, inform the user and ask whether to proceed anyway.

User-docs review checkbox (non-blocking):

After reading the verify-report (if it exists), surface the user-docs review item status:

User docs review checkbox: [CHECKED / UNCHECKED / ABSENT]

• CHECKED: verify-report contains [x] Review user docs — good
• UNCHECKED: verify-report contains [ ] Review user docs — remind the user to

check if this change affects user-facing docs

• ABSENT: the checkbox is not in the verify-report — no action needed (older

changes pre-date this requirement)

This check is non-blocking — the archive operation continues regardless of the checkbox state.

Step 2 — Confirm with the user

Do you confirm archiving the change "[change-name]"?

This will perform the following actions:
1. Save an archive closure report to the persistent memory layer
2. Update ai-context/ with decisions from this change
3. Delete `docs/sdd/<change>/` (guarded — only if archive-report is confirmed in the memory layer AND Sync Impact Report shows zero pending pieces; the archive-report is moved to `docs/sdd/_archived/<change>-archive-report.md` first)

[PASS WITH WARNINGS — warnings were left unresolved]
[or: Verification: PASS]

Continue? [y/n]

Step 3 — Sync Impact Report

Enumerate the living-artifact surface for this change. Living artifacts are files in: skills/, agents/, hooks/, docs/, and ai-context/features/. For each piece of logic introduced by the change being closed, determine whether a living artifact exists that carries that logic.

For each logic piece, classify as one of:

• ✅ updated — a living artifact exists at a named path AND was updated this session
• ✅ created — no living artifact existed; ARCHIVE created one in-repo this session (see creation rule below)
• ⚠ pending — no living artifact exists and ARCHIVE could not create one in this run

Active creation rule (priority-ordered): When a piece of logic has no living artifact (would be ⚠ pending), ARCHIVE MUST attempt to create the appropriate artifact in this repo using this decision rule:

1. Reusable agent behavior / repeatable process → skills/<name>/SKILL.md (one directory, one SKILL.md, valid YAML frontmatter with format:) 2. Orchestration / coordination instructions → agents/<name>.md 3. Automated enforcement on a harness event → hooks/<name>.js 4. Domain business rules of a bounded context → ai-context/features/<domain>.md 5. Conventions / guidelines / standalone decision → docs/<path>.md

Capable-tier delegation (MANDATORY): ARCHIVE runs on a lightweight model tier, which is too weak to author a living artifact from scratch. ARCHIVE MUST NOT author the artifact inline. Instead, ARCHIVE MUST DELEGATE the authoring to a fresh capable-tier worker. The creation sub-step MUST NOT run on the lightweight tier. Only this creation sub-step escalates — the enumerate / move / delete / memory-persist / guarded-deletion sub-steps remain on the lightweight tier. When the delegated worker returns the created artifact, update the report row to ✅ created with its path.

Record the type decision and its rationale in the report row. After creation, update the row to ✅ created with the new artifact path.

Emit the Sync Impact Report in this exact format:

## Sync Impact Report — <change-name>

| Logic piece | Living artifact | Path | Status |
|-------------|-----------------|------|--------|
| <what the change introduced> | <skill/agent/hook/doc/feature> | <repo-relative path> | ✅ updated |
| <...> | <...> | <repo-relative path> | ✅ created |
| <...> | (none yet) | <intended path> | ⚠ pending |

Deploy note: Artifacts created/updated above live in THIS repo. They reach the
installed configuration ONLY after a manual install step. ARCHIVE cannot
auto-deploy.

Pending count: <N>

Status is a closed enum: ✅ updated, ✅ created, ⚠ pending. No other value is valid. Pending count = number of ⚠ pending rows. This integer is the input to deletion precondition (b) in Step 6. Deploy note is MANDATORY on every run, regardless of whether new artifacts were created.

Step 4 — Save closure to the memory layer

Disk-primary, two steps, disk FIRST. First write docs/sdd/{change-name}/archive-report.md with the closure summary:

Archived: {change-name}. Dates: {start} -> {close}. Summary: {1-2 sentences}.
Specs domains: {domain list}. Skipped phases: {list or "none"}.

Then persist a pointer + summary to the memory layer with topic_key: sdd/{change-name}/archive-report, type: architecture, project: {project}, content = "path: docs/sdd/{change-name}/archive-report.md\n\n{1-3 sentence summary}".

If the persistent memory layer is not reachable: still write the disk artifact (the source of truth); skip the memory-layer pointer only.

Step 5 — Auto-update memory

After the archive is complete, automatically update ai-context/ with the decisions and changes from this cycle.

Process:

1. Load the project's memory-management guidance. 2. Execute the memory update in "update" mode inline, using the archived change as session context:

• Change name: <change-name>
• Artifacts: proposal, specs, design, tasks (from the memory layer)

3. Report the result

Non-blocking error handling:

• On success: report in the output:

  Memory updated: ai-context/ files refreshed with decisions from "[change-name]".

• On failure (guidance not found, write error, any other issue): report a

warning and continue:

  Warning: Memory update failed — [reason]. Archive completed successfully.
  Suggestion: Run /memory-manage (update mode) manually to update ai-context/.

The archive is always considered successful regardless of the memory-update outcome.

Step 6 — Guarded spec-dir deletion

Attempt to delete docs/sdd/<change>/ only after BOTH preconditions hold. Evaluate them in order — short-circuit on the first failure.

Precondition (a) — memory-persisted: search the memory layer for topic_key: sdd/<change>/archive-report scoped to the canonical project. If the row is returned: precondition (a) passes. If no row is returned: retry the memory-layer save once (the save from Step 4 may not have landed); if the retry lands, proceed; if it still fails:

Deletion blocked: archive-report not confirmed in the memory layer (Precondition A failed). Spec dir retained.

STOP. Do NOT evaluate precondition (b). Retain docs/sdd/<change>/ intact.

Precondition (b) — zero pending: read the Pending count: line from the Sync Impact Report emitted in Step 3. If Pending count == 0: precondition (b) passes. If Pending count > 0:

Deletion blocked: Sync Impact Report shows [N] pending piece(s) (Precondition B failed). Spec dir retained.
[list each ⚠ item]

STOP. Retain docs/sdd/<change>/ intact.

Both preconditions pass — move then delete:

1. MOVE: write docs/sdd/_archived/<change>-archive-report.md with the content of docs/sdd/<change>/archive-report.md. If docs/sdd/_archived/ does not exist, create it first. Verify the moved file is readable at its new path. If the write or verify fails:

Deletion aborted: archive-report move to docs/sdd/_archived/ failed — [reason]. Spec dir retained.

STOP. Retain docs/sdd/<change>/ intact.

2. DELETE: git rm -r docs/sdd/<change>/ (removes tracked files), THEN rm -rf docs/sdd/<change>/ to sweep any UNTRACKED residue (git rm skips untracked files — e.g. an archive-report.md or verify-report.md written this cycle but never committed — so the dir would survive half-empty without this second step). After both, the directory MUST be fully gone. The closure record now lives at docs/sdd/_archived/<change>-archive-report.md and in the memory layer — both survive the deletion.

3. Report:

Spec dir deleted: docs/sdd/<change>/ removed.
Closure record: docs/sdd/_archived/<change>-archive-report.md (readable).
Memory-layer pointer: sdd/<change>/archive-report (confirmed in Step 6 precondition check).

Final output:

Change "<change-name>" successfully archived.

Memory: [updated | failed — reason]
Sync Impact Report: [N artifacts updated/created, 0 pending | N pending — install step required]
Spec dir: [deleted — closure record at docs/sdd/_archived/<change>-archive-report.md | retained — [reason]]

Output Contract

{
  "status": "ok|warning|failed",
  "summary": "Change [name] archived. Memory: [updated|failed|skipped].",
  "artifacts": ["sdd/{change-name}/archive-report"],
  "next_recommended": [],
  "risks": []
}

Rules

• NEVER archive with unresolved CRITICAL issues
• ALWAYS confirm with the user before executing (it is irreversible)
• CRITICAL artifacts (proposal, tasks) MUST block with no proceed option — the completeness check MUST run before the verify-report is read
• WARNING artifacts (design, specs) MUST always offer option 2 (acknowledge and proceed) — they MUST NOT silently block
• ARCHIVE MUST enumerate every piece of the change's logic in the Sync Impact Report (Step 3). For each piece with no living artifact, ARCHIVE MUST CREATE the appropriate artifact in this repo. The report MUST state the manual install deploy limitation on every run. ARCHIVE MUST NOT claim any artifact is already deployed to the installed configuration.
• ARCHIVE MUST NOT delete docs/sdd/<change>/ unless BOTH preconditions hold: (a) archive-report confirmed in the memory layer via a post-save search, AND (b) Sync Impact Report Pending count is zero. ARCHIVE MUST MOVE the archive-report to docs/sdd/_archived/<change>-archive-report.md BEFORE deleting the spec dir. On any precondition or move failure, ARCHIVE MUST retain the spec dir and report which step blocked.
• When ARCHIVE creates a missing living artifact (Step 3), the artifact-CREATION sub-step MUST run under a capable model tier by DELEGATING the authoring to a fresh capable-tier worker. ARCHIVE MUST NOT author the artifact on its own lightweight context, and MUST NOT fall back to the lightweight tier for this sub-step. All other ARCHIVE sub-steps MUST remain on the lightweight tier.