@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/architecture/SKILL.md

@@ -0,0 +1,436 @@
+---
+name: architecture
+description: "This skill should be used when managing Architecture Decision Records or C4 diagrams."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Architecture as Code
+
+Create, manage, and query Architecture Decision Records (ADRs) and maintain an interactive [LikeC4](https://likec4.dev/) architecture model. ADRs are version-controlled markdown; the C4 model is version-controlled LikeC4 DSL (`.c4`). All artifacts live in `knowledge-base/engineering/architecture/`.
+
+<!-- operator-typed-render:start -->
+**Any message this skill PRINTS that tells the operator to run a skill or command renders at emit time.** The doc names it canonically (`soleur:<name>`, ADR-226); before printing, render it as the active harness's **operator-typed form** per `formatSkillInvocation` (`plugins/soleur/lib/harness.ts`), which owns the per-harness slash and sigil forms — the operator types that string into a fresh session where no routing contract is in context, so a bare canonical name is model-discretion there rather than a dispatch. This covers abort messages, `AskUserQuestion` prompts and options, `Display`/`echo` lines and resume prompts alike; an agent-read instruction stays canonical.
+<!-- operator-typed-render:end -->
+
+## Sub-commands
+
+| Command | Description |
+|---------|-------------|
+| `architecture create [title]` | Create a new ADR with the next sequential number |
+| `architecture list` | Display all ADRs with status, title, and date |
+| `architecture supersede <N> [title]` | Mark ADR-N as superseded and create its replacement |
+| `architecture diagram [type]` | Create or update the LikeC4 model and its views (context, container, component) |
+| `architecture add-container <id>` | Add a container/database element to the model |
+| `architecture add-component <id>` | Add a component element to the model |
+| `architecture add-relationship <from> <to>` | Add a relationship between two model elements |
+| `architecture render` | Validate the LikeC4 project (`likec4 validate`) and report element/view counts |
+| `architecture assess [feature]` | Assess a feature against the NFR register and principles register |
+| `architecture principle list` | Display the architecture principles register |
+
+If no sub-command is provided, display the table above and ask which sub-command to run.
+
+## Arguments
+
+`$ARGUMENTS` is parsed for a sub-command and optional parameters:
+
+```text
+architecture [sub-command] [arguments...]
+```
+
+---
+
+## Phase 0: Prerequisites
+
+Verify the knowledge-base directory exists:
+
+```bash
+if [[ ! -d "knowledge-base" ]]; then
+  echo "No knowledge-base/ directory found. Create one first or run soleur:sync."
+  # Stop execution
+fi
+```
+
+Create the architecture directories if they do not exist:
+
+```bash
+mkdir -p knowledge-base/engineering/architecture/decisions
+mkdir -p knowledge-base/engineering/architecture/diagrams
+```
+
+**Branch safety check (defense-in-depth):** Run `git branch --show-current`. If the result is `main` or `master`, abort with: "Error: architecture skill cannot run on main/master. Checkout a feature branch first."
+
+**Vocabulary.** Before committing a word that names a concept, check it against `knowledge-base/project/glossary.md` and use the sense its pointer settles; if the word is materially ambiguous and has no entry, hedge in the artifact and name the ambiguity. The instruction is stated once in [glossary-format.md](../kb-glossary/references/glossary-format.md) §The consumer pointer and is not restated here.
+
+**Rejected-concepts substrate.** Before recording a decision that refuses a *concept* rather than a
+*mechanism*, read [ADR-234](../../../../knowledge-base/engineering/architecture/decisions/ADR-234-rejected-concepts-are-a-distinct-kb-substrate.md):
+an ADR's `## Alternatives Considered` table is scoped to the mechanisms of one decision, so a
+concept-level refusal belongs in the no-list at `knowledge-base/project/rejected/` instead, where the
+intake pre-check can find it by concept. The two are siblings, not substitutes — the no-list cites ADR
+tables as a store the lookup also checks, and imports nothing from them.
+
+---
+
+## Sub-command: create
+
+Create a new ADR with the next sequential number.
+
+### Steps
+
+1. **Determine next ADR number.** List existing ADRs in `knowledge-base/engineering/architecture/decisions/`:
+
+   ```bash
+   ls knowledge-base/engineering/architecture/decisions/ADR-*.md 2>/dev/null | sort -V | tail -1
+   ```
+
+   Extract the highest number and increment by 1. If no ADRs exist, start at 001.
+
+2. **Get the title.** If a title was provided in `$ARGUMENTS`, use it. Otherwise, use AskUserQuestion: "What architectural decision are you recording?"
+
+3. **Generate the filename.** Convert the title to kebab-case: `ADR-<NNN>-<kebab-title>.md`
+
+4. **Read the ADR template** from [adr-template.md](./references/adr-template.md). The template now documents two labeled body shapes (terse / rich) under the `## Choosing the shape` section. Read that section before proceeding.
+
+5. **Ask the shape rubric.** Present the 5 triggers from the template's `## Choosing the shape` section and pick between the terse and rich shapes. Use AskUserQuestion with options:
+
+   - "No — terse (3 sections)"
+   - "Yes — rich (8 sections)"
+   - "Unsure — walk me through each trigger"
+
+   If the contributor picks "Unsure," ask each of the 5 triggers as its own yes/no AskUserQuestion. Compute: any yes → rich, all no → terse.
+
+   **Pipeline mode default.** If running inside `soleur:one-shot` or any other non-interactive caller (no AskUserQuestion available, only `$ARGUMENTS` context), default to **terse**. Rich-shape ADRs in pipeline mode require the caller to pass `shape: rich` explicitly in `$ARGUMENTS`, or the rubric falls through to terse.
+
+6. **Write the ADR file.** Create `knowledge-base/engineering/architecture/decisions/ADR-<NNN>-<kebab-title>.md` using the chosen shape's body block from the template. The filename is the sole ordinal authority; do not add an `adr:` frontmatter key. Fill in frontmatter:
+   - `title: <title>`
+   - `status: active`
+   - `date: <today YYYY-MM-DD>`
+
+7. **Gather context.** Ask the user (or use `$ARGUMENTS` context if running in pipeline). The prompt list branches on the shape chosen in step 5:
+
+   **Terse branch (3 prompts):**
+
+   - **Context:** What motivates this decision?
+   - **Decision:** What is the change being made?
+   - **Consequences:** What becomes easier or harder?
+
+   **Rich branch (8 prompts):**
+
+   - **Context:** What motivates this decision?
+   - **Considered Options:** What alternatives were evaluated? (list with pros/cons and links to tentative C4 model changes)
+   - **Decision:** Which option was chosen and why?
+   - **Consequences:** What becomes easier or harder?
+   - **Cost Impacts:** How much does this change increase or reduce costs? (reference `knowledge-base/operations/expenses.md` for baseline; use "None" if no impact)
+   - **NFR Impacts:** Which non-functional requirements are affected? Read [nfr-reference.md](./references/nfr-reference.md) for the assessment checklist and common patterns by decision type. Reference NFR IDs from `knowledge-base/engineering/architecture/nfr-register.md`. Use "None" if no impact.
+   - **Principle Alignment:** Which architectural principles does this decision align with or deviate from? Read `knowledge-base/engineering/architecture/principles-register.md` for the register. Reference AP-NNN IDs. Use "None" if no impact.
+   - **Diagram:** (optional) Should a LikeC4 diagram be included or updated?
+
+8. **Write the ADR body** with the gathered context. If a diagram was requested (rich branch only), update the consolidated LikeC4 model using [likec4-reference.md](./references/likec4-reference.md) (see the `diagram` sub-command) and embed the relevant view with a ` ```likec4-view ` block.
+
+8.5. **Domain-model register check.** If this ADR records or changes a **business rule** — an entity invariant, an ownership/access model, or a relationship encoded in a migration constraint / RLS policy / resolver-guard — update the affected row(s) in [`knowledge-base/engineering/architecture/domain-model.md`](../../../../knowledge-base/engineering/architecture/domain-model.md) in the same change: add or amend the rule with a citation back to this ADR. Rule IDs are immutable — supersede (mark + link the successor row), never reuse. If the ADR is purely a technology/process decision with no entity-invariant impact, skip silently.
+
+9. **Announce:** "Created ADR-<NNN>: <title> at `knowledge-base/engineering/architecture/decisions/ADR-<NNN>-<kebab-title>.md`"
+
+---
+
+## Sub-command: list
+
+Display all ADRs with their status, number, title, and date.
+
+### Steps
+
+1. **Scan the decisions directory:**
+
+   ```bash
+   ls knowledge-base/engineering/architecture/decisions/ADR-*.md 2>/dev/null
+   ```
+
+2. **If no ADRs exist:** Display "No ADRs found. Run `soleur:architecture create` to create one."
+
+3. **For each ADR file:** Read the YAML frontmatter and extract `adr`, `title`, `status`, `date`.
+
+4. **Display as a table:**
+
+   ```text
+   | # | Title | Status | Date |
+   |---|-------|--------|------|
+   | ADR-001 | Use LikeC4 for diagrams | active | 2026-03-27 |
+   | ADR-002 | PWA-first architecture | superseded | 2026-03-20 |
+   ```
+
+---
+
+## Sub-command: supersede
+
+Mark an existing ADR as superseded and create its replacement.
+
+### Steps
+
+1. **Parse the ADR number** from `$ARGUMENTS`. If not provided, use AskUserQuestion: "Which ADR number to supersede?"
+
+2. **Find the existing ADR** by matching `ADR-<NNN>-*.md` in `knowledge-base/engineering/architecture/decisions/`.
+
+3. **If not found:** Display "ADR-<NNN> not found." and stop.
+
+4. **If already superseded:** Display "ADR-<NNN> is already superseded by ADR-<M>." and stop.
+
+5. **Get the replacement title.** If provided in `$ARGUMENTS`, use it. Otherwise, use AskUserQuestion: "What is the title of the replacement decision?"
+
+6. **Create the replacement ADR** using the `create` sub-command flow (next sequential number). Add `supersedes: ADR-<NNN>` to the YAML frontmatter.
+
+7. **Update the original ADR.** Read the file and update:
+   - `status: superseded`
+   - Add `superseded-by: ADR-<NEW>`
+
+8. **Announce:** "ADR-<NNN> superseded by ADR-<NEW>: <title>"
+
+---
+
+## Sub-command: diagram
+
+Create or update the canonical **LikeC4** model. Soleur uses ONE consolidated
+model — every element is declared once and the views scope it to each C4 level
+with clickable drill-down (Context → Container → Component). The model is
+rendered interactively in the web Knowledge Base viewer; static Mermaid C4 is no
+longer emitted.
+
+**Read [likec4-reference.md](./references/likec4-reference.md) now** for the
+complete LikeC4 DSL syntax before editing any model.
+
+### Project layout
+
+> **`.c4` edits are not gated for this workflow.** The `c4-edit` runtime flag
+> (commit `3c8849655`) gates ONLY direct end-user edits in the in-browser webapp
+> editor (`PUT /api/kb/c4`, default OFF). It does **not** gate a workflow: Concierge
+> and the Claude Code plugin terminal are equally-trusted agent contexts that edit
+> the `.c4` files on the filesystem (Edit/Write) and commit them via this skill —
+> they never route through the webapp endpoint. Edit `.c4` directly; do not defer a
+> model change to "ask the Concierge."
+
+The model lives as a LikeC4 project under
+`knowledge-base/engineering/architecture/diagrams/`:
+
+- `spec.c4` — `specification` block: element kinds (actor, system, container, database, component) and tags.
+- `model.c4` — `model` block: every element (nested systems → containers → components) and every relationship, declared once.
+- `views.c4` — `views` block: one `view <id> [of <element>]` per C4 level. `view <id> of <element>` gives the parent element an automatic drill-down button.
+- `<view>.md` — thin pages embedding a view for the KB viewer via a fenced ` ```likec4-view ` block whose body is the view id, plus a `## Notes` section.
+
+### Steps
+
+1. **Gather context.** Read to understand the system:
+   - `knowledge-base/project/README.md` and `knowledge-base/project/components/`
+   - Existing ADRs in `knowledge-base/engineering/architecture/decisions/`
+   - The current `.c4` project in the diagrams dir — **READ all three files in full** (`model.c4`, `views.c4`, `spec.c4`), never a single keyword grep (do not duplicate elements that already exist).
+
+   **External-actor / external-system completeness sweep (do this before concluding "nothing to add").** For the change at hand, enumerate every (a) external human actor (who sends/receives the data — correspondents, reviewers, recipients), (b) external system/vendor (inbound webhook, outbound API, third-party store), (c) container/data-store touched, and (d) actor↔surface access relationship that changes. For each, confirm it is already modeled; if not, add it (element + `#external` tag if outside the platform boundary + the relationship edges + the `views.c4` `include` line so it RENDERS). A `grep` for the feature's own noun returning zero is NOT evidence of absence — the gap is usually an external actor/vendor named by role/vendor, not the feature (e.g. an inbound-email "Correspondent" actor + a "Resend" system for an email feature). Also fix any element **description** the change falsifies (e.g. a "Solo founder" actor when the change adds multi-Owner sharing). See `knowledge-base/project/learnings/2026-06-18-c4-impact-requires-reading-all-diagrams-and-enumerating-external-actors.md`.
+
+2. **Edit the consolidated model** (`spec.c4` / `model.c4`), following
+   [likec4-reference.md](./references/likec4-reference.md). Key rules:
+   - Declare each element exactly once; nest children inside their parent (`system { container { component } }`). Nesting creates the C4 boundary automatically — there is no separate boundary keyword.
+   - Relationships: `from -> to "label" { technology "HTTPS" }`. Reference nested elements by qualified path in views (`platform.webapp.dashboard`).
+   - Tag third-party systems `#external`.
+
+3. **Edit the views** (`views.c4`): ensure a view exists per level you want to
+   show. Wire drill-down with `view <id> of <parent>` so the parent element in
+   the higher-level view links into it.
+
+4. **Write/refresh the view page(s).** For each view that needs a KB page, write
+   `knowledge-base/engineering/architecture/diagrams/<view>.md`:
+
+   ````markdown
+   # <Title> (C4 Level N)
+
+   Generated: YYYY-MM-DD
+
+   ```likec4-view
+   <view-id>
+   ```
+
+   ## Notes
+
+   [Context about the diagram, references to relevant ADRs]
+   ````
+
+5. **Validate** (see `render` below) and **announce**:
+   "LikeC4 model updated — N elements, M relationships, K views."
+
+---
+
+## Sub-commands: add-container, add-component, add-relationship
+
+Incremental edits to the consolidated model. Each is a focused patch to the
+`.c4` files (no Mermaid). After any patch, run `render` (see below) to
+**validate** the source, then regenerate `model.likec4.json` with `render` and commit it
+with the `.c4` change. (In the Soleur repository itself a `c4-model-regenerate`
+pre-commit hook does this on commit; other repositories have no such hook.)
+
+- **add-container `<id>`** / **add-component `<id>`** — add an element inside the
+  correct parent in `model.c4` (`container` / `database` / `component` kind),
+  with `technology` and `description`. Add it to the relevant `view`'s `include`
+  list in `views.c4` if it should appear.
+- **add-relationship `<from> <to>`** — append `from -> to "label" { technology "…" }`
+  to `model.c4`, using existing element ids (qualified if nested).
+
+Gather the label/technology/description from `$ARGUMENTS` or via AskUserQuestion.
+
+---
+
+## Sub-command: render
+
+Validate the LikeC4 project and rebuild the precomputed model the web viewer
+renders. The Knowledge Base viewer does NOT run the `likec4` toolchain at
+runtime (it would pull vite/esbuild into production deps); it reads the
+committed, layouted `model.likec4.json`.
+
+**Run this after every `.c4` edit and commit the result.** Only the Soleur repository
+regenerates on commit automatically (its `c4-model-regenerate` lefthook hook, backed by
+`plugins/soleur/test/c4-model-freshness.test.sh` in CI); in any other repository an
+unregenerated `model.likec4.json` stays stale until someone runs this:
+
+```bash
+# Canonical regen (pinned, off-tree-validated, idempotent) — same primitive the
+# pre-commit hook and the merge resolver run; renders the current repository:
+bash "${CLAUDE_PLUGIN_ROOT}/scripts/render-c4-model.sh"
+
+# Or validate only (line-numbered diagnostics) without rewriting the artifact:
+# --no-use-dot keeps the drift check on the same wasm layout the artifact was
+# rendered with — a dot-layout verdict would disagree with committed bytes.
+cd knowledge-base/engineering/architecture/diagrams
+npx -y likec4@1.50.0 validate --no-use-dot .
+```
+
+The pinned `1.50.0` is load-bearing: it MUST match `apps/web-platform/Dockerfile`
+
+- `package.json` (`@likec4/core` / `@likec4/diagram`), guarded by
+`c4-likec4-version-pin.test.ts`. Never pin to a floating tag (the unpinned
+`likec4` / a moving release) — a CLI/client schema skew silently corrupts the
+rendered diagram. `render-c4-model.sh` renders
+off-tree and refuses to publish an empty/invalid/zero-view model, so a broken
+`.c4` or a failed layout can never clobber the good committed artifact.
+
+On success, report element / relationship / view counts (read the
+`elements` / `relations` / `views` key counts from `model.likec4.json`). On
+failure, branch on the refusal class — do NOT uniformly "fix the source":
+
+- **Source validation error or empty/degenerate model** — surface the
+  line-numbered diagnostics and fix the `.c4` source before continuing.
+- **"elements but no views — a layout failure"** — the `.c4` source is
+  innocent; editing it cannot help. Read the render log tail the refusal
+  prints, retry the render once, and if it persists reproduce with the
+  `export json --no-use-dot` command the message names, then report the
+  outcome rather than hand-editing the model.
+
+---
+
+## Sub-command: assess
+
+Assess a feature or plan against the NFR register to identify which non-functional requirements are relevant and what their current status is.
+
+**Read [nfr-reference.md](./references/nfr-reference.md) now** for the assessment checklist and common NFR patterns by decision type.
+
+### Steps
+
+1. **Get the feature description.** If provided in `$ARGUMENTS`, use it. Otherwise, check for a plan file on the current branch:
+
+   - If on a `feat-*` branch, look for `knowledge-base/project/plans/*<feature-slug>*-plan.md`
+   - If a plan exists, read it and extract the feature description from the Overview section
+   - Otherwise, use AskUserQuestion: "What feature or change are you assessing?"
+
+2. **Read the NFR register** at `knowledge-base/engineering/architecture/nfr-register.md`.
+
+3. **Read the principles register** at `knowledge-base/engineering/architecture/principles-register.md`. If it does not exist, skip principle alignment in step 5b.
+
+4. **Identify affected containers and links.** Read the Container & Link Inventory in the NFR register. Map the feature to specific C4 containers and links it touches (e.g., a new external service adds a network link; a new UI feature affects Dashboard and API Routes).
+
+5. **Classify the feature** against the decision type patterns from [nfr-reference.md](./references/nfr-reference.md):
+
+   - New external service integration
+   - Infrastructure change
+   - New user-facing feature
+   - Data model change
+   - Security change
+   - Deployment change
+
+6. **Assess each NFR category.** For each of the 7 categories (Observability, Resilience, Testing, Configuration & Delivery, Scaling & Recovery, Security, Data Quality), determine:
+
+   - Which specific NFRs are relevant to the affected containers/links
+   - Current per-container/link status from the NFR register tables
+   - Whether this feature improves, degrades, or has no effect on each NFR for the affected containers/links
+   - Any evidence gaps (rows with "Applicable: Yes" but no evidence documented)
+   - Any new NFRs that should be added to the register
+
+7. **Assess principle alignment.** For each principle in the register (AP-001 through AP-NNN), determine: relevant to this feature (yes/no), alignment status (Aligned/Deviation/N/A), and brief rationale. Skip if the principles register was not found in step 3.
+
+8. **Output the assessment** as a per-container table:
+
+   ```text
+   ## NFR Assessment: [Feature Name]
+
+   ### Affected Containers/Links
+
+   - Dashboard, API Routes, Agent Runtime -> New External Service (new link)
+
+   ### Assessment
+
+   | NFR | Requirement | Container/Link | Status | Impact | Evidence Gap |
+   |-----|-------------|----------------|--------|--------|-------------|
+   | NFR-001 | Logging | New Service | — | Needs attention | No logging configured |
+   | NFR-026 | Encryption In-Transit | Agent Runtime -> New Service | — | Needs attention | HTTPS required |
+   | NFR-007 | Circuit Breaker | Agent Runtime -> New Service | — | Risk introduced | No fallback for new dependency |
+   | NFR-026 | Encryption In-Transit | Founder -> Dashboard | Implemented | No change | Cloudflare |
+   ```
+
+   If the principles register was loaded, add a Principle Alignment section:
+
+   ```text
+   ### Principle Alignment
+
+   | Principle | Title | Status | Note |
+   |-----------|-------|--------|------|
+   | AP-001 | Terraform-only provisioning | Aligned | New infra uses Terraform |
+   | AP-008 | Doppler secrets | N/A | No new secrets |
+   ```
+
+9. **Recommend actions.** For each NFR with "Needs attention" or "Risk introduced" impact, propose a specific action referencing the affected container/link (e.g., "Add circuit breaker on Agent Runtime -> Stripe link", "Configure structured logging for New Service container"). For each principle with "Deviation" status, explain the deviation and whether an exception is justified.
+
+10. **Offer to create an ADR.** If the assessment reveals architectural decisions (e.g., choosing to accept a risk, implementing a new NFR, deviating from a principle), ask: "Create an ADR to document these decisions?" Principle alignment will be pre-filled from the assessment.
+
+---
+
+## Sharp Edges
+
+- **A re-open or review trigger keyed on an issue CLOSING fires at the merge of the PR that fixes it, when zero post-fix data exists.** Bind an ADR trigger to a sample floor or a date ("≥N rows after the fix merged, or T+6 weeks"), have the fixing PR carry `Ref #N`, and close the issue only after the re-run. **Why:** #8399 — ADR-229's "when #8470 closes, re-run the triage" would have reported all-clear on an empty sample. See `knowledge-base/project/learnings/2026-09-21-a-re-open-trigger-keyed-on-an-issue-closing-fires-at-the-fixing-merge.md`.
+
+- **An ADR ordinal derived across ALL `origin/*` refs still goes stale within a day — re-derive immediately before merge, and scope the renumber sweep to YOUR files.** `ls decisions/` is not enough (it misses sibling branches) and neither is a one-time cross-ref sweep (a sibling merges, or claims the next two, while your PR is in review). Derive with `for r in $(git for-each-ref --format='%(refname)' refs/remotes/origin); do git ls-tree --name-only "$r" knowledge-base/engineering/architecture/decisions/; done | grep -oE 'ADR-[0-9]+' | sort -u -t- -k2 -n | tail`, and re-run it as the last step before merge. When renumbering, sweep only the files YOUR branch owns — the colliding ADR's own citations (plugin scripts, `model.c4`, `model.likec4.json`, session-state) must not move, and a blanket search-replace will take them. **Why:** #7441 — ADR-178 was free across 65 refs at plan time; #7426 landed it the next day and 179/180 were claimed by two sibling branches by the time it was re-checked, so it renumbered to 181 with 27 citations swept and 8 deliberately left alone.
+
+- **Regenerating a generated artifact during a merge: render from the merged tree's git objects into private staging, never in the live worktree.** Every worktree state a mid-merge render can meet (interrupt, concurrent edit, a likec4 config loaded as code, a symlink out of the repo) needs its own guard; `git merge-tree --write-tree` plus `git cat-file blob` removes those states by construction. The resolver's design is recorded in the ADR-235 amendment of 2026-09-23. See `knowledge-base/project/learnings/2026-09-23-every-guard-i-wrote-defended-a-worktree-the-render-never-needed.md`.
+
+## ADR vs Learning
+
+ADRs and learnings serve different purposes:
+
+| | ADR | Learning |
+|---|-----|---------|
+| **When** | At decision time | After implementation |
+| **What** | "Why we chose X over Y" | "What went wrong and how we fixed it" |
+| **Format** | Context / Decision / Consequences | Problem / Solution / Key Insight |
+| **Location** | `knowledge-base/engineering/architecture/decisions/` | `knowledge-base/project/learnings/` |
+| **Lifecycle** | Active → Superseded | Evergreen (archived when stale) |
+
+---
+
+## Sub-command: principle list
+
+Display the architecture principles register.
+
+### Steps
+
+1. **Read the principles register** at `knowledge-base/engineering/architecture/principles-register.md`.
+
+2. **If the file does not exist:** Display "No principles register found. Create one at `knowledge-base/engineering/architecture/principles-register.md`."
+
+3. **Display the principles table** from the register, preserving the markdown table format.
+
+4. **Display the enforcement tiers table** below the principles table.

package/skills/architecture/references/adr-template.md

@@ -0,0 +1,154 @@
+# ADR Template
+
+Use this template when creating Architecture Decision Records. Read `## Choosing the shape` first to pick between the terse (3-section) and rich (8-section) body layouts.
+
+## YAML Frontmatter
+
+```yaml
+---
+title: [Decision Title]
+status: active | superseded
+date: YYYY-MM-DD
+superseded-by: ADR-NNN  # only when status is superseded
+supersedes: ADR-NNN     # only when this ADR replaces another
+---
+```
+
+> The ordinal lives in the **filename only** (`ADR-NNN-slug.md`) — do NOT add an
+> `adr:` frontmatter key. A frontmatter ordinal can disagree with the filename
+> and make `ADR-NNN` references ambiguous; `scripts/check-adr-ordinals.sh` layer 4
+> rejects any `adr:` key (#6800).
+
+## Choosing the shape
+
+ADRs come in two shapes. Pick at create-time based on the rubric below — do not mix sections from the two shapes.
+
+- **Terse (3 sections)** — Context, Decision, Consequences. Matches Michael Nygard's original 2011 ADR pattern. Optimized for read-speed and ease of authoring; readable in under 60 seconds. Use for narrow, one-decision records. Exemplar: [ADR-007 (Doppler secrets management)](../../../../knowledge-base/engineering/architecture/decisions/ADR-007-doppler-secrets-management.md) — 19 lines, three sections, no amendment.
+  > ADR-006 was this exemplar until 2026-09-09. It still has the terse *standing* shape — Context, Decision, Consequences — but #7836 appended a long dated `## Amendment` audit record to it, so it no longer reads as a 60-second example of the form. An amendment is a fourth *record*, not a fourth standing section; the shape rubric below is unchanged by it.
+- **Rich (8 sections)** — Context, Considered Options, Decision, Consequences, Cost Impacts, NFR Impacts, Principle Alignment, Diagram. Matches the MADR (Markdown Architectural Decision Records) 3.0 "full" template, extended with Soleur-specific Cost Impacts, NFR Impacts, and Principle Alignment sections. Optimized for audit-trail on cross-cutting decisions. Exemplar: [ADR-021 (KB binary-serving pattern)](../../../../knowledge-base/engineering/architecture/decisions/ADR-021-kb-binary-serving-pattern.md).
+
+### Rubric — pick rich when any one trigger is true
+
+Default to terse. Use rich when **any one** of the following is true. Each trigger is a yes/no question whose answer is checkable against a file that already exists in the repo.
+
+1. **Cross-cutting code surface.** Does the decision govern behavior in **2+ existing** routes/modules/skills at write time? Check: grep the decision's named helper, module, or concept across the repo and count the existing consumers. Example: ADR-021 governs `serveKbFile` consumed by two routes at write time → yes. ADR-006 governs a Terraform backend config pattern that each new `main.tf` reuses independently, with zero shared consumers at write time → no. Forward-looking "every future X" patterns do NOT hit this trigger on their own — wait until 2+ consumers exist, then supersede with a rich ADR if warranted. This keeps the rubric observable (grep can answer it) rather than subjective.
+2. **Material cost impact.** Does the decision introduce a new paid vendor, change a billing tier, or eliminate a paid service? Check: does the decision appear in or change anything in `knowledge-base/operations/expenses.md`?
+3. **NFR-moving.** Does the decision change the status of one or more NFRs in `knowledge-base/engineering/architecture/nfr-register.md` from one tier to another (e.g., Partial → Implemented)? Check: diff the expected NFR register state before and after implementation.
+4. **Principle deviation.** Does the decision deviate from an AP-NNN principle in `knowledge-base/engineering/architecture/principles-register.md` and require a documented exception? Check: name which AP-NNN and why the exception is justified. If the answer is "none, aligned with all principles," this trigger is not hit.
+5. **Teeth-bearing alternatives.** Did the contributor seriously evaluate 2+ concrete alternatives (named libraries, patterns, architectures, or vendors) AND is the rejection rationale load-bearing for future readers who might otherwise revisit the same decision? Check: can you name Option B and Option C with substantive pros/cons without making them up?
+
+If **zero triggers** are hit, use the terse shape. If **one or more triggers** are hit, use the rich shape.
+
+The rubric is intentionally asymmetric: a single genuine trigger (e.g., an NFR move or a principle deviation) is load-bearing on its own and justifies the rich shape.
+
+**Pipeline-mode default.** When `soleur:architecture create` runs non-interactively (e.g., inside `soleur:one-shot`), the rubric cannot be asked interactively and the default falls to **terse**. Rich-shape ADRs in pipeline mode require the caller to pass `shape: rich` explicitly in `$ARGUMENTS`. Interactive callers always see the full rubric prompt.
+
+### What NOT to use as a trigger
+
+- **"The decision feels important."** Importance is orthogonal to section count. A terse ADR about a one-line choice can be more consequential than a rich ADR about an eight-way tradeoff.
+- **"There are a lot of stakeholders."** Stakeholder count drives review process, not ADR shape. A terse ADR can capture the outcome of a 10-person review cleanly.
+- **"I want to write a longer ADR."** The 8 sections are not padding opportunities. An 8-section ADR with `None` in Cost/NFR/Principle Alignment is worse than a 3-section ADR — the reader wades through four `None` stanzas before reaching Consequences.
+
+Pick the shape as a whole, not by cherry-picking sections across the two.
+
+## Body Sections — Terse (3 sections)
+
+Use this block when zero rubric triggers are hit. This is the default shape.
+
+```markdown
+# ADR-NNN: [Decision Title]
+
+## Context
+
+[What is the issue that motivates this decision? What forces are at play?]
+
+## Decision
+
+[What is the change we are making? State the decision clearly.]
+
+## Consequences
+
+[What becomes easier or harder as a result of this decision?
+Include both positive and negative consequences.]
+```
+
+## Body Sections — Rich (8 sections)
+
+Use this block when one or more rubric triggers are hit.
+
+```markdown
+# ADR-NNN: [Decision Title]
+
+## Context
+
+[What is the issue that motivates this decision? What forces are at play?]
+
+## Considered Options
+
+[List options evaluated with pros, cons, and links to tentative C4 model changes.
+
+- **Option A: [name]** — [brief description]. Pros: [...]. Cons: [...].
+- **Option B: [name]** — [brief description]. Pros: [...]. Cons: [...].
+- **Option C: [name]** — [brief description]. Pros: [...]. Cons: [...].]
+
+## Decision
+
+[What is the change we are making? State the decision clearly and
+reference which option was chosen from the list above.]
+
+## Consequences
+
+[What becomes easier or harder as a result of this decision?
+Include both positive and negative consequences.]
+
+## Cost Impacts
+
+[How much is this change planning to increase or reduce costs?
+Include new service subscriptions, infrastructure changes, API usage,
+and any savings from replacing existing services. Use "None" if no
+cost impact. Reference knowledge-base/operations/expenses.md for
+current cost baseline.]
+
+## NFR Impacts
+
+[Which non-functional requirements does this decision affect?
+Reference NFR IDs from knowledge-base/engineering/architecture/nfr-register.md.
+Use "None" if no NFR impact.
+
+Example: "Improves NFR-026 (Encryption In-Transit) from Partial to Implemented.
+No impact on NFR-008 (Low Latency) — additional TLS termination handled by Cloudflare."]
+
+## Principle Alignment
+
+[Which architectural principles does this decision align with or deviate from?
+Reference principle IDs from knowledge-base/engineering/architecture/principles-register.md.
+Use "None" if no principle impact.
+
+Format: AP-NNN (Title): Aligned | Deviation | N/A — brief note
+
+Example: "AP-001 (Terraform-only): Aligned — new infrastructure uses Terraform.
+AP-008 (Doppler secrets): Deviation — uses .env file for local-only dev secret. Exception documented."]
+
+## Diagram
+
+[Optional Mermaid diagram illustrating the decision.
+Use C4 syntax (C4Context, C4Container, C4Component) for architecture diagrams.
+Omit this section entirely if no diagram is informative — do not leave a "None" stub.]
+```
+
+## Naming Convention
+
+Files are named: `ADR-NNN-kebab-case-title.md`
+
+Examples:
+
+- `ADR-001-use-mermaid-for-diagrams.md`
+- `ADR-002-pwa-first-architecture.md`
+- `ADR-003-byok-key-storage.md`
+
+## Status Lifecycle
+
+Two states only:
+
+- **active** — current truth, this decision applies
+- **superseded** — replaced by a newer ADR (must include `superseded-by` field linking to the replacement)