# Template design decisions Decision records about the **template itself** — why the Cascade KB is shaped the way it is. They use the same `type: decision` format as `wiki/decisions/`, but they live here, in the template layer, because: - `wiki/decisions/` is content: a KB's *own* decisions about its *own* subject. `ckb-reset` may wipe it, and a fresh `ckb-init` starts it empty. - Skills, modules and docs cite these records. A template must not depend on pages the content layer is allowed to delete. `ckb-upgrade` carries this folder along with the rest of the template layer. `ckb-decide` never writes here — it is not a place for a KB's project decisions. | # | Decision | |---|---| | [D-0001](0001-opt-in-file-based-kb-modules.md) | Optional capabilities ship as file-based modules under `.agents/modules/`, installed on request | | [D-0002](0002-software-module-design.md) | The `software` module: gitignored `src/` clones, two OpenSpec spec levels, hybrid vendoring | | [D-0003](0003-python-runtime-with-degraded-fallbacks.md) | Python stays the only scripting runtime; portable interpreter resolution, per-OS install guidance, a native fallback for the session-start check, degraded paths per skill (PowerShell half dropped by D-0019) | | [D-0004](0004-session-identity-from-git.md) | The git identity is the session's author; one workload file per person per day; `**Author:**` on log entries and saved conversations | | [D-0005](0005-session-titles-and-routines.md) | A new session asks for its title first and waits (point 1 reversed by D-0006); routines are time-since-last actions in `ckb.yaml`, run after the user's request, with `last_run` committed | | [D-0006](0006-title-chosen-by-agent.md) | The agent derives the session title from the first message and only announces it in one line; `announce_title` replaces `ask_title` | | [D-0007](0007-mcp-server-module.md) | The `mcp` module serves the KB over MCP: cascade-aware reads; remote writes limited to `raw/inbox/` and retraction requests, each naming its KB and confirmed by the user, and removable only by the person who added the document; auth switched by one flag (`none`/`token`/`oauth`), server runs in place against its own clone | | [D-0008](0008-document-templates.md) | Document templates are the user's Markdown files in root `templates/`, outside the cascade and the template layer; a comment per section is the agent's brief; `ckb-document` fills one into `outputs/documents/`, asking in one round and leaving `TODO:` lines instead of guesses | | [D-0009](0009-session-start-in-one-call.md) | Session start is one `session_start.py` call that says what to act on; `wiki/index.md` and the whole workload file are no longer read at start; a skill's `## Purpose` says only what its description does not | | [D-0010](0010-about-file.md) | A root `ABOUT.md`, written by the owner, states what the KB holds (purpose, audience, scope, owners, sensitivity) and the README links to it; agents read it, never edit it; ingest checks scope against it; `wiki/overview.md` stays the agent's summary | | [D-0011](0011-session-start-hook.md) | Session start can run as a per-machine, opt-in Claude Code `SessionStart` hook that injects the Rule E brief before the first message and after every compaction; Rule E stays the fallback | | [D-0012](0012-open-threads-not-a-status-file.md) | "What is in flight" is collected from `### Open threads` checkboxes in each person's workload notes, not a shared status page; threads close where they were opened | | [D-0013](0013-kept-answers-and-secret-guards.md) | Kept answers go to `outputs/answers/` with fingerprinted sources and reach the wiki only through ingest; committed text is scanned for secrets and `` spans, never auto-fixed, with a line-hash allowlist | | [D-0014](0014-schema-1-6-review-contradictions-tags-profiles.md) | Schema 1.6: `review`/`reviewed_by`/`reviewed_on` (not `status`), `tags` against `wiki/tags.md`, a `> CONTRADICTION:` marker, protected `## Rules` on project scopes; profiles in `workload/profiles/` and explicit lessons via a new `ckb-profile` skill; claim-level validity deferred | | [D-0015](0015-section-index-and-access-log.md) | Retrieval gains a stdlib FTS5 section index (title/heading/tldr as a separate context column) cached in `tmp/`, fused at weight 1.0, with section anchors and token estimates; pages read go to a per-machine `tmp/access.log` that lint turns into demotion proposals only | | [D-0016](0016-topic-summaries-and-consolidation.md) | Schema 1.7: agent-built topic pages in `wiki/topics/` with member-page digests as sources; a new `ckb-consolidate` skill writes proposals-only reports (topics, merges, links, stale, old log) and builds only approved topic pages | | [D-0017](0017-capture-module-and-skill-evals.md) | Opt-in `capture` module (stdlib fetch, Wayback only over a failed/thinner page, agent tool fallback, untrusted marking, dedup at capture, `yt-dlp` with consent); structural skill evals with a prepare/check runner; multi-agent setup documented as untested | | [D-0018](0018-share-mailbox-module.md) | Opt-in `share` module: KBs exchange documents through a git channel with one append-only mailbox per KB; received mail lands in `raw/inbox/` (untrusted) and retractions in `raw/retractions/`; the git author must own the mailbox; handled messages are kept in a ledger in `ckb.yaml` | | [D-0019](0019-two-dot-zero-drops-powershell.md) | Template 2.0.0 drops PowerShell; every script the template and its modules ship is Python (bash fallback and the container entrypoint named as exceptions); 1.x continues on a `1.x` maintenance branch; `ckb-upgrade` never crosses a major version without asking |