@arbiterforge/ca-pi 0.19.0 → 0.20.0

package/README.md

@@ -10,7 +10,7 @@ and durable project context. You decide. codeArbiter enforces.
 <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-d97757">
 <img alt="Codex plugin" src="https://img.shields.io/badge/OpenAI_Codex-plugin-10a37f">
 <img alt="Pi Feature Forge preview" src="https://img.shields.io/badge/ca--pi-Feature_Forge_preview-d97757">
-<img alt="version 3.0.0" src="https://img.shields.io/badge/version-3.0.0-2b7489">
+<img alt="version 3.1.0" src="https://img.shields.io/badge/version-3.1.0-2b7489">
 <img alt="core lanes" src="https://img.shields.io/badge/core_lanes-18-555">
 <img alt="skills" src="https://img.shields.io/badge/skills-22-555">
 <img alt="agents" src="https://img.shields.io/badge/agents-20-555">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `ca-pi` are documented in this file.
 
 ## [Unreleased]
 
+## [0.20.0] - 2026-10-17
+
+### Added
+
+- SMARTS is now the six-lens design-quality rubric for material engineering solution choices, not only architectural variance. Workflows pick a depth (scan, comparison or delegated decision); SMARTS itself grants no approval and is not a command.
+- A fifth verdict, `Unknown`, records missing evidence with its missing observation and whether it is decision-critical. A decision-critical `Unknown` blocks a strong recommendation and the selection of the option that carries it, and never stands in for user approval, a prerequisite or security authority. The engine validates the `smarts-plan-method/0.2.0` record while historical `0.1.0` receipts keep their four-verdict contract.
+- SMARTS runs only where a material choice exists: brainstorming compares approaches when two or more are materially plausible (a single approach gets one line and no table), the `/feature` small lane scans only a material choice, `/fix` compares remediation strategies only after root cause, and refactor compares only distinct strategies. Writing-plans routes undecided design choices back to brainstorming, and verification checks the change against a recorded rationale for material invalidation only.
+- Specs carry a concise SMARTS design rationale (`SEC-SMARTS`), and the per-lens historical detail loads lazily from `includes/smarts/lenses.md`.
+
 ## [0.19.0] - 2026-10-14
 
 ### Changed

package/plugins/ca-pi/SPRINT.md

@@ -48,6 +48,7 @@ The initial request bounds the work; it does **not** grant arbitrary future scop
 Send the selected plan to `subagent-driven-development` with no artificial per-batch human pause. It reads compact task records, selects actual dependency-clean work, and implements or delegates coherent units. Use TDD where behavior changes benefit from test-first work. Tests, review, and evidence belong to their actual subject and risk; do not require a fixed number of reviewers or rerun them because a receipt ID changed.
 
 **Deciding on behalf of the sprint:** use the user's intent and priorities to choose reversible implementation methods. Use SMARTS when a genuinely difficult trade-off warrants it, not as a six-lens tax on every step. Record material decisions in `.codearbiter/sprint-log.md` with reason and any meaningful uncertainty. A changed method, verification runner, or task decomposition within the agreed outcome is ordinary typed plan maintenance with a short reason, not a new user grant. A materially different product outcome is a question for the actual owner.
+Per `<plugin-root>/includes/smarts/core.md`, an `Unknown` cell names its missing observation and whether it is decision-critical; an `Unknown` cannot bypass a hard gate or manufacture authority, and never stands in for user approval, a prerequisite or security authority.
 
 For HTML, use receipt-free `task-start`, `task-review` (implementation reported ready), `task-reconcile` (reasoned progress correction), and `accept-scope` (reported implementation `DONE`) as appropriate. These labels **never certify a passing check, independent review, or released artifact**. Preserve applicable test output and state the exact outstanding checks. `eligible` is advisory scheduling; use `verification-status` only when an explicit historical attestation claim is actually needed, never to decide whether ordinary code editing may proceed.
 

package/plugins/ca-pi/agents/grader.md

@@ -80,7 +80,7 @@ Constraints:
 | Testable | ... | ... | ... |
 | Securable | ... | ... | ... |
 
-(Each cell: starts with verdict word — Strong, Adequate, Weak, or Indifferent — followed by brief justification. No hedging adverbs. Specific evidence required, not vague claims.)
+(Each cell: starts with verdict word — Strong, Adequate, Weak, Indifferent, or Unknown — followed by brief justification. An `Unknown` cell names its `missing_observation` and states whether it is `decision_critical`. No hedging adverbs. Specific evidence required, not vague claims.)
 
 ## Lens dominance for this decision
 
@@ -117,7 +117,8 @@ Before returning, verify:
 | Check | Status |
 |---|---|
 | Every SMARTS cell ≤ 25 words | yes / no — [list violating cells if any] |
-| Every cell starts with verdict word (Strong/Adequate/Weak/Indifferent) | yes / no |
+| Every cell starts with verdict word (Strong/Adequate/Weak/Indifferent/Unknown) | yes / no |
+| Every `Unknown` cell names its missing observation and decision-criticality | yes / no |
 | No hedging adverbs used | yes / no — [list occurrences if any] |
 | Recommendation strength is strong, moderate, or tied (not "weak") | yes / no |
 | No vague claims ("industry standard", "widely adopted") | yes / no |
@@ -127,7 +128,7 @@ If any check fails: fix the violation before returning. A non-conformant analysi
 
 ## Strength of Recommendation Levels
 
