AGENTS.md git:20260829.ea80da8A

Immutable. This exact content is served forever at /api/v1/blob/9646e8a9063e5ab9.

# Commonplace

`CLAUDE.md` is a symlink to this file (`AGENTS.md`). Edit `AGENTS.md` directly.

> **Vendored?** If this repository sits inside another project as a read-only knowledge base (a submodule or gitignored clone — see `INSTALL.md`, "Reader install"), you are a reader here, not an operator: navigate from `kb/notes/tags-README.md`, quote and cite freely, and do not create, edit, or commit anything under this directory. Everything below applies only when Commonplace itself is the working project. To contest a claim, open an issue at <https://github.com/zby/commonplace/issues>.

## Repository Overview

A framework for building agent-operated knowledge bases. This repo contains the methodology, type definitions, writing conventions, instructions and skills, and the Python commands that get installed into projects.

The Commonplace repo is itself a knowledge base — it uses its own knowledge system to document the methodology for building knowledge bases. There is no separation between "user content" and "methodology" here; the methodology IS the content.

## KB Goals and Scope

### Purpose

Support decisions about KB architecture, type systems, writing quality, context engineering, and knowledge organization — made by agents and maintainers working on Commonplace or on KBs built with it.

### Scope

Agent-operated knowledge base methodology: how to structure, write, connect, validate, review, and maintain knowledge artifacts for consumption by LLM agents.

In scope:

- Design decisions about KB methodology (type systems, linking, indexing, review)
- Context engineering theory (constraining, codification, knowledge reshaping)
- Operational patterns (writing workflows, validation, maintenance)
- Evaluations and comparisons with external knowledge systems

Out of scope:

- Application-specific KB content (belongs in consuming projects)
- General software engineering, learning theory, or cognitive science unless it directly informs KB design decisions
- Raw logs without analysis (use `kb/log.md`)

### Quality bar

A design insight is worth a note when it changes how someone would build or operate a KB. Observations about what works are worth a log entry on first occurrence and a note when the mechanism is understood. Pure pattern-recording without explanation belongs in a log entry, not a note.

**Simple writing (best effort).** Use the simplest wording that preserves the claim and its necessary qualifications. Aim for one main point per sentence. Prefer short, direct sentences. State definitions directly, put conditions and qualifiers next to the claims they limit, and make causal or contrastive relationships explicit. The KB graph already supplies complexity through connections among notes; do not add avoidable complexity inside a sentence.

**One term per concept (best effort).** Use the same word for the same thing throughout an artifact, and the KB's registered term where one exists. Literary style varies words to avoid repetition; technical prose does not, because a new word reads as a new referent. Do not swap in a synonym for variety.

**Substantive specificity (best effort).** Make each paragraph earn its place by changing what the reader understands, infers, or can do; do not restate or praise a point merely to make the text sound complete. In load-bearing claims, resolve ambiguity that would change the claim's truth conditions, evidential support, or implications; when relevant, name the mechanism, comparison basis, or scope. Use available specifics, but never invent precision: narrow the claim, state uncertainty, or flag the unresolved choice.

**Operator communication (best effort).** Shape messages around what the operator needs to understand or decide. Lead with the practical outcome, consequence, or decision needed, and keep important conditions and uncertainty next to the claim they limit. Use the simplest wording that preserves meaning, and make the opening understandable without first loading the implementation. Ordinary domain language and project terms with canonical definitions are fine, but expand or define terms coined for the task and terms inherited from artifacts that have no canonical definition; introduce code identifiers only after stating what they represent. Put deeper mechanism afterward. When a technical finding carries the evidence, point to that finding instead of reproducing its evidence. When a consequential explanation still depends on several concepts or a long causal chain, use the `operator-brief` skill.

## Vocabulary

Terms needed to understand the project's structure and everyday operations, alphabetical. Each links its full definition.

