@isaacriehm/cairn-core 0.1.0

package/templates/.cairn/config/stub-patterns.yaml

@@ -0,0 +1,231 @@
+# Layer A — mechanical stub-pattern catalog.
+#
+# Initial seed (~30 patterns). Grows additively via the /oops dialog
+# (PRIMER §10 Layer A; L25). Patterns NEVER added by typed CLI command.
+#
+# Each pattern is language-tagged. The orchestrator filters patterns by the
+# stack profile's language list before running. False-positive cases are not
+# silenced by editing this file — they're handled per-failure via the /oops
+# dialog (PRIMER §11 anti-pattern: do NOT disable sensors to make diffs pass).
+#
+# Format:
+#   - id: <stable identifier; cited in failure messages>
+#     languages: [<typescript|javascript|python|ruby|go|rust|sql>]
+#     description: <one-liner shown in remediation prompt>
+#     regex: <ECMAScript regex; multiline-mode>
+#     severity: hard | soft
+#
+# Severity:
+#   - hard: any match fails the run unconditionally
+#   - soft: match contributes to attestation cross-check (a `stubs_introduced: 0`
+#     claim becomes a lie if any soft pattern matches)
+
+version: 1
+
+patterns:
+
+  # ── TODO / FIXME / XXX / HACK markers ───────────────────────────────────
+  - id: todo-marker
+    languages: [typescript, javascript, python, ruby, go, rust]
+    description: "TODO/FIXME/XXX/HACK comment — flag as introduced-debt."
+    regex: '(?://|#|/\*)\s*(TODO|FIXME|XXX|HACK)\b'
+    severity: soft
+
+  # ── "not implemented" throws ─────────────────────────────────────────────
+  - id: throw-not-implemented
+    languages: [typescript, javascript]
+    description: "throw new Error('not implemented') — empty stub disguised as code."
+    regex: 'throw\s+new\s+Error\s*\(\s*[''"`][^''"`]*not[\s_]?implemented[^''"`]*[''"`]\s*\)'
+    severity: hard
+
+  - id: throw-todo
+    languages: [typescript, javascript]
+    description: "throw new Error('TODO ...') — same as not-implemented."
+    regex: 'throw\s+new\s+Error\s*\(\s*[''"`]\s*TODO\b'
+    severity: hard
+
+  - id: python-not-implemented
+    languages: [python]
+    description: "raise NotImplementedError — Python equivalent of the above."
+    regex: 'raise\s+NotImplementedError\b'
+    severity: hard
+
+  - id: rust-todo-macro
+    languages: [rust]
+    description: "todo!() / unimplemented!() macro — Rust placeholder."
+    regex: '\b(todo|unimplemented)!\s*\('
+    severity: hard
+
+  - id: rust-panic-todo
+    languages: [rust]
+    description: "panic!(\"todo\" / \"not implemented\") — disguised stub."
+    regex: 'panic!\s*\(\s*"(todo|not\s+implemented)\b'
+    severity: hard
+
+  - id: go-todo-panic
+    languages: [go]
+    description: "panic(\"TODO\" / \"unimplemented\") — Go placeholder."
+    regex: 'panic\s*\(\s*"(TODO|unimplemented|not\s+implemented)'
+    severity: hard
+
+  # ── Empty function bodies pretending to be implementations ──────────────
+  - id: empty-async-body
+    languages: [typescript, javascript]
+    description: "async function with empty body — async fn () => {} masquerades as work."
+    regex: 'async\s+(function\s+\w+\s*\([^)]*\)|\([^)]*\)\s*=>)\s*\{\s*\}'
+    severity: hard
+
+  - id: arrow-returning-undefined
+    languages: [typescript, javascript]
+    description: "() => {} or () => undefined — placeholder lambda."
+    regex: '=>\s*(\{\s*\}|undefined)\s*[,;)]'
+    severity: soft
+
+  - id: python-pass-only
+    languages: [python]
+    description: "Function whose only body is `pass` — Python empty stub."
+    regex: 'def\s+\w+\s*\([^)]*\)\s*(->[^:]+)?:\s*\n\s*pass\s*\n'
+    severity: hard
+
+  # ── "as any" / type escape hatches ──────────────────────────────────────
+  - id: ts-as-any
+    languages: [typescript]
+    description: "`as any` — type escape hatch; almost always indicates undone work."
+    regex: '\bas\s+any\b'
+    severity: soft
+
+  - id: ts-any-cast-bang
+    languages: [typescript]
+    description: "Non-null assertion + any cast pattern: `(x as any)!` — double evasion."
+    regex: '\(\s*[\w.]+\s+as\s+any\s*\)!'
+    severity: hard
+
+  # ── Type-checker / linter suppressions without justification ────────────
+  - id: ts-ignore-bare
+    languages: [typescript, javascript]
+    description: "`// @ts-ignore` without a reason comment on the same/next line."
+    regex: '//\s*@ts-ignore\s*$'
+    severity: hard
+
+  - id: ts-expect-error-bare
+    languages: [typescript, javascript]
+    description: "`// @ts-expect-error` without a reason."
+    regex: '//\s*@ts-expect-error\s*$'
+    severity: hard
+
+  - id: eslint-disable-bare
+    languages: [typescript, javascript]
+    description: "eslint-disable-next-line without rule name + reason."
+    regex: '//\s*eslint-disable(-next-line)?\s*$'
+    severity: hard
+
+  # ── Returning empty/null/zero collections as fake results ───────────────
+  - id: only-return-null
+    languages: [typescript, javascript]
+    description: "Function whose entire body is `return null;` (one-line stub)."
+    regex: '\{\s*return\s+null\s*;?\s*\}'
+    severity: soft
+
+  - id: only-return-undefined
+    languages: [typescript, javascript]
+    description: "Function whose entire body is `return;` or `return undefined;`."
+    regex: '\{\s*return\s*(undefined)?\s*;?\s*\}'
+    severity: soft
+
+  - id: only-return-empty-array
+    languages: [typescript, javascript]
+    description: "Function whose entire body is `return [];` (suspicious for query funcs)."
+    regex: '\{\s*return\s*\[\s*\]\s*;?\s*\}'
+    severity: soft
+
+  - id: only-return-empty-object
+    languages: [typescript, javascript]
+    description: "Function whose entire body is `return {};`."
+    regex: '\{\s*return\s*\{\s*\}\s*;?\s*\}'
+    severity: soft
+
+  - id: only-resolve-void
+    languages: [typescript, javascript]
+    description: "Function whose entire body is `return Promise.resolve();`."
+    regex: '\{\s*return\s+Promise\.resolve\s*\(\s*\)\s*;?\s*\}'
+    severity: hard
+
+  # ── Console-log-as-implementation ───────────────────────────────────────
+  - id: console-log-stub
+    languages: [typescript, javascript]
+    description: "console.log('not implemented') / console.warn('TODO ...') as the only body."
+    regex: 'console\.(log|warn|error)\s*\(\s*[''"`][^''"`]*(not\s+implemented|TODO|stub|placeholder)'
+    severity: hard
+
+  # ── Decorator + always-undefined fields (NestJS / class-validator) ──────
+  - id: optional-always-undefined
+    languages: [typescript]
+    description: "@IsOptional() field with no other validators or assignment — fake-thoroughness DTO field."
+    regex: '@IsOptional\s*\(\s*\)\s*\n\s*\w+\??:\s*\w+\s*;\s*$'
+    severity: soft
+
+  # ── Dead/commented-out code blocks ──────────────────────────────────────
+  - id: commented-block-3-plus-lines
+    languages: [typescript, javascript, python, ruby, go, rust]
+    description: "Block of 3+ consecutive commented-out code lines (not doc comments)."
+    regex: '(?:^[\t ]*//[^\n]*\n){3,}'
+    severity: soft
+
+  - id: commented-out-import
+    languages: [typescript, javascript]
+    description: "Commented-out import statement — usually leftover from undone work."
+    regex: '^\s*//\s*import\s+'
+    severity: soft
+
+  # ── Test placeholders ───────────────────────────────────────────────────
+  - id: it-skip-no-reason
+    languages: [typescript, javascript]
+    description: "it.skip / describe.skip / test.skip without a // reason — silent skip is a stub."
+    regex: '\b(it|describe|test|specify)\.skip\s*\([^)]*\)\s*[^/]*$'
+    severity: soft
+
+  - id: xit-bare
+    languages: [typescript, javascript]
+    description: "xit / xdescribe — Jasmine-era skip macro."
+    regex: '\b(xit|xdescribe|xtest)\s*\('
+    severity: hard
+
+  # ── Suppress-unused tricks ──────────────────────────────────────────────
+  - id: void-suppress-unused
+    languages: [typescript, javascript]
+    description: "`void unused;` to suppress tsc-unused — usually means feature half-implemented."
+    regex: '^\s*void\s+\w+\s*;\s*$'
+    severity: soft
+
+  - id: underscore-prefixed-arg
+    languages: [typescript]
+    description: "Function arg renamed `_unused` to escape the linter without using it. (Soft — may be legitimate.)"
+    regex: '\(\s*_\w+\s*:'
+    severity: soft
+
+  # ── Hard-coded "fake" values ────────────────────────────────────────────
+  - id: foo-bar-baz
+    languages: [typescript, javascript, python, ruby, go, rust]
+    description: "String literal foo / bar / baz / lorem in production-path code."
+    regex: '[''"`](foo|bar|baz|qux|lorem)[''"`]'
+    severity: soft
+
+  - id: dummy-placeholder
+    languages: [typescript, javascript, python, ruby, go, rust]
+    description: "String literal containing 'dummy', 'placeholder', or 'TODO' as the value itself."
+    regex: '[''"`](dummy|placeholder|TODO|stub)[''"`]'
+    severity: soft
+
+  # ── Ad-hoc time hacks ───────────────────────────────────────────────────
+  - id: setTimeout-await
+    languages: [typescript, javascript]
+    description: "setTimeout used as `await new Promise(r => setTimeout(r, N))` — pause-as-fix is almost always a stub."
+    regex: 'await\s+new\s+Promise\s*\(\s*\w+\s*=>\s*setTimeout\s*\(\s*\w+\s*,\s*\d+'
+    severity: soft
+
+  # ── SQL stubs ───────────────────────────────────────────────────────────
+  - id: sql-select-1
+    languages: [sql]
+    description: "Migration/query containing only `SELECT 1` — placeholder."
+    regex: '^\s*SELECT\s+1\s*;?\s*$'
+    severity: soft

