safeword 0.40.1 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "safeword",
-  "version": "0.40.1",
+  "version": "0.41.0",
   "description": "CLI for setting up and managing safeword development environments",
   "repository": {
     "type": "git",

package/templates/SAFEWORD.md

@@ -20,7 +20,12 @@ Each turn:
 4. Incorporate what the user confirmed; narrow the open set.
 5. When zero open questions remain and the user accepts → advance.
 
-Research before proposing anything significant. Read the relevant code, docs, and prior tickets. Identify 2-3 options, weigh them on correctness, simplicity, and no-bloat, then propose one with rationale.
+Research before proposing anything significant — and the order is load-bearing:
+
+1. **Frame** the problem and its hard constraints: prior tickets, the data model, non-negotiable framework idioms. Don't read the soft conventions yet.
+2. **Design the ideal.** Run `/figure-it-out` to weigh 2-3 options on correctness, simplicity, and no-bloat, and pick the best architecture _as if the codebase didn't exist_. Computing this first gives the next step a yardstick.
+3. **Survey the existing patterns** in the area you're about to touch — now, not before. Surveying earlier anchors the design to the status quo and quietly shrinks it to match.
+4. **Reconcile.** Conform to the existing pattern by default — deviate only when the ideal is a real improvement, not taste. When your ideal diverges from what exists, record the call: to deviate, name a concrete defect of the existing pattern the ideal fixes, the call-site count you're splitting, a one-line pre-mortem ("assume this was wrong — what broke?"), and the follow-up ticket to uplevel the rest. Reversible and local → a few lines in the ticket; irreversible or cross-cutting (data model, public API) → promote to an ADR. See `./.safeword/guides/architecture-guide.md`.
 
 Depth scales with ambiguity. Clear request → 0 turns. One open question → 1 turn. Vague idea → 2-3 turns of increasingly specific proposals.
 

package/templates/commands/verify.md

@@ -102,8 +102,11 @@ The Status section uses the existing Verify Checklist format. Format with these
 **Scenarios:** All N scenarios marked complete (or ❌ X/Y complete, or ⏭️ Skipped — no ticket)
 **Dep Drift:** ✅ Clean (or ⚠️ N undocumented deps, or ⏭️ Skipped — no ARCHITECTURE.md)
 **Parent Epic:** {id} (siblings: X/Y done) or N/A
+**Reconcile:** ✅ No pattern deviation (or ⚠️ N deviations, M missing uplevel ticket — soft, never blocks)
 ```
 
+**Reconcile** is soft — it never blocks the done gate. If the work introduced a pattern that diverges from existing siblings (see `.safeword/guides/architecture-guide.md` → Survey & Reconcile), confirm the ticket carries a reconcile record and every deviation has an uplevel follow-up ticket; flag any that don't. Use `N/A` when the work conformed or introduced no new pattern.
+
 **Done-gate evidence patterns** (the stop hook validates these literal phrases — do not move or rename):
 
 - `✓ X/X tests pass` — proves test suite ran

package/templates/guides/architecture-guide.md

@@ -4,6 +4,48 @@
 
 ---
 
+## Survey & Reconcile (Before You Propose)
+
+The order is load-bearing (full version in `@.safeword/SAFEWORD.md` → Clarify):
+
+1. **Frame** the hard constraints — data model, non-negotiable framework idioms, prior decisions.
+2. **Design the ideal** with `/figure-it-out`, as if the codebase didn't exist. This is your yardstick.
+3. **Survey** the existing patterns in the area — _now_, not before. Surveying first anchors the design to the status quo.
+4. **Reconcile** — conform by default; record the call when your ideal diverges.
+
+### Survey: what to look for
+
+- **Sibling implementations** — grep the layer/feature for code that solves the same shape of problem. How is it structured?
+- **Prior decisions** — search `ARCHITECTURE.md` and tickets for an existing ruling on this pattern.
+- **Tests near the code** — they encode the conventions you'd be expected to match.
+- **Call-site count** — how many places use the existing pattern? Write the number down; it is the cost of deviating.
+
+### Reconcile: conform by default
+
+Default to the existing pattern. Per Google's code-review standard, conform "as long as that doesn't worsen the overall code health of the system" — deviate only when your ideal is a _real_ improvement, not your taste.
+
+**Ideal and existing agree → no decision, no record.** When they diverge, record the call (below). You can't silently conform your ideal away (that is how mediocre patterns calcify), and you can't silently deviate (that is how a codebase splits in two).
+
+### The reconcile record
+
+Required only when the ideal diverges from what exists:
+
+| Field                       | Notes                                                                                                           |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Direction**               | Conform, or deviate                                                                                             |
+| **Reason**                  | The load-bearing why                                                                                            |
+| **Health defect** (deviate) | A _named_ failure of the existing pattern the ideal fixes. "Cleaner" is not a defect.                           |
+| **Inconsistency cost**      | The call-site count you're splitting (from the survey)                                                          |
+| **Pre-mortem**              | One line: "assume deviating was wrong — what broke?" Prospective hindsight surfaces costs you're discounting.   |
+| **Uplevel ticket**          | The tracked follow-up to migrate the rest. Track it; don't migrate every call site now (avoid the rabbit-hole). |
+
+**Depth scales with reversibility:**
+
+- **Reversible + local** → the record is a few lines in the ticket.
+- **Irreversible or cross-cutting** (data model, public API) → promote to a full Architecture Doc decision (What / Why / Trade-off / Alternatives, below) and get a second opinion that tries to _refute_ the deviation before committing.
+
+---
+
 ## Document Type Decision Tree (Follow in Order)
 
 Answer **IN ORDER**. Stop at the first "Yes":

package/templates/skills/bdd/DISCOVERY.md

@@ -99,6 +99,8 @@ If any answer is vague, you have open questions — surface them.
 
 **When the feature leans on a library or framework** — read the installed version's docs before proposing API shapes or done-when criteria. Scope baked on training memory of a different version is silently wrong. Check `package.json` / lockfile first, then the source wired up (Context7, official docs, README at the pinned ref).
 
+**When the feature introduces architecture or a new pattern** — design the ideal first (`/figure-it-out`), _then_ survey the existing patterns in the area and reconcile: conform by default, deviate only with a named defect and an uplevel follow-up ticket. See `.safeword/guides/architecture-guide.md` → Survey & Reconcile.
+
 ## Worked example: Phase 0 end to end
 
 One feature walked through all four artifacts and every sub-phase gate. Slug `oauth-flow`: let an operator rotate an API key without a coordinated flag day.

package/templates/skills/verify/SKILL.md

@@ -106,8 +106,11 @@ The Status section uses the existing Verify Checklist format. Format with these
 **Scenarios:** All N scenarios marked complete (or ❌ X/Y complete, or ⏭️ Skipped — no ticket)
 **Dep Drift:** ✅ Clean (or ⚠️ N undocumented deps, or ⏭️ Skipped — no ARCHITECTURE.md)
 **Parent Epic:** {id} (siblings: X/Y done) or N/A
+**Reconcile:** ✅ No pattern deviation (or ⚠️ N deviations, M missing uplevel ticket — soft, never blocks)
 ```
 
+**Reconcile** is soft — it never blocks the done gate. If the work introduced a pattern that diverges from existing siblings (see `.safeword/guides/architecture-guide.md` → Survey & Reconcile), confirm the ticket carries a reconcile record and every deviation has an uplevel follow-up ticket; flag any that don't. Use `N/A` when the work conformed or introduced no new pattern.
+
 **Done-gate evidence patterns** (the stop hook validates these literal phrases — do not move or rename):
 
 - `✓ X/X tests pass` — proves test suite ran