@isaacriehm/cairn-core 0.1.0

package/templates/.cairn/ground/canonical-map/topics.yaml

@@ -0,0 +1,54 @@
+# Canonical-map — topic → canonical-doc-path.
+#
+# Curated registry. Agents call `cairn_canonical_for_topic(<topic>)` to get
+# the authoritative path for a topic — no fuzzy match, no hallucinated paths.
+#
+# Adopters extend this registry as their codebase grows. Unknown topics
+# return TOPIC_NOT_REGISTERED — agents must NOT invent topics. Add via
+# /direction confirmation when an operator references a recurring topic
+# the Cairn agents should know about.
+#
+# Below is a baseline that ships with `cairn init` so every adoption
+# has a non-empty registry on day one. Trim or extend per project.
+
+version: 1
+topics:
+  - topic: agents-md
+    canonical_path: AGENTS.md
+    audience: dual
+  - topic: claude-md
+    canonical_path: CLAUDE.md
+    audience: dual
+  - topic: cairn-architecture
+    canonical_path: docs/ARCHITECTURE.md
+    audience: dual
+  - topic: cairn-primer
+    canonical_path: docs/PRIMER.md
+    audience: dual
+  - topic: cairn-mcp-surface
+    canonical_path: docs/MCP_SURFACE.md
+    audience: dual
+  - topic: cairn-filesystem-layout
+    canonical_path: docs/FILESYSTEM_LAYOUT.md
+    audience: dual
+  - topic: cairn-workflow-guide
+    canonical_path: docs/WORKFLOW_GUIDE.md
+    audience: dual
+  - topic: cairn-uat-pipeline
+    canonical_path: docs/UAT_PIPELINE.md
+    audience: dual
+  - topic: cairn-sessionstart-spec
+    canonical_path: docs/SESSIONSTART_SPEC.md
+    audience: dual
+  - topic: two-zone-separation
+    canonical_path: docs/PRIMER.md
+    audience: dual
+  - topic: backprop-protocol
+    canonical_path: docs/PRIMER.md
+    audience: dual
+  - topic: garbage-collection-cadence
+    canonical_path: docs/PRIMER.md
+    audience: dual
+  - topic: anti-patterns
+    canonical_path: docs/PRIMER.md
+    audience: dual

package/templates/.cairn/ground/capabilities/mcp-tools.yaml

@@ -0,0 +1,4 @@
+# MCP servers registered alongside Cairn in .mcp.json.
+# Includes name + description so the agent knows what's available without
+# listing every tool exhaustively.
+mcp_tools: []

package/templates/.cairn/ground/capabilities/skills.yaml

@@ -0,0 +1,3 @@
+# Installed skill packs available in this session.
+# The init mapper scans .claude/skills/ and seeds entries; operator extends.
+skills: []

package/templates/.cairn/ground/capabilities/snippets.yaml

@@ -0,0 +1,3 @@
+# Blessed implementations for security-sensitive patterns.
+# See DOCS_SPEC.md §3.5 for shape.
+snippets: []

package/templates/.cairn/ground/manifest.yaml

@@ -0,0 +1,16 @@
+# Ground manifest — read-only for agents.
+#
+# Continuously regenerated by `cairn watch` (the grounding daemon) on filesystem
+# events. Each entry is one canonical-zone file with its hash, classification,
+# audience, verified-at, and (for generated artifacts) the source + generator.
+#
+# Agents query the MCP tool surface, NOT this file directly. The daemon is the
+# only writer. Modifying this file by hand is meaningless — the daemon overwrites
+# on next event.
+#
+# Layout per FILESYSTEM_LAYOUT.md §8.
+
+version: 1
+generated: 2026-05-02T13:19:00Z
+generator: cairn-watch
+files: []

package/templates/.cairn/ground/product/personas.yaml

@@ -0,0 +1,4 @@
+# Product personas — who this is for. Read at every SessionStart.
+# See DOCS_SPEC.md §3.4 for shape.
+status: draft
+personas: []

package/templates/.cairn/ground/product/positioning.md

@@ -0,0 +1,21 @@
+---
+type: rule
+status: draft
+audience: dual
+generated: 2026-05-04T00:00:00Z
+verified-at: 2026-05-04T00:00:00Z
+source-commits:
+  - manual
+---
+
+# Product positioning
+
+<!--
+Fill this in. This file is injected at every SessionStart so the AI knows
+what the product is and isn't. Keep it short — < 300 tokens. Cover: who
+this is for, the core value, what's deliberately out of scope.
+
+Flip status to `accepted` once filled.
+-->
+
+(operator: replace this paragraph with a tight positioning statement)

package/templates/.claude/settings.json

@@ -0,0 +1,57 @@
+{
+  "statusLine": {
+    "type": "command",
+    "command": "cairn status-line"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cairn hook session-start"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cairn hook session-end"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cairn hook read-enrich"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cairn hook write-guard"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cairn hook write-guard"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.github/workflows/cairn-check.yml

@@ -0,0 +1,31 @@
+name: cairn-check
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+
+jobs:
+  cairn:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install Cairn CLI
+        run: npm install -g @isaacriehm/cairn
+
+      - name: Run Cairn sensors against PR diff
+        run: |
+          base="${GITHUB_BASE_REF:-main}"
+          cairn sensor-run --diff "origin/${base}..HEAD" --strict

package/templates/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "cairn": {
+      "command": "cairn",
+      "args": ["mcp", "serve"]
+    }
+  }
+}

package/templates/README.md

@@ -0,0 +1,24 @@
+# `templates/` — files the init script copies into adopted projects
+
+This directory ships with the `@isaacriehm/cairn` npm package. It is the seed for `.cairn/` and `.archive/` inside any project that runs:
+
+```sh
+npx @isaacriehm/cairn init <repo-dir>
+```
+
+Layout mirrors `docs/FILESYSTEM_LAYOUT.md`. The init script:
+
+1. Copies `templates/.cairn/config/*` into `<repo-dir>/.cairn/config/` (preserving the `<project_name>:` placeholder; the script then replaces it with the adopting project's package name).
+2. Copies `templates/.cairn/ground/manifest.yaml` (empty stub; daemon populates).
+3. Copies `templates/.archive/README.md` into `<repo-dir>/.archive/`.
+4. Creates the runtime directories (`runs/`, `inbox/`, `transcripts/`, `tasks/`, `staleness/`, `ground/{decisions,invariants,canonical-map,schema,routes,events}/`) and adds them to the project's `.gitignore` per spec §9.
+
+This directory is **NOT** Cairn's own state. The Cairn package source repo is not self-hosted; it is the source for the published npm package.
+
+## Why placeholders?
+
+The `<project_name>:` block in `templates/.cairn/config/workflow.md` is a placeholder by design. The init script reads the adopting project's `package.json name` (or directory name as fallback), normalizes it (lowercase, non-alphanumerics → underscores), and replaces every occurrence of `<project_name>` in the copied file. Cairn package code reads the project block at runtime via `Object.keys()` lookup — never by hardcoded project name (per L50, operator answer S1).
+
+## Editing templates
+
+Templates are the single source of seed configuration. Changes here flow to every freshly-adopted project on next `npx @isaacriehm/cairn init`. Existing adoptions are unaffected — they own their copies.