Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .claude/agents/architect.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ memory: project

- Before implementing a spec whose territory touches more than one crate, or that extends another spec's files
- When asked to "plan", "design", "decompose", or "think through" an approach
- To validate a proposed change against the thesis (spec 002), the constitution, and the frozen invariants
- To validate a proposed change against the thesis (spec 002), the constitution, and the memory invariants
- When a build session finds the spec imprecise and must decide before coding (the decision becomes a D-n entry)

## aicortex Context
Expand Down Expand Up @@ -56,7 +56,7 @@ Read the spec (or request). Identify the layer, the crate, every file in `establ
### 3. Validate Against the Corpus

- Does the approach stay inside the spec's Territory? A file outside it needs an `extends` edge or belongs to another spec.
- Does it hold the frozen invariants? Anything that changes a golden vector, adds a clock or map-order dependency to a hashed path, or writes authoritatively from L5 up is a stop, not a plan step.
- Does it hold the memory invariants? Anything that splits a capture from its outbox work, stores a memory without provenance or a trust class, compares vectors across models, returns recalled content as instruction, loads a SQLite extension, or reimplements a chassis responsibility is a stop, not a plan step.
- Does it keep dependencies pointing downward, and does it consume rahi rather than reimplement it?
- Does it need a new third-party crate? Then the plan includes the `[workspace.dependencies]` entry and the `extends` edge on spec 010.
- Will the derived artifacts need regenerating (`spec-spine compile && spec-spine index`)? Almost always yes.
Expand All @@ -67,7 +67,7 @@ Ordered, atomic steps. For each: **What** (files), **Why** (the B-n, FR, or prin

### 5. Identify Risks

- **Invariant risk**: any step near hashed bytes, signatures, or cache trust
- **Invariant risk**: any step near the capture transaction, the write gate, embedding storage, the recall path, or the MCP surface
- **Coupling drift**: a file the plan touches that no edge covers
- **Ownership debt**: a new file not yet in `establishes` (`C-002`)
- **Spec silence**: a decision the spec does not make; name it so the session records a D-n
Expand Down Expand Up @@ -110,15 +110,15 @@ Ordered, atomic steps. For each: **What** (files), **Why** (the B-n, FR, or prin
- **DO:** Keep each step verifiable by one command
- **DO NOT:** Modify files; this agent is read-only
- **DO NOT:** Plan around the gate or the ownership ratchet
- **DO NOT:** Propose regenerating a golden vector
- **DO NOT:** Propose relaxing a memory invariant; that is a human decision

## What to remember (project memory)

This agent writes to `.claude/agent-memory/architect/MEMORY.md`. Record patterns that recur across decompositions, not plans for specific specs:

- **Spec-shape patterns**: edge combinations that keep the gate clean for a class of change (a crate extension, a new predicate, a new CLI verb)
- **Spec-shape patterns**: edge combinations that keep the gate clean for a class of change (a crate extension, a new source adapter, a new MCP tool)
- **Decomposition pitfalls**: wrong cuts seen proposed (splitting a spec's code and its `establishes` growth across PRs; putting a dependency in a crate manifest without the workspace table)
- **Latent constraints**: invariants that emerge from how the crates compose rather than from one spec
- **Reusable plan skeletons**: the standard shape for "found a crate", "add a module", "add a fact kind", "add a predicate"
- **Reusable plan skeletons**: the standard shape for "found a crate", "add a module", "add a source adapter", "add a curator"

Do not record plans for specific specs, reactions to one conversation, or generic engineering advice.
2 changes: 1 addition & 1 deletion .claude/agents/explorer.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ mutation: read-only

- To understand how a layer, crate, or module works, or is specified to work
- To trace a `depends_on` chain, an `extends` chain, or a crate dependency chain
- To find every spec that claims a path, every fact kind, every predicate, every seam
- To find every spec that claims a path, every source adapter, every MCP tool, every seam
- To answer "where is X specified?", "what depends on Y?", "which spec owns Z?"
- Before planning a change, to gather the current state of affected specs and code

Expand Down
4 changes: 2 additions & 2 deletions .claude/agents/implementer.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Read the files that will change and the seams the dependency specs expose (trait
### 3. Make Minimal Changes

- Prefer `Edit` for existing files, `Write` for new files
- Match surrounding style; owned data, no lifetimes at public boundaries, `BTreeMap` never `HashMap` in the L0/L1 crates
- Match surrounding style; owned data, no lifetimes at public boundaries, `BTreeMap` never `HashMap` in anything that reaches a hashed manifest or a deterministic recall trace
- One concern per change; do not refactor beyond the plan
- New file? Add it to the spec's `establishes` in the same change
- New dependency? Root `[workspace.dependencies]` plus `workspace = true` in the crate, plus the `extends` edge on spec 010's `Cargo.toml` section `workspace.dependencies`
Expand Down Expand Up @@ -102,6 +102,6 @@ Files changed with paths, verification results, deviations from the plan, and an
- **DO:** Stop and report when the spec is wrong rather than silent (coherence guard)
- **DO NOT:** Design or architect; ask for a plan if the spec is unclear
- **DO NOT:** Edit `.derived/`
- **DO NOT:** Regenerate a golden vector, ever
- **DO NOT:** Edit the evaluation corpus or its baseline to make a retrieval delta pass
- **DO NOT:** Amend an owning spec's contract to make the gate pass
- **DO NOT:** Combine multiple plan steps into one large edit
8 changes: 4 additions & 4 deletions .claude/agents/reviewer.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: reviewer
description: Use this agent to review aicortex changes for bugs, correctness, spec compliance, the ownership ratchet, and the frozen invariants. Triggered after implementation, or when asked to review, audit, or check recent changes.
description: Use this agent to review aicortex changes for bugs, correctness, spec compliance, the ownership ratchet, and the memory invariants. Triggered after implementation, or when asked to review, audit, or check recent changes.
tools:
- Read
- Grep
Expand All @@ -15,7 +15,7 @@ memory: project

# Reviewer: Post-Change Review

**Role**: Read-only review agent that examines recent changes for correctness, security, determinism, compliance with the owning spec, and the ownership ratchet. Provides structured, actionable feedback. Never modifies files. Delegates L0/L1 and trust-plane depth to `ledger-guardian` and `trust-reviewer` when the diff touches their paths.
**Role**: Read-only review agent that examines recent changes for correctness, security, determinism, compliance with the owning spec, and the ownership ratchet. Provides structured, actionable feedback. Never modifies files. Applies `.claude/rules/memory-invariants.md` rule by rule when the diff touches the store, gate, embed, index, recall, or mcp crates.

## When to Use

Expand Down Expand Up @@ -102,11 +102,11 @@ make spine: [ok/FAIL] | coverage: [n claimed, m unclaimed]

- **DO:** Review every changed file
- **DO:** Run the gate and quote its output as evidence
- **DO:** Delegate depth to the specialist agents on their paths
- **DO:** Report every memory invariant as held, violated, or not applicable when its crate is touched
- **DO:** Cite `file:line` and B-n labels
- **DO NOT:** Modify any files
- **DO NOT:** Nitpick style that matches surrounding code
- **DO NOT:** Approve a change that regenerated a golden vector or added an authoritative write above L4
- **DO NOT:** Approve a change that splits a capture from its outbox work, stores a memory without provenance, compares vectors across models, returns recalled content unlabelled, or leaves embeddings behind after erasure

## What to remember (project memory)

Expand Down
18 changes: 9 additions & 9 deletions .claude/skills/build/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ code.
{
"id": "<spec-id>/D-n",
"specId": "<spec-id>",
"scope": ["<spec-id>", "crates/aicortex-ledger/src/entry.rs"],
"scope": ["<spec-id>", "crates/aicortex-recall/src/fusion.rs"],
"title": "one line",
"decision": "what was chosen",
"rationale": "why",
Expand All @@ -89,7 +89,7 @@ code.

## Step 3: implement inside the territory (steps 4 and 5)

- Every new file under `crates/`, `fuzz/`, `executor/`, or `web/` is
- Every new file under `crates/`, `apps/`, `eval/`, `docker/`, or `deploy/` is
claimed in this spec's `establishes` in the same change (the ownership
ratchet: `spec-spine index coverage --fail-on-untraced` refuses an
unclaimed file and `couple` refuses a changed one).
Expand All @@ -99,11 +99,11 @@ code.
with `workspace = true`. Always `--locked`.
- Touching a file another spec owns needs an `extends` edge on that
spec's unit, declared in this spec's frontmatter.
- The frozen invariants (step 5): nothing that reaches a hashed byte may
depend on a clock, an environment read, a float, or `HashMap`
iteration. A change to any golden vector under
`crates/aicortex-types/testdata/vectors/` is a schema MAJOR and a human
decision: stop and report, never regenerate.
- The memory invariants (step 5): `.claude/rules/memory-invariants.md`
is the checklist. A change to chunking, embedding, ranking, or fusion
runs the evaluation corpus and reports the delta; the corpus and its
baseline are never edited to make the delta pass. A change that needs
an invariant relaxed is a human decision: stop and report.
- Do not edit `.derived/` by hand.

Use the `implementer` agent for focused sub-tasks and `explorer` for
Expand All @@ -118,7 +118,7 @@ make ci # spine + index coverage --fail-on-untraced + build, test, clippy -
```

