charter
An agent harness for spec-driven development.
Star
Fork
Watch
charter spec indexing.md
1.5 kB · 53 lines
Markdown
at main

id: indexing kind: architecture title: Indexing status: active #

Indexing #

Charter needs an index so agents can find the relevant parts of the spec without rereading every document on every turn.

The first index is deliberately lexical and inspectable. It is not a semantic vector store yet. A dumb index that exists beats an elegant index that lives only in a diagram.

Command #

charter index

The command scans the current projection and builds a lexical index over document ids. The prototype writes .spec/state/index.json as a disposable local cache. The target model is still database-native: index rows or derived query state attached to the same document ids, not an authoritative filesystem artifact.

Indexed fields #

For each spec document:

  • document id
  • path
  • title
  • kind
  • status
  • hash
  • heading outline
  • Markdown links
  • wikilinks
  • normalized lexical terms

The index also contains:

  • pathIndex: spec path to document id.
  • termIndex: term to document ids.
  • backlinks: target document id or path to source document ids.
charter search agent runtime

Search is term-overlap over the current in-memory index built from the projection. It can later use persisted index rows or a semantic adapter, but the command should remain stable.

Future semantic layer #

Semantic indexing should be an adapter over the same document ids, not a replacement for the lexical index. Agents need stable ids, hashes, and provenance before they need vibes with cosine similarity.