- **Actionable** — an operator-relative relation: a methodology is actionable only for an operator that can use its mapping through available operations on a target in a stated setting. Use this technical sense only in a clause that links the definition; unlinked *actionable* remains ordinary English. See `kb/notes/definitions/actionable-methodology.md`.
- **Assay** — any snapshot-anchored LLM evaluation executed through the review job pipeline. Closed-ended assays ask a fixed question; open-ended assays sample a space of possible findings. This question shape is distinct from the persisted `verdict`/`report` result kind. See `kb/reference/README-REVIEW-SYSTEM.md#concepts`.
- **Codification** — the far end of constraining, where natural language crosses into a symbolic artifact (code, schema, grammar) with formal semantics. See `kb/notes/definitions/codification.md`.
- **Collection** — a `kb/` subtree whose root contains `COLLECTION.md`; that file is the local authoring and routing contract for artifacts in the subtree. See `kb/reference/definitions/collection.md`.
- **Commonplace** — the name of this KB and framework. Capitalize it in prose; lowercase only in literal identifiers (`commonplace-*`, `llm-commonplace`, `src/commonplace/`, `kb/commonplace/`).
- **Commonplace doctrine** — the standing instruction a worker inherits with binding force when its runtime loads it: this file, plus the collection contracts, type specs, and skill its runtime supplies. A handoff is a delta from it. The compound is the technical term; bare *doctrine* stays ordinary English and may abbreviate it where nothing else (such as the source-side military doctrine in the planning reports) could be meant. See `kb/reference/definitions/commonplace-doctrine.md`.
- **Criterion** — the instruction text applied to a note in an assay. It occupies the persisted `criterion_path` side of a review pair; a gate is a closed-ended, verdict-kind criterion, while critique is an open-ended, report-kind criterion. See `kb/reference/README-REVIEW-SYSTEM.md#concepts`.
- **Constraining** — narrowing the space of valid interpretations an artifact admits — from writing a convention up to committing to code. See `kb/notes/definitions/constraining.md`.
- **Context engineering** — getting the right knowledge into a bounded context at the right time: routing, loading, scoping, maintenance. See `kb/notes/definitions/context-engineering.md`.
- **Discovery lifecycle** — the ideal-type staged path by which an ampliative conjecture earns acceptance: observe, conjecture, derive consequences, test, accept, integrate. The compound is the technical term; bare "discovery" stays ordinary English. See `kb/notes/definitions/discovery-lifecycle.md`.
- **Explanatory-reach** — the property that a claim keeps working beyond the cases that produced it because it captures why the pattern works; the quality goal of `kb/notes/` and the property reach-assessment judges. The compound is the technical term (adapted from Deutsch's "reach"); bare "reach" stays ordinary English. See `kb/notes/first-principles-reasoning-selects-for-explanatory-reach-over.md`.
- **Frontloading** — pre-computing parts of an instruction whose inputs are already known (at build, install, or session start) and inserting the result, so the consuming call's context carries the answer instead of the work. See `kb/notes/frontloading-spares-execution-context.md`.
- **Freshness baseline** — the current snapshot-pinned applicability boundary for one registered target. In v1 review targets are `review-pair` keys `(note, criterion, model partition)` with `note` and `criterion` `file-text` inputs; a baseline preserves an evidence review pair while tracking the latest accepted input snapshots — it is not endorsement or global approval. See `kb/reference/README-REVIEW-SYSTEM.md#concepts` and `kb/reference/freshness-architecture.md`.
- **Commonplace store** — the operational SQLite database (`kb/reports/state/commonplace-store.sqlite`; `COMMONPLACE_STORE`) holding artifact snapshots, freshness baselines, and review execution state. See `kb/reference/freshness-architecture.md`.
- **Gate** — a closed-ended, verdict-kind assay criterion. See `kb/reference/README-REVIEW-SYSTEM.md#concepts`.
- **Mark** — a frontmatter field that caches a value recomputable from ground truth recorded elsewhere, validated by code, and read by agents to spare an expensive in-context recompute (`complete`/`covered_by` on tag-READMEs). Recomputable, so never load-bearing; enforced-or-omitted, because a stale trusted cache is a trap. See `kb/types/tag-readme.md`.
- **Outcome** — the substantive `pass`, `warn`, or `fail` value produced by a completed verdict pair. Report pairs complete without an outcome; `ERROR` fails the job and is not an outcome. See `kb/reference/README-REVIEW-SYSTEM.md#concepts`.
- **Representational form** — how retained content is encoded and consumed: natural-language, symbolic (code, schemas, grammars), distributed-parametric (model weights), or mixed. Codification is the natural-language→symbolic crossing on this axis, and form sets the default review method: read natural-language content, test symbolic artifacts, probe parametric ones. **Prompt** is a consumption-path shorthand for material supplied or assembled as model input, not a fourth form or a synonym for every natural-language artifact. See `kb/notes/definitions/representational-form.md`.
- **Result kind** — the persisted pair protocol: `verdict` completes with an outcome; `report` completes without one. `REPORT` is a completion marker, not a fourth outcome. See `kb/reference/README-REVIEW-SYSTEM.md#concepts`.
- **System-definition artifact** — a retained artifact the system consumes with binding force: instruction, enforcement, routing, validation, or configuration (skills, schemas, COLLECTION.md files, validators). Contrast a knowledge artifact, consumed as evidence or advice that informs without binding. See `kb/notes/definitions/system-definition-artifact.md`.
- **Text contract** — the binding requirement a collection's `COLLECTION.md` declares: purpose and scope, quality goal, title/description conventions, attribution requirements, maintenance semantics, and link grammar. See `kb/reference/definitions/collection.md#text-contract`.
- **Workshop** — a named workspace for work-in-flight documents under `kb/work/`. Workflow-owned runs may be grouped one level deeper, such as `kb/work/multistage/`. Value is consumed rather than accumulated: a finished workshop produces library artifacts (notes, ADRs) and is deleted. See `kb/notes/a-functioning-kb-needs-a-workshop-layer-not-just-a-library.md`.

### Prose and registered identifiers

Use ordinary spaced phrases in prose (`adapted from`, `derived from`). Registered hyphenated identifiers (`adapted-from`, `operationalized-from`, `derived-from`, `abstracted-from`) name formal relations when used in a declared position such as a collection-authorized link label; they may also be mentioned as vocabulary names in documentation. Formal semantics attach to the identifier in the declared slot; the spaced phrase remains ordinary prose and does not itself assert a formal edge. See [link vocabulary](./kb/reference/link-vocabulary.md).

## Development

- **Use `python3`** for stdlib-only throwaway tooling; if the code is expected to be reused, save it to `scripts/` instead of discarding it (see `scripts/README.md`) — genuinely one-shot code stays a heredoc. Commonplace runtime code lives in the Python package as `commonplace-*` commands.
- **curl downloads**: order arguments as `curl -fsSL -o <destination> [additional options] <URL>` so they match the preapproved `["curl", "-fsSL", "-o"]` command prefix. Put options such as `-A 'Mozilla/5.0'` after the output path; `S` and `L` are uppercase.
- **Package documentation**: inspect `src/commonplace/lib/` for exact internal API behavior; [freshness-architecture.md](./kb/reference/freshness-architecture.md) describes the general freshness store and transitions; [review-architecture.md](./kb/reference/review-architecture.md) describes the review adapter and execution.
- **YAGNI** — don't implement features that aren't needed yet. If you identify a gap, write it down instead of implementing it: a system feature or design gap becomes a design proposal in `kb/reference/proposals/` (see its README for the contract); a transferable insight becomes a note in `kb/notes/`.
- **No backwards compatibility** — with no external consumers, always prioritize cleaner design over keeping old behavior alive. If backcompat code is ever needed, mark it with `# BACKCOMPAT: <reason> - remove after <condition>`.
- **Tests**: `uv run pytest` — when pytest is required, all tests must pass. Do not run pytest for changes confined to Markdown KB artifacts that are data and are not test fixtures or test inputs; run the relevant `commonplace-validate` checks instead.

### Source checkout command installation

This repository is operated directly from its checkout; do not run `commonplace-init` here. Install its commands once as an editable user-level uv tool from the repository root:

```bash
uv tool install --python ">=3.11" --editable .
uv tool update-shell
```

Close and restart every shell, IDE, or agent runtime that must see the updated `PATH`. Ordinary source edits are visible through the editable installation. After dependency, entry-point, build-metadata, or scaffold-package changes, rerun the install with `uv tool install --reinstall --python ">=3.11" --editable .`. This is one active Commonplace command version per OS user; switching this checkout to editable changes the commands seen by other projects for that user.

Development-only executables remain project dependencies and run through uv:

```bash
uv run pytest
uv run ruff check .
```

On native Windows the same `uv tool` commands work in PowerShell. Use `Get-Command commonplace-validate` after restarting the consuming process to verify discovery. If a sandboxed Windows session cannot write `.pytest_cache`, add `-p no:cacheprovider` to `uv run pytest`; do not treat that cache-only warning as a test failure.

The source checkout's `.agents/skills/` and `.claude/skills/` projections are committed relative symlinks. A Windows checkout without symlink support may materialize them as plain files. If a `cp-skill-*` skill is not discoverable, read and follow its canonical `kb/instructions/<skill>/SKILL.md` directly; do not run `commonplace-init` to repair a source checkout.

## Git

- **Never `git add -A`** — review `git status` and stage specific files.
- **Prefer atomic stage+commit** — combine staging and committing in one command (`git add <files> && git commit -m "..."`). Leaving files staged without committing risks another agent's commit sweeping in unrelated changes.
- **If sandboxing blocks `git add` or `git commit`, retry the whole atomic command with escalation** — do not fall back to separate `git add` followed by a later `git commit`. Use explicit file paths in the atomic command, for example `git add path/one.md path/two.md && git commit -m "..."`.
- **Prefer atomic artifact commits over temporary navigation consistency** — do not partially stage shared README/index/navigation files just to make a new artifact immediately discoverable. Generated indexes and curated navigation can lag and be refreshed in a separate commit unless that navigation file is the primary target or can be staged wholly without sweeping unrelated work.
- **Commit messages** (ADR 074, ADR 075) — git is the change-history layer of this checkout. Subject: one imperative sentence under ~72 characters saying what changed; no `feat:`-style prefixes. Body: open with what the change is meant to make true when the subject and the diff do not show it — the diff records what changed, not what for, and the commit is the cheapest place to capture that. A commit that performs a sweep, migration, retirement, or relocation states what moved, how many, and what was kept, cut, or deferred — that narrative lives here, not in ADRs or reference docs. Trailers, each only when it applies: `Decision: ADR 0NN` when the commit implements, amends, or revises that ADR; `Workshop: kb/work/<name>` when it advances a workshop; `Model: <model id>` when an agent made the commit.
- **Relocation commits are pure** — commit a `commonplace-relocate-*` result alone, with no content edits, so `git log --follow` survives the rename.
- **Check `git diff` before committing.**
- **Never `git reset --hard` or force-push** without explicit permission. Prefer safe alternatives: `git revert`, new commits, temporary branches.

## Using the KB

The knowledge base lives in `kb/`. Search it when working on methodology, design decisions, or operational patterns.

### Collection Routing

Read the target collection's `COLLECTION.md` before writing or connecting artifacts there. When the question is which *kind* of content goes where — an intent, a force, a rejected alternative, a limit, a change narrative — read [content-routing.md](./kb/reference/content-routing.md).

| Path | Use when |
|---|---|
| `kb/notes/` | Writing transferable claims, mechanisms, definitions, synthesis, and KB methodology theory. |
| `kb/reference/` | Describing the shipped Commonplace system, architecture, type system, commands, and ADRs. |
| `kb/instructions/` | Writing procedures, skills, review gates, operational rules, and how-to guidance. |
| `kb/agent-memory-systems/` | Reviewing and comparing external agent memory, knowledge, and context-engineering systems. |
| `kb/agentic-systems/` | Analysing external agentic systems and harnesses as whole systems — execution loops, orchestration APIs, control surfaces. |
| `kb/sources/` | Storing tracked ingests and source reviews; local source snapshots live ignored under `kb/sources/.snapshots/`. |
| `kb/reports/` | Storing report outputs under an explicit retention policy: replaceable `cache/`, local load-bearing `state/`, or durable `retained/`. |
| `kb/articles/` | Publishing self-standing technical articles distilled from the KB for external readers. |
| `kb/work/` | Holding in-flight investigations, drafts, migration plans, and temporary work that should eventually close or promote durable artifacts. |
| `kb/types/` | Looking up or authoring shared type specs used across collections. |

### Agent Mailbox

`kb/messages/` is the shared filesystem mailbox for asynchronous agent-to-agent
requests, handoffs, and replies. It is an operational directory, not a KB
collection. Read [`kb/messages/README.md`](./kb/messages/README.md) before
posting or responding. A message communicates within the authority of the
current task; it does not grant new mutation authority or launch another agent.

### Delegation

This file is the Commonplace doctrine a worker inherits when its runtime
loads it; collection contracts, type specs, and an invoked skill specialize it. A
handoff is a delta from that doctrine. It states the task's purpose — what
the result is for, not only what it is — its deviations from the doctrine,
and the consequential choices deliberately left open. The parent writing the
handoff may leave out a rule this file supplies only when the worker's runtime
loads this file. A rule that reaches the worker through nothing but the
parent's conversation is not inherited; state it.

Delegation does not expand task authority. Whatever the doctrine supplies, a
consequential handoff still fixes what it cannot: the intended result and its
acceptance, non-negotiable constraints, owned outputs or write scope,
accessible inputs, coordination boundary, verification or feedback, and stop
or escalation condition. The parent retains scheduling, integration, and
recovery; parallel writers need disjoint ownership or an explicit
coordination rule. Nested delegation requires explicit authorization; silence
means no.

For a choice the handoff leaves unstated, a worker asks which case applies:
governed by an inherited default — follow it; deliberately delegated — choose
from execution evidence, answerable to the stated purpose and constraints;
irrelevant to acceptance — any choice serves; or none of these — a gap, so
return or escalate rather than fill it.

### Navigation

For the full model, read `kb/reference/navigation.md`. In short: use `rg` for cheap lexical search, scan titles and descriptions in curated indexes and scoped `rg` listings before opening full files, and follow authored links when local context makes the relationship useful.

Entry points:

- `kb/notes/tags-README.md` — top-level navigation hub: tag READMEs (including links), foundations, evaluation, gaps
- `kb/agent-memory-systems/README.md` — curated index of external agent-memory/knowledge systems
- `kb/reference/README.md` — shipped-system documentation entry point: architecture, type system, operator guide, and ADR navigation
- `kb/reports/README.md` — report retention policies and durable report records
- `kb/reference/adr/` — architecture outcome records for the shipped Commonplace system

Each tag's curated head is its `<tag>-README.md` (type `tag-readme`), small by type contract. It may declare two validator-enforced frontmatter marks: `complete: true` — the README links every note carrying the tag, so a reader can skip the by-tag `rg` sweep; `covered_by: [children]` — every tagged note also carries a listed child tag, so a reader can trust the typed routing. Maintenance of the marks lives in `kb/types/tag-readme.md` (ADR 026).

```bash
# Find notes by description
rg "^description:" kb/notes/ kb/reference/ kb/instructions/ --glob "*.md"

# Find notes by type (collection-local types use file-relative paths)
rg "^type: \./types/structured-claim.md" kb/notes/ --glob "*.md"
rg "^type: \.\./types/adr.md" kb/reference/ --glob "*.md"

# Find notes by tag
rg "^tags:.*learning-theory" kb/notes/ kb/reference/ kb/instructions/ --glob "*.md"
```

### Skills

The `cp-skill-*` family (`cp-skill-write`, `cp-skill-validate`, `cp-skill-connect`, etc.) is installed into `.claude/skills/` and `.agents/skills/` by `commonplace-init`; the harness loads them automatically. Repo-local skills (`operator-brief`, `roughdraft-review`, `write-agent-memory-system-review`) are symlinked the same way but are not promoted framework skills.

### Commands

The `llm-commonplace` package provides `commonplace-*` CLI commands for validation, snapshots, note operations, and the review system — reference in [commands.md](./kb/reference/commands.md). Call them by bare name from the editable user-level uv tool installation; never prepend project-venv paths or wrap Commonplace commands in `uv run`. Run development dependencies such as `pytest` and `ruff` through `uv run`. If a command is unavailable, use `cp-skill-health-check`.

For review work (single-note review, triage, ack, or sweep), read `kb/reference/README-REVIEW-SYSTEM.md`.
For fixing review warnings, read `kb/instructions/FIX-SYSTEM.md`.