-- **strong** — multiple dominant lenses align cleanly on one option; non-SMARTS considerations confirm.
+- **strong** — multiple dominant lenses align cleanly on one option; non-SMARTS considerations confirm; and no option carries a decision-critical `Unknown`.
 - **moderate** — dominant lenses align with caveats, or a single lens dominates.
 - **tied** — the analysis produces no preferred option; user judgment is required.
 
@@ -140,7 +141,7 @@ The `decision-variance` skill uses strength to decide how forcefully to present
 Non-negotiable:
 
 1. **Length cap:** each SMARTS cell ≤ 25 words.
-2. **Verdict-first:** each cell starts with `Strong`, `Adequate`, `Weak`, or `Indifferent`.
+2. **Verdict-first:** each cell starts with `Strong`, `Adequate`, `Weak`, `Indifferent`, or `Unknown`. An `Unknown` cell names its `missing_observation` and states whether it is `decision_critical`; a lens that matters but lacks evidence is `Unknown`, never `Indifferent` for missing evidence.
 3. **Justification follows:** ≤ 20 words after the verdict.
 4. **No hedging adverbs:** "potentially," "might," "arguably," "perhaps," "generally," "tends to," "could be," "may" are forbidden.
 5. **Evidence specificity:** vague claims do not count. Cite a specific property of the option, a specific project constraint, or a specific failure mode.

package/plugins/ca-pi/helpers/artifacts/release.json