package/templates/.cairn/config/trust-policy.yaml

@@ -0,0 +1,95 @@
+# Trust policy.
+#
+# Per-command trust posture (WORKFLOW_GUIDE.md §3 + §8). Three classes:
+#
+#   read_only            no friction — runs without any operator confirmation
+#   write_creating       light friction — single-tap reaction or button confirm
+#   configuration        heavy friction — operator must edit a config file
+#
+# Auto-merge classes (PRIMER §12.2) live in workflow.md trust_posture_defaults
+# and the project block; this file governs operator INTERACTION friction, not
+# git-push friction.
+
+version: 1
+
+commands:
+
+  # ── Read-only — no friction ───────────────────────────────────────────
+  - id: status
+    posture: read_only
+    surface: slash
+  - id: queue
+    posture: read_only
+    surface: slash
+  - id: eval
+    posture: read_only
+    surface: slash
+  - id: agent_list
+    posture: read_only
+    surface: slash
+  - id: help
+    posture: read_only
+    surface: slash
+
+  # ── Write-creating — single-tap confirm ────────────────────────────────
+  - id: task
+    posture: write_creating
+    surface: slash
+    confirmation: none           # spec tightener handles ambiguity downstream
+  - id: run
+    posture: write_creating
+    surface: slash
+    confirmation: reaction_if_outside_pilot_scope
+    timeout_seconds: 30
+  - id: oops
+    posture: write_creating
+    surface: slash
+    confirmation: per_step_inline_reaction
+  - id: direction
+    posture: write_creating
+    surface: slash
+    confirmation: green_red_pre_commit
+  - id: archive
+    posture: write_creating
+    surface: slash
+    confirmation: green_confirm_with_reason
+  - id: resume
+    posture: write_creating
+    surface: slash
+    confirmation: none
+  - id: ship_anyway
+    posture: write_creating_logged_override
+    surface: slash
+    confirmation: none           # logged for audit; no friction
+  - id: halt
+    posture: write_creating
+    surface: slash
+    confirmation: none
+
+  # ── Configuration — high-friction by design ─────────────────────────────
+  - id: enable_auto_merge_code_class
+    posture: configuration
+    surface: workflow_yaml_edit
+  - id: disable_sensor
+    posture: configuration
+    surface: workflow_yaml_edit
+  - id: change_pilot_module
+    posture: configuration
+    surface: workflow_yaml_edit
+  - id: change_collaboration_mode
+    posture: configuration
+    surface: workflow_yaml_edit
+  - id: register_frontend_adapter
+    posture: configuration
+    surface: workflow_yaml_edit
+  - id: change_off_limits
+    posture: configuration
+    surface: workflow_yaml_edit
+
+# Default routing for out-of-band notifications.
+notification_routing:
+  errors: all_registered_adapters
+  completions: all_registered_adapters
+  paged_events: all_registered_adapters
+  uat_approval_request: first_registered_adapter
+  voice_capable_only: discord

