feat: add smithy finish step running Atlas at end of cycle

After hone reaches A++, smithy now runs a final finish step before the
merge handoff: update README.md and CHANGELOG.md for the completed
feature, then invoke the atlas skill scoped to that feature when it is
available in the consumer's environment (silent no-op otherwise, like
the kanban sync). Atlas is not vendored by Damascus.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018heVcgSs6P9EMMLJdth1wf

Author: claude

CHANGELOG.md

@@ -34,6 +34,7 @@ All notable changes to this project are documented here, following [Common Chang
 - Change forge's Norms section to require machine-checkable form (the tool + config that enforces each norm, installed as gates by quench) and mark each Safeguard as the source of a property test or runtime assertion
 - Change anvil's task format: optional `[UX]`/`[REFACTOR]`/`[HARD]` tags and a ≤400-changed-line sizing budget per task (oversized tasks come back as anvil feedback via the quench log)
 - Change smithy's state machine to drive hone after quench and halt on hone's 3-round cap
+- Add a smithy finish step at the end of the cycle: after hone reaches A++, update `README.md` and `CHANGELOG.md` for the feature, then run the `atlas` skill scoped to the completed feature if it is available (silent no-op otherwise, like the kanban sync)
 - Move `superpowers:requesting-code-review` from KEEP to DENY — `hone` replaces it; `receiving-code-review` stays KEEP for applying findings
 - Replace the 95% line-coverage gate in `tdd-test-generator`'s pytest config with mutation-testing guidance and a registered `fr` marker for requirement traceability
 

README.md

@@ -37,6 +37,10 @@ Both loops need **no external API**. Each round, three critic subagents with dis
 - **Temper** reviews the *spec triplet* (lenses: completeness, feasibility, testability; max 5 rounds). Each critic runs an active procedure — re-deriving sections, tracing a data flow, drafting per-FR test skeletons — and attaches the artifact; opinions without evidence are discarded. Trail: `specs/NNN-<slug>/review.md`, append-only.
 - **Hone** reviews the *implementation diff* the same way (lenses: spec-conformance, security, simplicity; max 3 rounds), task by task in **≤400-changed-line units**, after quench's tests and gates are green. Fixes never touch tests. Trail: `specs/NNN-<slug>/code-review.md`, append-only.
 
+### Finish step: docs + optional Atlas survey
+
+Once `hone` reaches A++, `smithy` runs a final finish step before the merge handoff: it updates `README.md` and `CHANGELOG.md` for the completed feature, then — **if the `atlas` skill is available in the consumer's environment** — invokes Atlas scoped to that feature to produce an intent-vs-reality survey for the handover. Atlas is not vendored by Damascus; where it is not installed the step is a silent no-op, exactly like the optional kanban sync.
+
 ## Requirements
 
 - git ≥ 2.13 (submodules)

skills/smithy/SKILL.md

@@ -44,7 +44,8 @@ Smithy reads disk and decides which stage to invoke:
 │ tasks.md has unchecked items│ quench in progress │ continue quench  │
 │ all tasks checked, CI green │ quench done     │ run hone            │
 │ code-review.md, last < A++  │ hone iterating  │ continue hone       │
-│ code-review.md ends A++     │ hone done       │ hand off to finish  │
+│ code-review.md ends A++     │ hone done       │ run finish step     │
+│ README/CHANGELOG updated    │ finish done     │ hand off to merge   │
 └─────────────────────────────┴─────────────────┴─────────────────────┘
 ```
 
@@ -97,6 +98,27 @@ Smithy invokes each stage Skill **directly**; it does not duplicate their bodies
 
 Each stage that smithy drives runs **its own** board/state sync at its "Gate to Next Stage" — and only if the host repo ships one. **Smithy therefore adds NO sync call of its own** — doing so would double-sync every transition. Any post-merge sync belongs to the host repo's merge tooling.
 
+## Finish Step (post-hone, absolute end of the cycle)
+
+After `hone` reaches A++ and its gate is signed off, the feature is complete. Before
+handing off to `superpowers:finishing-a-development-branch`, smithy runs one final step:
+
+1. **Update `README.md` and `CHANGELOG.md`** for the completed feature (NNN). CHANGELOG
+   gets a single-line entry under `[Unreleased]` in the host repo's changelog convention;
+   README gets whatever the feature changed in user-facing behavior (skip README if the
+   feature is purely internal). This is the cycle's documentation gate.
+2. **Run Atlas, if available.** Every completed pipeline run is a major feature, so once
+   the docs are updated, smithy checks whether the **`atlas` skill is available in this
+   environment**. If it is, invoke it **scoped to the just-completed feature (NNN)** —
+   Atlas surveys that feature's artifacts (its PRD, spec triplet, review trails) and
+   verifies them against the shipped code, producing an intent-vs-reality map for the
+   handover. If `atlas` is **not** available, **skip silently** — exactly like the kanban
+   sync. Atlas is not vendored by Damascus; this step is a no-op wherever the consumer
+   has not installed it.
+
+This step runs **after** the hone gate signoff and is the last thing smithy does before
+the merge handoff. It adds no board sync of its own (see the single-call-site rule above).
+
 ## Handoff Messages
 
 After every stage exit, smithy prints:
@@ -120,6 +142,8 @@ After full pipeline completion:
   - Code reviews: specs/NNN-<slug>/code-review.md (A++ in N rounds)
   - Tests: <count>
   - Implementation commits: <count>
+  - Docs: README.md + CHANGELOG.md updated for NNN
+  - Atlas: <survey path> | skipped (atlas skill not available)
   Next: superpowers:finishing-a-development-branch
 ```