@@ -6,43 +6,43 @@
   "binaries": {
     "darwin/amd64": {
       "file": "ca-artifact-darwin-amd64",
-      "sha256": "1849b2d8abaa5ef76a4f1682bc75ba2fcf452b55d3c66f7bb6a16b141558438d",
+      "sha256": "ca6dc89a106f4b79eb2ab992eb7617c79742f88eb3d5d9b0444102ecf3f23ed3",
       "native_tested": true
     },
     "darwin/arm64": {
       "file": "ca-artifact-darwin-arm64",
-      "sha256": "7ee24e5ddd330a2b52336470cd28635b7f1ea16a235fd377058952d5696b0e15",
+      "sha256": "04dae5874b003fb5530a460c3d9ce6da8284ca7bbfb886e6b6591d0e2980934d",
       "native_tested": true
     },
     "linux/amd64": {
       "file": "ca-artifact-linux-amd64",
-      "sha256": "1d20e9dfdc663c4f3d82f82cb1df861261304acf439f604f7bddc33a79f6af91",
+      "sha256": "1b2d858cf64e7774cbc2abf8abe7921c5f9fe147fcee796e70dbe38478272847",
       "native_tested": true
     },
     "linux/arm64": {
       "file": "ca-artifact-linux-arm64",
-      "sha256": "94a54eb7e83a4992a4ee78b98b7946d2332e2a007ad7fd4ec14a3e332ad16651",
+      "sha256": "37e592fb61297850b17e2cd6c603a203143940b42b04e7a285f081b0d9d848e5",
       "native_tested": true
     },
     "windows/amd64": {
       "file": "ca-artifact-windows-amd64.exe",
-      "sha256": "d8f0bafd5f1949d93e87fb3cec7222ad9757087e30f7ea06268f148897f5b5a7",
+      "sha256": "4f4b3f4cf0ab7230f9cd577a3310a293007af1126913224c8e6103438aaafc8b",
       "native_tested": true
     },
     "windows/arm64": {
       "file": "ca-artifact-windows-arm64.exe",
-      "sha256": "be36ede70afe3dfc57afcd1ff2f5be5b36134ac383998c10145809bd0b80f459",
+      "sha256": "855bfbd1c628a0b76cfa5bdf7d6ff392fb55e49dba23efb13e2a7a26d9e5ccb4",
       "native_tested": true
     }
   },
   "context_qualification": {
     "darwin/amd64": {
-      "source_commit": "36685a40ab035074be04bb7204618acbb0a2dfdf",
+      "source_commit": "44149055d1ca136e191f79136244f0d3a2b1a461",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38995632892",
-      "binary_sha256": "1849b2d8abaa5ef76a4f1682bc75ba2fcf452b55d3c66f7bb6a16b141558438d",
-      "observation_sha256": "4b2b1f09e54d99fe7e7cc0ca177b80c2ac5d47e6428eddd551453a13ac2b272f",
-      "module_sha256": "91fed16f177e249d082638387a5f6e8d38dcb33604f357e8296b2f0124a4ca2a",
+      "run_id": "39097065693",
+      "binary_sha256": "ca6dc89a106f4b79eb2ab992eb7617c79742f88eb3d5d9b0444102ecf3f23ed3",
+      "observation_sha256": "178ac16ede5052a25eff69597ef2c6ab30439bcfd3d9127a1189e9eaa7a6147e",
+      "module_sha256": "a34f09f52c52145624e87c1d5e3850c822dd1ca54c346c5ad63802f6e5a0d0b3",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -53,12 +53,12 @@
       ]
     },
     "darwin/arm64": {
-      "source_commit": "36685a40ab035074be04bb7204618acbb0a2dfdf",
+      "source_commit": "44149055d1ca136e191f79136244f0d3a2b1a461",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38995632892",
-      "binary_sha256": "7ee24e5ddd330a2b52336470cd28635b7f1ea16a235fd377058952d5696b0e15",
-      "observation_sha256": "3a30a7b8a8d719ac8f261f3c9094bae62a5d9e3db31b565dc401d21486ed48f3",
-      "module_sha256": "91fed16f177e249d082638387a5f6e8d38dcb33604f357e8296b2f0124a4ca2a",
+      "run_id": "39097065693",
+      "binary_sha256": "04dae5874b003fb5530a460c3d9ce6da8284ca7bbfb886e6b6591d0e2980934d",
+      "observation_sha256": "c7a246aafb77097d60704ecae57abcd7a8786078144de3549475684cd93c1fc2",
+      "module_sha256": "a34f09f52c52145624e87c1d5e3850c822dd1ca54c346c5ad63802f6e5a0d0b3",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -69,12 +69,12 @@
       ]
     },
     "linux/amd64": {
-      "source_commit": "36685a40ab035074be04bb7204618acbb0a2dfdf",
+      "source_commit": "44149055d1ca136e191f79136244f0d3a2b1a461",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38995632892",
-      "binary_sha256": "1d20e9dfdc663c4f3d82f82cb1df861261304acf439f604f7bddc33a79f6af91",
-      "observation_sha256": "d977095e8db3aa5bd71fd2db318292d6c6da3aa716b1253ae7ad0fe95780c475",
-      "module_sha256": "91fed16f177e249d082638387a5f6e8d38dcb33604f357e8296b2f0124a4ca2a",
+      "run_id": "39097065693",
+      "binary_sha256": "1b2d858cf64e7774cbc2abf8abe7921c5f9fe147fcee796e70dbe38478272847",
+      "observation_sha256": "f2725ba4c6ef48d36fb92962ef1fc6b00871e057a3234010ab0066a844bf21fd",
+      "module_sha256": "a34f09f52c52145624e87c1d5e3850c822dd1ca54c346c5ad63802f6e5a0d0b3",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -85,12 +85,12 @@
       ]
     },
     "linux/arm64": {
-      "source_commit": "36685a40ab035074be04bb7204618acbb0a2dfdf",
+      "source_commit": "44149055d1ca136e191f79136244f0d3a2b1a461",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38995632892",
-      "binary_sha256": "94a54eb7e83a4992a4ee78b98b7946d2332e2a007ad7fd4ec14a3e332ad16651",
-      "observation_sha256": "24d3bdce7f5044e3c5dda44b0f2a5ccd37bd0821408aa8f62b5b329aacd8e98b",
-      "module_sha256": "91fed16f177e249d082638387a5f6e8d38dcb33604f357e8296b2f0124a4ca2a",
+      "run_id": "39097065693",
+      "binary_sha256": "37e592fb61297850b17e2cd6c603a203143940b42b04e7a285f081b0d9d848e5",
+      "observation_sha256": "3c0cae7073c8e7cf7ba6e40da4a04fad9d623a87914e44dac3b6e329d0dd020a",
+      "module_sha256": "a34f09f52c52145624e87c1d5e3850c822dd1ca54c346c5ad63802f6e5a0d0b3",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -101,12 +101,12 @@
       ]
     },
     "windows/amd64": {
-      "source_commit": "36685a40ab035074be04bb7204618acbb0a2dfdf",
+      "source_commit": "44149055d1ca136e191f79136244f0d3a2b1a461",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38995632892",
-      "binary_sha256": "d8f0bafd5f1949d93e87fb3cec7222ad9757087e30f7ea06268f148897f5b5a7",
-      "observation_sha256": "eb42182fceca7bdb85924d382a8cf3917fb49b9c2a8a32ccd563a3acab245547",
-      "module_sha256": "91fed16f177e249d082638387a5f6e8d38dcb33604f357e8296b2f0124a4ca2a",
+      "run_id": "39097065693",
+      "binary_sha256": "4f4b3f4cf0ab7230f9cd577a3310a293007af1126913224c8e6103438aaafc8b",
+      "observation_sha256": "3ad94468cbd6eaf40500b525859923feaa5fbb120f91b3aadcc08b08ae837fc9",
+      "module_sha256": "a34f09f52c52145624e87c1d5e3850c822dd1ca54c346c5ad63802f6e5a0d0b3",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",
@@ -117,12 +117,12 @@
       ]
     },
     "windows/arm64": {
-      "source_commit": "36685a40ab035074be04bb7204618acbb0a2dfdf",
+      "source_commit": "44149055d1ca136e191f79136244f0d3a2b1a461",
       "workflow": ".github/workflows/ci.yml",
-      "run_id": "38995632892",
-      "binary_sha256": "be36ede70afe3dfc57afcd1ff2f5be5b36134ac383998c10145809bd0b80f459",
-      "observation_sha256": "12b1ba42509dd791bebf60df616608e7dbf50359175f90a3cf7a857c3c82cad8",
-      "module_sha256": "91fed16f177e249d082638387a5f6e8d38dcb33604f357e8296b2f0124a4ca2a",
+      "run_id": "39097065693",
+      "binary_sha256": "855bfbd1c628a0b76cfa5bdf7d6ff392fb55e49dba23efb13e2a7a26d9e5ccb4",
+      "observation_sha256": "8f594d61907c66818ddae106e859c6ba437713ca4c049468425558751ddb9697",
+      "module_sha256": "a34f09f52c52145624e87c1d5e3850c822dd1ca54c346c5ad63802f6e5a0d0b3",
       "native_cases": [
         "TestContextBoundedRender",
         "TestContextDocumentContract",

package/plugins/ca-pi/hooks/_host.py

@@ -11,7 +11,7 @@ import hostapi  # noqa: E402
 class PiHost(hostapi.Host):
     name = "pi"
     adapter_name = "@arbiterforge/ca-pi"
-    adapter_version = "0.19.0"
+    adapter_version = "0.20.0"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

package/plugins/ca-pi/hooks/hostapi.py

@@ -313,7 +313,7 @@ class Host:
 
     name = "claude"
     adapter_name = "ca"
-    adapter_version = "3.0.0"
+    adapter_version = "3.1.0"
 
     # Update-notifier descriptor. Each independently versioned host overrides
     # these three values in its per-plugin _host.py. Keeping the target,

package/plugins/ca-pi/includes/artifacts.md

@@ -34,6 +34,11 @@ authorized work. Do not invent criteria, decisions or test results to pass
 validation. A changed outcome goes to the actual decision owner; in-scope
 methods and task decomposition can be updated with a reason.
 
+A spec's SMARTS design rationale is stored in its existing `approach` record, bound
+`decisions` records and one `SEC-SMARTS` section, as defined once in
+`<plugin-root>/includes/smarts/core.md` (Design rationale record); a legacy Markdown spec
+uses its one `## SMARTS design rationale` section instead.
+
 Query an operation-specific `schema` only when its request shape is unknown;
 reuse known shapes for subsequent calls instead of querying on every read.
 Do not preload the entire schema. The packaged bridge invokes the verified native

package/plugins/ca-pi/includes/smarts/core.md

@@ -1,10 +1,23 @@
-# SMARTS — lenses, cell rules, strength
+# SMARTS — design-quality rubric
 
-The standardized evaluation for architectural variances. Apply the six lenses evenhandedly to every
-option. This is the project's framework; do not substitute another. This `core` file is everything the
-scoring path needs (decision-variance, the grader, the decision-challenger, and `/sprint` autonomous
-scoring). The append-only **decision-log entry format** lives separately in
-[`decision-log-format.md`](decision-log-format.md) — load it only when writing a log line.
+SMARTS is codeArbiter's six-lens design-quality rubric for material engineering solution choices.
+Workflow owners decide when a choice needs a scan, a full comparison, or delegated autonomous
+handling; SMARTS itself does not grant authority. Architectural variance (decision-variance, the
+grader, the decision-challenger) is one consumer of the rubric, not the definition of the framework.
+Apply the six lenses evenhandedly to every option; this is the project's framework, do not substitute
+another. This `core` file is everything a routine evaluation needs; the per-lens detail in [`lenses.md`](lenses.md)
+is loaded only when a case named under the lenses below arises. The append-only **decision-log entry
+format** lives separately in [`decision-log-format.md`](decision-log-format.md) — load it only when
+writing a log line.
+
+## Evaluation depths
+
+1. **Scan** — a lightweight six-lens fitness pass when a choice is material but does not need the full table: name the material strengths, weaknesses, unknowns and decisive lenses; no full table is required in user-visible output.
+2. **Comparison** — the full option-by-option table, when two or more materially plausible approaches exist, when the user explicitly asks for a full SMARTS read, or when reconciliation or arbitration requires it.
+3. **Delegated decision** — a requested `/sprint` choosing a reversible in-scope method on the user's behalf and logging its reason in `.codearbiter/sprint-log.md`; no separate method grant is required.
+
+All three depths use the semantics in this file; they differ in presentation, persistence and
+decision authority, not in what the acronym means.
 
 ## Step 0 — recorded-intent check (before any lens is scored; ADR-0025)
 
@@ -37,8 +50,27 @@ Three outcomes:
 Fail-soft: an absent `plans/` or `decisions/` directory is not a gap to surface and never a STOP —
 record `intent: silent — no decomposition record` and proceed.
 
+## Context envelope
+
+Before judging a material choice, establish only the context that makes the lenses meaningful:
+
+- **decision** — the actual choice being made, stated when the request leaves it implicit.
+- **scope/horizon** — the bounded system and planning horizon, when they change a verdict.
+- **scale expectation** — only when scale could differentiate the options.
+- **failure/availability expectation** — only when failure behavior could differentiate the options.
+- **security/trust boundary** — only when it bears on Securable.
+- **non-SMARTS constraints** — cost, schedule, team skill, vendor or stakeholder constraints, only when they materially affect the recommendation.
+
+The envelope is scope-sized and fail-soft. No dimension is required for every choice, and it creates
+no new project or configuration file: existing project context, the active spec, explicit user
+steering and relevant recorded decisions supply the evidence when available.
+
 ## The six lenses
 
+The summaries below settle most verdicts. Load the per-lens reference
+[`lenses.md`](lenses.md) only when a verdict turns on a consideration these summaries do not
+settle, or when the user asks for a full SMARTS read — never for a routine scan.
+
 - **Scalable** — supports growth in users, data, throughput, geography without an architectural rewrite. Trap: over-engineering for scale that never arrives, or under-engineering for scale that's on the roadmap.
 - **Maintainable** — can be understood, modified, and extended later (including by agents) without prohibitive effort. Standard patterns over bespoke abstractions; mind the refactoring blast radius and eventual hand-off.
 - **Available** — reachable and functional when needed, including under partial failure. Watch single points of failure, bundled-dependency failure, recovery time. Do not conflate availability with high availability.
@@ -46,33 +78,77 @@ record `intent: silent — no decomposition record` and proceed.
 - **Testable** — validated by deterministic, fast tests that cover real failure modes. Unit + integration + contract; mind mockability and test-data isolation. "Tests later" is a Weak verdict.
 - **Securable** — enables the project's security posture (per `<project-root>/.codearbiter/security-controls.md`) without retrofit. Authentication, authorization, audit, secret management, attack surface, default-deny stance, supply-chain integrity.
 
+## Verdicts
+
+Every evaluated lens takes exactly one verdict:
+
+- **Strong** — performs well for the stated context.
+- **Adequate** — acceptable for the stated context.
+- **Weak** — materially poor for the stated context.
+- **Indifferent** — evidence shows the lens does not materially differentiate the options at the stated context and horizon. If any option marks a lens `Indifferent`, every option marks it `Indifferent`. In a single-option scan there is nothing to differentiate, so Indifferent means the lens is not material to this choice at the stated context; a lens that matters but lacks evidence is `Unknown`, never `Indifferent`.
+- **Unknown** — the evidence needed to judge the lens is missing, contradictory or not yet established. Every Unknown names its missing observation (`missing_observation`) and states whether it is decision-critical (`decision_critical`: true when that observation could change the selected option); no other verdict carries those fields.
+
+`Unknown` is not neutral: never treat it as `Indifferent`, `Adequate` or a pass, and never map it to
+one. A recommendation may stand with a non-critical Unknown only when the output names the missing
+observation and why it does not control the decision. A decision-critical Unknown blocks a `strong`
+recommendation, blocks selecting the option that carries it, and is surfaced before any irreversible
+or authority-bearing choice. A non-critical Unknown never shields a dominated option: on the selected
+option it is no better than the other option's verdict on that lens, and strictly worse than a compared
+`Strong`.
+
 ## Cell rules (hard)
 
 Each SMARTS cell is a constraint, not a guideline. A non-conformant cell is rejected.
 
 1. **Length cap** — at most 25 words per cell.
-2. **Verdict-first** — every cell opens with one verdict word: `Strong` (performs well), `Adequate` (acceptable), `Weak` (poor), `Indifferent` (this lens does not differentiate the options at the current scale).
-3. **Justification follows** — at most 20 words after the verdict.
-4. **No hedging adverbs** — forbidden: potentially, might, arguably, perhaps, generally, tends to, could be, may. If genuinely uncertain, the verdict is `Indifferent`.
+2. **Verdict-first** — every cell opens with one verdict word: `Strong`, `Adequate`, `Weak`, `Indifferent` or `Unknown`.
+3. **Justification follows** — at most 20 words after the verdict; an `Unknown` justification names the missing observation and whether it is decision-critical.
+4. **No hedging adverbs** — forbidden: potentially, might, arguably, perhaps, generally, tends to, could be, may. If genuinely uncertain, the verdict is `Unknown` with its missing observation.
 5. **Evidence specificity** — "industry standard," "best practice," "widely adopted" are not evidence. Cite a specific property of the option, a specific project constraint, or a specific failure mode.
 
+## Conflicting lenses and priority
+
+SMARTS stays qualitative: never count `Strong` cells, assign weights, sum or compute percentages to pick a winner.
+Per-lens dominance — one option no worse on every lens and better on at least one — is an ordinal
+comparison, not a score. When lenses conflict, apply preference evidence in this order:
+
+1. explicit current user or approved-spec priority;
+2. explicit project priority already recorded in project context or an accepted decision;
+3. relevant prior-decision precedent, labelled as precedent, not authority;
+4. no assumed priority.
+
+Absent explicit priority evidence, a tied comparison stays tied.
+
 ## Strength of recommendation
 
 Every recommendation carries exactly one strength label:
 
-- **strong** — multiple dominant lenses align cleanly on one option; non-SMARTS factors confirm.
+- **strong** — dominant lenses align cleanly on one option, non-SMARTS factors confirm, and no option carries a decision-critical Unknown.
 - **moderate** — dominant lenses align with caveats, or a single lens dominates.
 - **tied** — no preferred option emerges. A legitimate output: "This is a coin flip under SMARTS — your call."
 
-There is no `weak` level — a slight edge is `moderate`. When lenses conflict with no winner, state it
-plainly, surface which lens the user has emphasized in prior decisions as input, and mark `tied`.
-The `Precedent:` line under each table (decision-variance Phase 3) is how that emphasis is surfaced
-systematically: 1–3 most-similar prior decisions by ID plus the observed lens pattern, or
-`Precedent: none on record` when history is thin — never an invented pattern.
+There is no `weak` level — a slight edge is `moderate`. The `Precedent:` line under each table
+(decision-variance Phase 3) surfaces step 3 of the priority order: 1–3 most-similar prior decisions by
+ID plus the observed lens pattern, or `Precedent: none on record` when history is thin — never an
+invented pattern, and never authority on its own.
 
 SMARTS does not cover cost, time-to-market, team-skill fit, vendor lock-in, or political
-acceptability. When these matter, surface them as **non-SMARTS considerations** alongside the table;
-they supplement, never replace, the analysis.
+acceptability. When these matter, surface them as **non-SMARTS considerations** alongside the
+analysis; they supplement, never replace it, and never become a seventh lens.
+
+## Design rationale record
+
+An approved full-lane spec keeps a concise SMARTS design rationale; it is design evidence, not a
+source of execution authority. For a typed HTML spec, write it through the existing mutation
+operations with this convention, with no spec-schema change:
+
+- the chosen approach and its trade-off live in the existing `approach` record (`choice`, `tradeoff`);
+- a `decisions` record carries each material decision the SMARTS pass settled, and `approach.binding_decision_refs` cites it;
+- one `sections` record with the fixed id `SEC-SMARTS` (title "SMARTS design rationale") holds one block each for: alternatives considered or the single-option statement; decisive lenses; material Weak and Unknown observations, each Unknown with its missing observation and whether it is decision-critical; load-bearing assumptions; non-SMARTS considerations; and priority evidence when one influenced the recommendation.
+
+Read the rationale back with the existing read operations; never hand-edit or parse rendered HTML.
+A legacy Markdown spec keeps the rationale in one stable `## SMARTS design rationale` section that
+carries the same parts in the same order.
 
 ## Worked example
 

package/plugins/ca-pi/includes/smarts/lenses.md

@@ -0,0 +1,115 @@
+# SMARTS — lens reference (lazy)
+
+Per-lens detail behind the one-line summaries in [`core.md`](core.md). `core.md` owns the role,
+verdicts, cell rules and strength; this file only deepens what each lens asks. Load it only under
+the condition `core.md` states — never for a routine scan the summaries already settle.
+
+Each lens lists the question it answers, the considerations that usually decide it, the traps
+that produce a wrong verdict, and the observation that settles an `Unknown` on it (the
+`missing_observation` an Unknown cell names).
+
+## Scalable
+
+**Question:** does the option support growth in users, data, throughput or geography without an
+architectural rewrite?
+
+**Considerations:**
+- User scale across the stated horizon — prototype, pilot, production.
+- Data volume and its growth rate, including retained history and logs.
+- Throughput shape: bursty versus steady, and the peak the design must absorb.
+- Geographic spread: single region now, multi-region on the roadmap or not.
+
+**Traps:** over-engineering for scale that never arrives; under-engineering for scale that is on
+the roadmap; confusing performance (one request is fast) with scalability (many requests stay fast).
+
+**Settles an Unknown:** the expected load or data volume at the stated horizon, or a measurement
+of the option at that load.
+
+## Maintainable
+
+**Question:** can the system be understood, modified and extended later — including by agents —
+without prohibitive effort?
+
+**Considerations:**
+- Comprehensibility for the next contributor, human or agent, without reading internals.
+- Standard patterns versus bespoke abstractions.
+- Documentation the option obliges someone to keep current.
+- Refactoring blast radius when the option changes.
+- Onboarding and hand-off cost to whoever owns the code next.
+
+**Traps:** treating maintainability as one engineer's concern; underestimating the cost of a
+bespoke pattern when agents write most of the code; ignoring the eventual hand-off.
+
+**Settles an Unknown:** who maintains the code at the stated horizon, and whether the pattern
+already exists in the codebase.
+
+## Available
+
+**Question:** is the system reachable and functional when needed, including under partial failure?
+
+**Considerations:**
+- Single points of failure the option introduces or removes.
+- Failure of a bundled or external dependency, and what keeps working.
+- Disconnected or degraded operation requirements.
+- Time to recover from the common failure modes.
+- The downtime the caller can actually accept.
+
+**Traps:** conflating availability with high availability; designing for high availability the
+project does not require; ignoring partial-availability states.
+
+**Settles an Unknown:** the stated downtime tolerance, or how the option behaves when its
+dependency is unreachable.
+
+## Reliable
+
+**Question:** does the option produce correct, predictable, durable outcomes?
+
+**Considerations:**
+- Atomicity and durability where they matter — the decision log, audit events, receipts.
+- Idempotency of retried operations.
+- State consistency across components.
+- Recovery from failure without corruption.
+- Reproducibility of builds, deployments and recorded evidence.
+
+**Traps:** assuming the database or framework handles it without checking; underestimating the
+reliability cost of distribution; ignoring long-tail durability.
+
+**Settles an Unknown:** the failure the option must survive, and evidence of its behavior under it.
+
+## Testable
+
+**Question:** can the option be validated by deterministic, fast tests that cover meaningful
+failure modes?
+
+**Considerations:**
+- Unit testability of the parts the option introduces.
+- Integration and contract testing between components.
+- Test data generation and isolation.
+- Whether the real failure modes can be reproduced in a test, not just the happy path.
+- The boundary between a throwaway spike and a test that must hold.
+
+**Traps:** patterns that resist mocking or isolation; ignoring the cost of test infrastructure;
+"tests later" for foundational components.
+
+**Settles an Unknown:** whether a deterministic test can reproduce the failure mode the option
+must handle.
+
+## Securable
+
+**Question:** does the option enable the project's security posture — as defined in
+`<project-root>/.codearbiter/security-controls.md` — without retrofit?
+
+**Considerations:**
+- Authentication boundary: who the actor is.
+- Authorization boundary: what the actor may do.
+- Audit boundary: what is recorded, and whether it can be trusted.
+- Secret handling.
+- Attack surface: every bundled component and exposed input.
+- Default-deny versus default-allow stance.
+- Supply-chain integrity: provenance, licenses, signatures.
+
+**Traps:** bolting security on after the architecture is set; confusing compliance with security;
+underestimating the hardening burden of bundled components.
+
+**Settles an Unknown:** the trust boundary the option crosses, and the control
+`security-controls.md` requires there.

package/plugins/ca-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",

package/plugins/ca-pi/routines/brainstorming/SKILL.md

@@ -45,6 +45,12 @@ State the problem, observable result, intended scope and explicit exclusions. Re
 
 Consider genuine trade-offs where they matter, recommend a suitable approach and explain why. Do not manufacture straw alternatives. Reversible implementation methods remain agent-owned within the agreed outcome. Ask for a user ruling on an unresolved, consequential product choice, not on every viable implementation detail.
 
+**Never manufacture alternatives.** When only one sane approach exists, say so in one line and say why; that path runs no SMARTS comparison and adds no SMARTS table.
+
+**SMARTS on a material choice.** Only when two or more materially plausible approaches exist, run a SMARTS comparison per `<plugin-root>/includes/smarts/core.md` inline before recommending one. Bound it to the context-envelope dimensions that could differentiate the approaches, mark missing evidence `Unknown` with its missing observation, and surface a decision-critical `Unknown` before selecting. If every candidate carries one, pause the selection until the missing observation is resolved or the user rules. The comparison dispatches no grader or scout, performs no bulk read of `plans/` or `decisions/`, and loads `<plugin-root>/includes/smarts/lenses.md` only when a verdict turns on a consideration the core summaries do not settle. Name cost, schedule, team-skill, vendor or stakeholder constraints alongside the result; they never become a seventh lens. Apply the core's priority order when lenses conflict; a tie without explicit priority evidence goes to the user. An explicit request for a full SMARTS read changes only the presentation depth — the full option-by-option table — with no new command and no change to decision authority.
+
+**Record the rationale.** When the comparison ran, write the decisive lenses, any `Unknown` with its missing observation, the non-SMARTS constraints and the selection reason into the spec's `SEC-SMARTS` section, or the `## SMARTS design rationale` section of a Markdown spec. A single-approach choice records only its one-line statement there.
+
 Review applicable ADRs and explicit exclusions. A real conflicting architecture decision goes to its owner. Mentioning a protected file does not by itself restart the entire feature interview.
 
 ## Phase 3 - Make acceptance observable

package/plugins/ca-pi/routines/debug/SKILL.md

@@ -353,6 +353,7 @@ reported as an executed pass.
 - MUST consider mundane environmental, configuration, and dependency mechanisms
   where plausible, without inventing one to meet a count.
 - MUST NOT promote INCONCLUSIVE evidence to CONFIRMED or REFUTED without a cited source.
+- MUST NOT apply SMARTS to hypothesis ranking or root-cause confirmation — diagnosis is evidence-led; a remediation strategy choice belongs to `/fix` after root cause.
 - MUST record capture limits and relevant source/runtime identity; partial
   observation and stale evidence cannot silently establish a cause.
 - MUST NOT repeat an unchanged read without a new discriminator or changed context.

package/plugins/ca-pi/routines/decision-variance/references/analysis.md

@@ -106,8 +106,11 @@ both governing sources and their disagreement; do not invent an artifact/scaffol
 variance, resolution or scoring inputs where that comparison actually agrees.
 
 The SMARTS table follows `<plugin-root>/includes/smarts/core.md` exactly: six lenses, verdict-first cells (Strong /
-Adequate / Weak / Indifferent), the length cap, no hedging adverbs, evidence specificity. The
-recommendation carries one strength label — strong / moderate / tied.
+Adequate / Weak / Indifferent / Unknown), the length cap, no hedging adverbs, evidence specificity.
+An `Unknown` cell names its `missing_observation` and states whether it is `decision_critical`; a
+lens that matters but lacks evidence is `Unknown`, never `Indifferent` for missing evidence. The
+recommendation carries one strength label — strong / moderate / tied — and is never `strong` while
+any option carries a decision-critical `Unknown`.
 
 **Precedent row.** Before writing the tables, scan the existing decision log once: tally which
 lenses prior resolutions turned on (which lens was decisive, which way ties broke) and note

package/plugins/ca-pi/routines/refactor/SKILL.md

@@ -84,6 +84,12 @@ Gate: either "No new seams", or failing seam tests with all pre-existing tests s
 
 ## Phase 4 — Implementation · gate: BLOCK
 
+**Strategy choice (conditional).** Only when materially distinct restructuring strategies exist (for
+example, extract-and-delegate versus move-and-rename), and only after the Phase 1 surface table and
+the Phase 2 parity proof are settled, run a SMARTS comparison per
+`<plugin-root>/includes/smarts/core.md` inline to choose between them. The choice never widens the
+surface table or relaxes a parity or coverage gate. One evident strategy gets no SMARTS table.
+
 Apply the restructure with zero behavior change, to the conventions in `coding-standards.md`. Confine every edit to the surface table. Acceptable edits: rename symbols (with consumer updates); extract or inline functions and methods; move symbols between files; replace an internal implementation with an equivalent one; collapse or split modules where the public interface is preserved.
 
 Unacceptable inside a refactor: adding a behavior, branch, error path, or side effect; changing the value any public method returns for any pre-existing input; adding a public method beyond a Phase 3 seam; changing observable order of operations (event emission, logging, IO). Classify the resulting staged diff against `commit-gate` classification criteria — a diff that classifies as `feat` is not a refactor; halt and route to `tdd`.

package/plugins/ca-pi/routines/subagent-driven-development/SKILL.md

@@ -48,6 +48,14 @@ If implementation reveals a better in-scope method, update task steps, runner, o
 
 Compare the implementation to the source criteria: what is required, what changed, what is missing, and what behavior a passing test actually covers. Run the planned applicable test or a narrower verified equivalent through the existing **host-governed execution tool**. Record the command, working directory, outcome, and limitations. A command-level pass is not invented named-test proof. A new failure or a skipped/unknown result cannot be masked by an earlier pass.
 
+**Design-rationale drift.** When the spec records a SMARTS design rationale (`SEC-SMARTS`, or a
+Markdown spec's `## SMARTS design rationale` section), check the change against it for material
+invalidation only: a load-bearing assumption the change contradicts, a `Weak` or `Unknown` the
+rationale chose to avoid that the change newly introduces, or a materially different approach than
+the one selected. Do not re-run SMARTS or grade the implementation. A mismatch returns the task to
+step 2 with the contradicted rationale cited, or routes the design question back to `brainstorming`;
+never pick a replacement approach inside review.
+
 A failing check is a reason to repair, investigate, or mark verification pending, **not permission to claim it passed** and not a ban on unrelated implementation. Rerun affected checks after a correction. If the same approach fails repeatedly without new information, diagnose differently or record a bounded blocked task and continue unrelated work.
 
 Review the combined relevant diff when risk or change size warrants it. Use a specialist reviewer only for an actual security/dependency/migration concern or an explicit policy requirement. Avoid duplicate security reviews and blanket per-task spec/quality fleets. Retain useful findings; revisit affected conclusions only when relevant code, requirements, supporting evidence, or the previously reviewed subject changes. A new receipt ID by itself is not an impact.

package/plugins/ca-pi/routines/writing-plans/SKILL.md

@@ -42,6 +42,14 @@ for useful implementation and review, not a compulsory two-to-five-minute limit.
 A small related change does not need its own author/reviewer lifecycle. Split
 work when it has separate outcomes, dependencies, or independently useful progress.
 
+**Design-drift guard.** Decomposition splits decided work; it never designs. If splitting surfaces a
+material solution choice the spec does not decide — two or more materially plausible approaches the
+spec leaves open, or a step that would contradict the spec's recorded SMARTS rationale — STOP and
+never pick, score or SMARTS-evaluate it here. Route the undecided choice back to the owning design
+workflow, `brainstorming` (`<plugin-root>/routines/brainstorming/SKILL.md`), and resume planning only
+once the spec records the decision. A choice the spec already decides, or a trivial local
+implementation detail with no material solution choice, is not drift.
+
 Use real repository commands or an explicitly described observable check. A test
 file or case that this task will create may not exist yet. An unsupported named
 result parser is not a reason to reject the plan or invent test outcomes; a

package/plugins/ca-pi/skills/ca-debug/SKILL.md

@@ -353,6 +353,7 @@ reported as an executed pass.
 - MUST consider mundane environmental, configuration, and dependency mechanisms
   where plausible, without inventing one to meet a count.
 - MUST NOT promote INCONCLUSIVE evidence to CONFIRMED or REFUTED without a cited source.
+- MUST NOT apply SMARTS to hypothesis ranking or root-cause confirmation — diagnosis is evidence-led; a remediation strategy choice belongs to `/fix` after root cause.
 - MUST record capture limits and relevant source/runtime identity; partial
   observation and stale evidence cannot silently establish a cause.
 - MUST NOT repeat an unchanged read without a new discriminator or changed context.

package/plugins/ca-pi/skills/ca-feature/SKILL.md

@@ -67,6 +67,13 @@ judged against `$ARGUMENTS` and a quick look at the code, never assumed:
 - no new dependency, endpoint, command, or configuration surface;
 - the behavior change is expressible as 1–3 concrete, individually testable acceptance criteria.
 
+**Small-lane SMARTS.** Only when the change involves a material solution choice — two or more
+materially plausible ways to build it — run a SMARTS scan per `<plugin-root>/includes/smarts/core.md`,
+inline with no grader or scout, and state its one-line result with the mini-spec. Otherwise state
+`SMARTS: no material solution choice` and continue; that path adds no SMARTS table and no extra
+artifact. If the scan shows that the better approach would violate any small-lane criterion above,
+route to the **full lane**.
+
 **Small lane:** state the mini-spec inline (the 1–3 criteria). Unless the user requested a pause or a real consequential question remains, proceed without a second permission reply. Append one line to `<project-root>/.codearbiter/triage.log`
 (append-only, `>>`):
 

package/plugins/ca-pi/skills/ca-fix/SKILL.md

@@ -44,6 +44,12 @@ new behavior:
    current state for the precise reason the bug causes (not an unrelated error).
 4. **Confirm it's red for the right reason** — the failure message matches the described defect.
 
+**Remediation strategy (conditional).** Only after step 2 has confirmed the root cause, and only when
+materially distinct remediation strategies exist (for example, a local guard versus a contract
+change), run a SMARTS comparison per `<plugin-root>/includes/smarts/core.md` inline before any fix
+code. A single obvious fix gets no SMARTS table. SMARTS never ranks hypotheses or confirms the cause;
+diagnosis stays evidence-led in `debug`.
+
 Only then does `tdd` proceed: minimal fix to green, then the remaining `tdd` gates. When delegating,
 select `backend-author`, `frontend-author`, or `infra-author` by where the bug lives. If
 the defect cannot be pinned by a failing test, STOP and surface the question.

package/plugins/ca-pi/skills/ca-refactor/SKILL.md

@@ -84,6 +84,12 @@ Gate: either "No new seams", or failing seam tests with all pre-existing tests s
 
 ## Phase 4 — Implementation · gate: BLOCK
 
+**Strategy choice (conditional).** Only when materially distinct restructuring strategies exist (for
+example, extract-and-delegate versus move-and-rename), and only after the Phase 1 surface table and
+the Phase 2 parity proof are settled, run a SMARTS comparison per
+`<plugin-root>/includes/smarts/core.md` inline to choose between them. The choice never widens the
+surface table or relaxes a parity or coverage gate. One evident strategy gets no SMARTS table.
+
 Apply the restructure with zero behavior change, to the conventions in `coding-standards.md`. Confine every edit to the surface table. Acceptable edits: rename symbols (with consumer updates); extract or inline functions and methods; move symbols between files; replace an internal implementation with an equivalent one; collapse or split modules where the public interface is preserved.
 
 Unacceptable inside a refactor: adding a behavior, branch, error path, or side effect; changing the value any public method returns for any pre-existing input; adding a public method beyond a Phase 3 seam; changing observable order of operations (event emission, logging, IO). Classify the resulting staged diff against `commit-gate` classification criteria — a diff that classifies as `feat` is not a refactor; halt and route to `tdd`.