Both exit 0, or the commit waits. Then `/commit` with the spec ordinal as
scope (`feat(017): ...`), staging the regenerated `.derived/` shards with
scope (`feat(012): ...`), staging the regenerated `.derived/` shards with
the code they describe. Commit in coherent slices; a red gate is fixed,
not committed around.

Expand Down Expand Up @@ -148,7 +148,7 @@ next spec.
- A dirty tree, the wrong branch, or a red `make spine` in preflight.
- A `draft` spec, an unmet dependency, or a missing operator prerequisite.
- A contradiction between the spec and what the code must do.
- A golden vector that would change.
- A memory invariant that would have to be relaxed.
- A coupling failure that only a spec rewrite or a `Spec-Drift-Waiver:`
could clear: a driven session never self-approves a waiver.
- A `PreToolUse` hook refusal (exit 2): it is a stop, not an obstacle.
14 changes: 6 additions & 8 deletions .claude/skills/cleanup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,12 +43,11 @@ You are a cleanup analyzer for aicortex. Analyze and report; change nothing.
--locked -- -W dead_code -W unused 2>&1 | grep -E "unused|dead|never
used"`; `cargo udeps --workspace` if installed (nightly), otherwise a
manual pass over each crate's `[dependencies]` against its `use` lines.
TypeScript (`web/`): `npx --no-install knip --no-exit-code` if present.
Fallback for orphan files: a source file under `crates/*/src/` that no
`mod` declaration or `use` path references.