package/templates/.cairn/config/workflow.md

@@ -0,0 +1,230 @@
+---
+type: workflow-policy
+status: draft
+audience: dual
+generated: 2026-05-02T13:19:00Z
+verified-at: 2026-05-02T13:19:00Z
+source-commits:
+  - manual
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Top-level (project-agnostic) configuration.
+# This block is read by Cairn package code; values here are universal defaults.
+# Project-specific overrides go in the `<project_name>:` extension block below.
+# ──────────────────────────────────────────────────────────────────────────────
+
+collaboration_mode: solo                # solo | team — see FILESYSTEM_LAYOUT.md §12
+concurrency: 1                          # single-task FIFO; do not change without re-reviewing PRIMER §5.4
+
+frontend_adapters:
+  - discord                             # discord | notion | cli | web
+  # operator may register additional adapters; first-registered owns approval-request routing
+
+tier_assignment:
+  intent_classifier: 0                  # 0 = Ollama; 1 = Haiku 4.5; 2 = Sonnet 4.6; 3 = Opus 4.7
+  spec_tightener_short: 1
+  spec_tightener_long: 2
+  decision_extractor: 1
+  attestation_check: 0                  # mechanical regex; LLM only on ambiguity
+  implementer_default: 2
+  implementer_high_stakes: 3
+  reviewer: 2                           # same model as implementer; context isolation does the work
+  uat_runner: 2
+  uat_question_agent: 1
+  backprop_author: 2
+  garbage_collector: 1
+  init_mapper: 2                        # one-time at adoption; OK to spend tokens
+
+# Tier-3 (Opus) auto-escalation policy — per Codex audit Finding #9.
+escalation:
+  tier_3_requires_explicit_approval: true
+  max_attempts_per_task: 3              # halt + page operator after this many retries
+  pre_run_cost_projection: true         # block dispatch on > 1% daily plan-headroom estimate
+
+# Run lifecycle thresholds.
+timeouts:
+  stall_event_silence_seconds: 300      # no event in 5 min → kill + retry
+  uat_decision_seconds: 86400           # 24h before auto-deny
+  approval_dialog_seconds: 30           # 🟢/🔴 confirm window
+
+# Anthropic plan-quota self-throttle (per WORKFLOW_GUIDE §2.2).
+plan_quota_floor_percent: 20            # below this remaining → Cairn self-throttles to Tier 1 only
+
+# Spec-tightener gate.
+spec_quality_floor: 7                   # quality_score < floor → operator dialog OR /ship-anyway
+
+# Dialog rules.
+operator_dialog_max_questions_per_turn: 2  # Codex audit Finding #7 — collapse 3+ to single tightened proposal
+
+# Trust posture defaults — overridden in project block as needed.
+trust_posture_defaults:
+  safe_class_auto_merge: true
+  code_class_auto_merge: false
+  high_stakes_auto_merge: false
+
+# Decision capture defaults.
+decision_extractor:
+  auto_propose_threshold_confidence: 0.7
+  require_assertions_at_confirm: true
+
+# Whisper / voice defaults.
+voice:
+  enabled: true
+  model: large-v3-turbo
+  quantization: q5_0
+  language: en
+  confidence_floor: 0.85                # below → operator confirm-heard prompt
+  audio_persistence: forbidden          # never write audio to disk
+
+# Local mirror checkout (Cairn operates here, never user's working tree).
+mirror:
+  base_path: "~/.local/cairn/repos"   # one subdir per adopted project
+  state_path: "~/.local/cairn/state"  # PIDs, sockets, runtime
+  models_path: "~/.local/cairn/models"
+
+# Retention policy.
+retention_days:
+  runs: 90
+  transcripts: 90
+  inbox: 30
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Project-extension placeholder.
+#
+# At adoption (`npx @isaacriehm/cairn init`), the init script REPLACES this
+# block with a real key matching the adopting project's `package.json name`
+# (or directory name, lowercased, with non-alphanumerics → underscores).
+#
+# Cairn package code reads this block by `Object.keys()` lookup — never by
+# hardcoded project name (per L50 + operator-S1).
+#
+# Example below uses `<project_name>` as the placeholder key.
+# ──────────────────────────────────────────────────────────────────────────────
+
+<project_name>:
+  pilot_module: ALL                     # full repo, OR a glob like core/src/integrations/**
+  off_limits:
+    - .git/**
+    - .archive/**
+    - .env
+    - .env.local
+    - node_modules/**
+    # adopting project extends with its own off-limits paths at init
+  high_stakes_globs: []                 # populated at init from stack-profile heuristic + operator confirm
+  trust_posture:
+    safe_class_auto_merge: true
+    code_class_auto_merge: false
+    high_stakes_auto_merge: false
+  budget_metric:
+    primary: claude_code_subscription_quota
+    secondary_dollar_record_only: true
+    pre_run_projection: true
+    tier_3_requires_explicit_approval: true
+    max_attempts_per_task: 3
+
+---
+
+# Per-task prompt template
+
+Below is the rendered-prompt body the orchestrator injects into every agent run. The template engine substitutes `{{var}}` tokens with run-scoped values resolved at dispatch time.
+
+## Identity
+
+You are running inside Cairn as agent role `{{agent_role}}` for project `{{project_name}}`. Your run-id is `{{run_id}}`. The mirror checkout is at `{{mirror_path}}` pinned to `origin/main` SHA `{{sha_pin}}`. Do not modify files outside the mirror. Do not switch branches.
+
+## Task
+
+{{tightened_spec_body}}
+
+## Acceptance criteria
+
+{{#each acceptance_criteria}}
+- {{this}}
+{{/each}}
+
+## Decisions in scope
+
+The following accepted decisions bind your work. You MUST NOT contradict them. Their machine-readable assertions will be evaluated against your diff.
+
+{{#each in_scope_decisions}}
+- **{{id}}** — {{title}}  ({{scope_summary}})
+{{/each}}
+
+If none, this is empty.
+
+## Invariants in scope
+
+The following §V invariants bind your work. They have sensors that will block your commit if violated.
+
+{{#each in_scope_invariants}}
+- **{{id}}** — {{title}}
+{{/each}}
+
+If none, this is empty.
+
+## Off-limits paths
+
+You MUST NOT modify any of these:
+
+{{#each off_limits}}
+- {{this}}
+{{/each}}
+
+## Sensors that will run
+
+After your turn, these sensors will execute against your diff. Their failure messages are remediation prompts — read them and retry.
+
+{{#each scoped_sensors}}
+- `{{id}}` — {{description}}
+{{/each}}
+
+## Honesty contract (Layer B)
+
+When you emit your final response, include a fenced YAML block titled `attestation` with these fields filled:
+
+```yaml
+attestation:
+  delivered:
+    - symbol: "<name>"
+      path: "<path>"
+      behavior: full | partial | scaffolded
+      sensors_passed: [<sensor_ids>]
+  deferred:
+    - symbol: "<name>"
+      reason: "<one line>"
+  known_limitations: []
+  todos_introduced: 0
+  stubs_introduced: 0
+  files_touched: ["<paths>"]
+```
+
+This will be cross-checked against your actual diff. Any mismatch fails the run.
+
+## Tools available
+
+You have the standard Read/Edit/Write/Bash/Glob/Grep tool surface. You also have the Cairn MCP tools — use these for grounding rather than re-reading large files:
+
+- `cairn_decision_get(id)` — full ADR + assertions
+- `cairn_decisions_in_scope(globs[])` — IDs whose scope overlaps your target
+- `cairn_invariant_get(id)` — §V invariant + linked sensor
+- `cairn_canonical_for_topic(topic)` — canonical doc path + verified-at
+- `cairn_query_history(scope, question)` — the ONLY way to read `.archive/`
+
+## Constraints
+
+- Hard cutovers; no backwards-compat shims, no deprecation notices, no transition regex.
+- No `[STALE]` banners — stale docs get archived, not labeled.
+- No model-issued confidence scores in user-visible writes.
+- No commit, no push — Cairn handles git after sensor + reviewer + UAT pass.
+
+## Stop conditions
+
+Stop when the acceptance criteria are met AND the attestation block is complete AND no in-scope assertion or invariant is contradicted.
+
+If you cannot proceed (genuine ambiguity, missing context, contradicting decisions), emit a `blocked_by` field instead of a partial diff:
+
+```yaml
+blocked_by:
+  reason: "<one line>"
+  needed_from_operator: "<one line>"
+```

package/templates/.cairn/git-hooks/commit-msg

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Cairn commit-msg hook (versioned, per-clone activation via core.hooksPath).
+#
+# Spec: PLUGIN_ARCHITECTURE §17 Layer 1.
+#
+# Validates DEC/TSK/§V citations in the commit message body when the
+# project's commit policy requires them. The Cairn CLI owns the policy
+# (sensors.yaml `commit_msg_policy`) so the hook stays a thin shim.
+
+set -e
+
+if ! command -v cairn > /dev/null 2>&1; then
+  # If Cairn isn't on PATH, the pre-commit hook already blocked.
+  exit 0
+fi
+
+exec cairn sensor-run --commit-msg "$1" "$@"

package/templates/.cairn/git-hooks/post-commit

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Cairn post-commit hook (versioned, per-clone activation via core.hooksPath).
+#
+# Spec: PLUGIN_ARCHITECTURE §17 Layer 1 (bypass tracking).
+#
+# Records the SHA of the commit that just succeeded into
+# `.cairn/.attested-commits`. The Stop hook uses this list to detect
+# `--no-verify` bypasses and surface them inline.
+
+set -e
+
+if ! command -v git > /dev/null 2>&1; then
+  exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2> /dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+  exit 0
+fi
+
+SHA="$(git rev-parse --verify HEAD 2> /dev/null || true)"
+if [ -z "$SHA" ]; then
+  exit 0
+fi
+
+mkdir -p "$REPO_ROOT/.cairn"
+echo "$SHA" >> "$REPO_ROOT/.cairn/.attested-commits"
+exit 0

package/templates/.cairn/git-hooks/pre-commit

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Cairn pre-commit hook (versioned, per-clone activation via core.hooksPath).
+#
+# Spec: PLUGIN_ARCHITECTURE §17 Layer 1.
+#
+# Fails the commit when:
+#   - Cairn CLI is missing from PATH
+#   - sensor-run --staged exits non-zero
+#
+# To opt out a project: rm .cairn/  (irreversible).
+# Bypass for a single commit: git commit --no-verify (CI gate still catches).
+
+set -e
+
+if ! command -v cairn > /dev/null 2>&1; then
+  echo "✗ Cairn CLI not on PATH"
+  echo "  This project requires Cairn. Install:"
+  echo "    /plugin install cairn@isaacriehm-cairn   (Claude Code)"
+  echo "    npm install -g @isaacriehm/cairn            (CLI)"
+  echo "  Or: rm -rf .cairn/  to opt the project out (irreversible)"
+  exit 1
+fi
+
+exec cairn sensor-run --staged "$@"

package/templates/.cairn/ground/brand/overview.md

@@ -0,0 +1,24 @@
+---
+type: rule
+status: draft
+audience: dual
+generated: 2026-05-04T00:00:00Z
+verified-at: 2026-05-04T00:00:00Z
+source-commits:
+  - manual
+---
+
+# Brand overview
+
+<!--
+Fill this in. This file is injected at every SessionStart so the AI knows
+what your product looks and sounds like before it makes design decisions.
+Keep it short — one paragraph max, < 200 tokens. Cover: product personality,
+tone, what to avoid. Detailed colors/typography go in colors.yaml /
+typography.yaml.
+
+While status is `draft`, the AI will see a [DRAFT] hint in its context and
+ask before making design decisions. Flip status to `accepted` once filled.
+-->
+
+(operator: replace this paragraph with your brand summary)

package/templates/.cairn/ground/brand/voice.md

@@ -0,0 +1,20 @@
+---
+type: rule
+status: draft
+audience: dual
+generated: 2026-05-04T00:00:00Z
+verified-at: 2026-05-04T00:00:00Z
+source-commits:
+  - manual
+---
+
+# Brand voice
+
+<!--
+Tone, vocabulary, communication style. Read at every SessionStart so the AI
+knows how to talk in this project. Keep tight — < 200 tokens.
+
+Flip status to `accepted` once filled.
+-->
+
+(operator: replace this paragraph with how Claude should communicate)