**B. Duplicates.** A duplicate detector if installed (`jscpd` for TS,
`simian` or `cpd` for Rust); otherwise surface near-identical `pub fn`
**B. Duplicates.** A duplicate detector if installed (`simian` or `cpd`
for Rust); otherwise surface near-identical `pub fn`
signatures across crates with `grep -rn "^pub fn" crates/*/src | awk -F:
'{print $3}' | sort | uniq -d`. Treat results as hints.

Expand All @@ -59,11 +58,10 @@ categorizing.

Keep (false positives): anything under `.derived/` (compiler output);
generated code (`build.rs` outputs, prost modules under `target/`); trait
implementations reached only through dynamic dispatch seams (`Signer`,
`Verifier`, `IssuerResolver`, `ObjectStore`, `Projection`); public API of
library crates consumed by `aicortex-cli` or `aicortex-cli`; test fixtures
and `testing` feature builders; workflow and hook scripts;
golden vectors (never touch, spec 012).
implementations reached only through dynamic dispatch seams (rahi's
`Cell`, `SourceAdapter`, `RemoteProvider`, curator and tool registrations);
public API of library crates consumed by `apps/aicortex`; migrations; test
fixtures and the evaluation corpus under `eval/`; workflow and hook scripts.

Safe to remove: private items clippy flags as never used with no
suppression; dependencies with zero usage in their crate; files no spec
Expand Down
11 changes: 6 additions & 5 deletions .claude/skills/code-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
---
name: code-review
description: "Review the current diff for correctness bugs and spec drift with make spine as the gate, delegate L0/L1 and trust-plane paths to ledger-guardian and trust-reviewer, and emit an evidence-oriented findings list"
description: "Review the current diff for correctness bugs and spec drift with make spine as the gate, check the store, gate, embed, index, recall, and mcp paths against the memory-invariants rule, and emit an evidence-oriented findings list"
allowed-tools: Read, Grep, Glob, Agent, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*), Bash(git rev-parse:*), Bash(git fetch:*), Bash(spec-spine:*), Bash(make:*), Bash(cargo:*), Bash(grep:*)
argument-hint: "[scope] - e.g. \"branch\", \"working tree\", \"crates/aicortex-ledger\""
argument-hint: "[scope] - e.g. \"branch\", \"working tree\", \"crates/aicortex-recall\""
---

# /code-review: correctness, spec drift, frozen invariants
# /code-review: correctness, spec drift, memory invariants

Reviews the current diff against three questions: does the change have
correctness or edge-case bugs, does it still match its owning spec's
contract, and can it alter a hashed byte or let something unverified
count as verified. Output is an evidence-oriented findings list, each
contract, and does it relax a memory invariant (capture in one `txn`,
provenance and trust class on every memory, every vector naming its
model, recalled content labelled untrusted, erasure reaching embeddings). Output is an evidence-oriented findings list, each
line citing `file:line`. Nothing authored is modified; `make spine`
regenerates `.derived/` deterministically, and a diff it leaves is itself
evidence (stale shards).
Expand Down
12 changes: 6 additions & 6 deletions .claude/skills/commit/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: commit
description: "Create a git commit with an impact-focused conventional commit message whose scope is the spec ordinal (feat(017): ...), with the regenerated .derived/ shards staged alongside the change they describe."
description: "Create a git commit with an impact-focused conventional commit message whose scope is the spec ordinal (feat(012): ...), with the regenerated .derived/ shards staged alongside the change they describe."
allowed-tools: Bash
argument-hint: "[optional note about the change]"
---
Expand Down Expand Up @@ -44,7 +44,7 @@ Format: `type(scope): subject`
**Type (required):** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`.

**Scope:** the three-digit ordinal of the spec the change implements or
amends: `feat(017): ...`, `fix(011): ...`, `docs(024): ...`. Harness and
amends: `feat(012): ...`, `fix(011): ...`, `docs(024): ...`. Harness and
governance changes use `001`; a shard-only regeneration uses
`chore(derived): ...`; a dependency bump on the workspace table uses
`chore(010): ...`.
Expand All @@ -55,10 +55,10 @@ governance changes use `001`; a shard-only regeneration uses
- No trailing period. No emojis. No em dash.

**Good versus bad:**
- BAD: `refactor(017): extract helper for parent sorting`
- GOOD: `feat(017): ledger entries reject unsorted or duplicate parents`
- BAD: `feat(032): add new subcommand handler`
- GOOD: `feat(032): hq status reports the four spec-spine exit codes`
- BAD: `refactor(013): extract helper for verdict mapping`
- GOOD: `feat(013): the write gate quarantines captures with no provenance`
- BAD: `feat(021): add new tool handler`
- GOOD: `feat(021): the MCP server answers 401 with resource metadata`

**Body (optional):** separate from the subject with a blank line. Use
dash-prefixed bullets only for multiple distinct changes. Keep lines under
Expand Down
6 changes: 3 additions & 3 deletions .claude/skills/implement-plan/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@ Per task:

Rules: read the entire plan before starting; keep the plan in sync after
every task, not in batches; never commit unless asked (`/commit` when
asked); never disable or skip a failing test; never regenerate a golden
vector; claim every new source file in the spec whose territory it joins
asked); never disable or skip a failing test; never edit the evaluation
corpus to make a delta pass; claim every new source file in the spec whose territory it joins
(the ownership ratchet, `C-002`); preserve the plan's structure.

Mid-implementation checkpoint at 50 percent: report done, issues,
Expand Down Expand Up @@ -99,4 +99,4 @@ the user, never by this skill.
| Test or build failure | fix; if unfixable, mark the task blocked and continue with independent tasks |
| Ambiguous task | ask |
| Coupling failure | surface the drift; never patch the spec to match the code |
| Golden vector mismatch | stop; a human decides (schema MAJOR) |
| Memory invariant would be relaxed | stop; a human decides |
12 changes: 6 additions & 6 deletions .claude/skills/refactor-claude-md/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ index: every change here couples to `specs/001-agentic-harness/spec.md`
```markdown
---
paths:
- "crates/aicortex-eval/**"
- "crates/aicortex-recall/**"
---

Two or three key points, and the doc to read: `docs/<name>.md`.
Expand All @@ -53,7 +53,7 @@ index: every change here couples to `specs/001-agentic-harness/spec.md`

- Extract only context-specific guidance; keep universal rules in
`CLAUDE.md`.
- Preserve critical information in `CLAUDE.md`: the frozen invariants,
- Preserve critical information in `CLAUDE.md`: the memory invariants,
the commands, the architecture table, the governance mechanics, house
style.
- Meaningful globs: a rule that loads everywhere is a `CLAUDE.md` section
Expand All @@ -63,13 +63,13 @@ index: every change here couples to `specs/001-agentic-harness/spec.md`
## Good extraction candidates in this repository

- Per-crate implementation notes once a crate has shipped (for example
the REAPI digest mapping for `crates/aicortex-eval/**`).
- Testing patterns (fixture ledgers, the `testing` feature builders).
- The web client's conventions (`web/**`).
the fusion and trace format for `crates/aicortex-recall/**`).
- Testing patterns (fixture memories, the evaluation corpus under `eval/`).
- Deployment notes for `docker/**` and `deploy/**`.

## Keep in CLAUDE.md

- The frozen invariants and the hash-stability rule.
- The memory invariants and the chassis-consumed-never-forked rule.
- Commands and exit codes.
- The layer-to-crate table.
- Governance mechanics (ownership ratchet, committed `.derived/`, hooks).
Expand Down
8 changes: 4 additions & 4 deletions .claude/skills/research/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,13 @@ Decide: query type, agent count, domains (corpus, codebase, external
docs, papers, general web), and scope (corpus-only, web-only, hybrid).

- **Corpus questions** ("what does spec 020 say about erasure", "who owns
`crates/aicortex-ledger/src/order.rs`", "what depends on 064"): use the
`crates/aicortex-recall/src/fusion.rs`", "what depends on 018"): use the
`explorer` agent with `spec-spine registry show|relationships <id>`,
`spec-spine index render`, `Grep` over `specs/`, and `git log`. Never
parse `.derived/` directly.
- **External questions** (REAPI digest functions, BAO range proofs,
Biscuit datalog, Willow reconciliation, Sigstore bundle format, hiqlite
Raft semantics): `WebSearch` and `WebFetch`, preferring primary sources
- **External questions** (the MCP streamable HTTP transport, OAuth
protected resource metadata, embedding model normalization, hybrid
ranking fusion, hiqlite Raft semantics): `WebSearch` and `WebFetch`, preferring primary sources
(specifications, RFCs, the library's own docs).
- Many questions are hybrid; split them across agents by domain.

Expand Down
Loading