context-update

Project lexicon updater

Maintain the project's semantic lexicon at .roc/rocket/lexicon.md: a compact, structured catalog of project-specific concepts, vocabulary, recurring patterns, roles, and decisions. The lexicon is read by rocket:spec-writer, rocket:spec-maker, and other agents to align their vocabulary with the user's. This skill is the only writer.

The skill runs in three modes:

• Hook mode (scoped) — invoked by the Stop hook through the wrapper script plugins/rocket/hooks/update-context.sh. The wrapper runs a multi-stage pipeline (heuristic pre-filter, Haiku gate) before spawning a Sonnet subprocess with a scoped prompt containing only pre-validated candidate concepts. The summary is logged but not surfaced to the user.
• Hook mode (v1 fallback) — if the context-gate binary is not available, the wrapper falls back to the v1 behavior: tail 500 lines of the transcript and pipe to Sonnet directly. This ensures zero regression on platforms without the binary.
• Manual mode — invoked by the user via /rocket:context-update or auto-invoked by Claude on a semantic shift. The forked context provides the full conversation; the summary is surfaced to the user. Manual mode bypasses the toggle, heuristic, and Haiku gate entirely.

Output contract

• Write .roc/rocket/lexicon.md (and only that file) atomically via .roc/rocket/lexicon.md.tmp + mv, protected by an mkdir-based atomic lock at .roc/rocket/lexicon.md.lock.d/ (POSIX-portable; flock is not available by default on macOS).
• The file conforms to the Lexicon format below. No deviation.
• Final output to the caller is a single short paragraph: counts of added / merged / flagged entries, names of flagged entries. No prose elaboration. No emojis.
• If the lexicon is unchanged after analysis, output "No update needed." and do not rewrite the file.

Lexicon format

<!-- Auto-maintained by rocket:context-update. Edits are preserved when consistent. -->

## <Area name>

### <Concept>
- **Definition**: <one-line definition>
- **Aliases**: <comma-separated synonyms, or "none">
- **Relations**: <comma-separated concept names, or "none">
- **Source**: <free-form citation>

### <Concept>
[...]

## <Other area>
[...]

Rules enforced on every write:

• Header comment is always the first line.
• Each entry has exactly the four bullet keys above, in that order. No additional bullets, no surrounding prose.
• Areas are sorted alphabetically. Concepts within each area are sorted alphabetically.
• No two entries share a concept name within the same area.
• No two areas share a name.
• Every value listed in Relations resolves to an existing concept name in the file.
• Total size cap: 300 lines OR 12 KB, whichever smaller. If exceeded after merge, prune per Step 5.

Areas are project-defined groupings (e.g. Domain, Architecture, Roles, Conventions, Decisions). Create them on first need; merge them when their meaning overlaps.

Scoped mode

When invoked with a Candidates: block in the prompt (the Sonnet writer path from the hook pipeline), the skill operates in scoped mode:

1. Skip Step 1's transcript reading — do not read from stdin or the conversation context. The candidates are already identified.
2. Skip Step 2's full extraction — do not scan the conversation for new concepts. The pre-classifier has already done this.
3. Take the candidate list as given and run Steps 3–7 against it: deduplicate against the existing lexicon, reconcile contradictions, prune if needed, render and write.

The scoped prompt format (generated by context-gate format-writer-prompt) is:

/rocket:context-update

Integrate these candidate concepts into the project lexicon at
`.roc/rocket/lexicon.md`. The candidates were identified by a pre-classifier
from the latest conversation turn.

Candidates: <comma-separated candidate names>

Existing lexicon:
<full lexicon content>

Project conventions (from CLAUDE.md):
<CLAUDE.md content>

Run the context-update workflow (Steps 2-7) for these candidates only.
Do not re-analyze the full conversation -- the candidates are pre-validated.

When this format is detected, enter scoped mode automatically.

Workflow

Step 1 — Load context

1. Read .roc/rocket/lexicon.md. If absent, treat the existing lexicon as empty.
2. Read the conversation transcript:
   • Hook mode: read from stdin (the wrapper pipes the transcript JSONL).
   • Manual mode: use the conversation context inherited by the fork.
3. Read the project's CLAUDE.md (root only) for tone and language conventions to match.

Step 2 — Extract candidates

Identify nouns and noun phrases that name:

• Domain concepts specific to the project (not generic technical vocabulary).
• Architectural elements (services, modules, boundaries, named patterns).
• Recurring patterns the user has named or described.
• Roles (human or system) the project distinguishes.
• Decisions the user has stated explicitly ("we decided to...", "the rule is...").

Discard generic technical vocabulary (HTTP, SQL, REST, "webhook" in the abstract). Keep them only when the project gives them a specific local meaning.

Step 3 — Deduplicate

For each candidate, compare against existing entries by semantic match, not string match:

• Existing entry covers the same concept and the candidate adds new information → merge into the existing entry, keep the existing concept name as the canonical label.
• Existing entry covers the same concept and the candidate restates the same info → skip.
• Existing entry covers the same concept under a different label → add the candidate's label to Aliases.
• No matching entry → new entry. Place it in the most appropriate existing area, or create a new area if none fits.

Step 4 — Reconcile contradictions

If a candidate contradicts an existing definition (different meaning under the same concept name, or incompatible relations):

• Append <!-- TODO: contradiction with <description> --> to the affected entry's Definition line.
• Do NOT silently overwrite.
• Surface the flag in the Step 7 summary.

Step 5 — Prune

After merging, render the lexicon and measure its size.

If the rendered file exceeds 300 lines OR 12 KB (whichever smaller):

1. Sort entries by Source recency (oldest first; "inferred" counts as oldest).
2. Drop entries that are not referenced by any other entry's Relations.
3. Never drop an entry marked with a <!-- TODO: contradiction ... --> comment.
4. Stop pruning as soon as the rendered file fits the budget.

If the budget cannot be met without dropping flagged entries, stop pruning and emit a warning in the summary.

Step 6 — Render and write

1. Compose the file with the header comment first, areas sorted alphabetically, concepts sorted alphabetically within each area, four bullets per entry in the order Definition / Aliases / Relations / Source.
2. Resolve the project root (use $CLAUDE_PROJECT_DIR if set, otherwise the cwd).
3. Acquire a non-blocking atomic lock by attempting mkdir .roc/rocket/lexicon.md.lock.d/. If the directory already exists (lock held), abort with the summary Lexicon update already in progress. rather than waiting — this matches the wrapper's skip-on-contention behaviour. Release the lock by rmdir at every successful return path.
4. Write the rendered content to .roc/rocket/lexicon.md.tmp.
5. mv .roc/rocket/lexicon.md.tmp .roc/rocket/lexicon.md (atomic on POSIX filesystems).
6. Release the lock.

If the rendered content equals the previous content byte-for-byte, skip the write (idempotent no-op).

Step 7 — Summary

Emit a single short paragraph:

Lexicon updated: <N> added, <M> merged, <K> flagged. Flagged: <comma-separated names or "none">.

If nothing changed: No update needed.

In hook mode, the wrapper captures this summary via stderr; do not add formatting that would garble the log. In manual mode, surface the summary directly to the user.

Idempotency rules

• A second invocation on the same conversation must produce a byte-identical lexicon file.
• Sorting, normalization (whitespace, comma spacing, trailing newlines), and merge order must therefore be deterministic.
• Do not include timestamps or run counters in the file.

Concurrency rules

• The mkdir lock on .roc/rocket/lexicon.md.lock.d/ is mandatory. Two simultaneous fires must serialize.
• The second invocation reads the freshly-updated lexicon (Step 1 re-runs after acquiring the lock) and only contributes incremental information.

Edge cases

• Lexicon does not exist: Step 1 treats it as empty. Step 6 creates it.
• Lexicon edited manually by the user: respect the edits unless they violate invariants (duplicates, dangling relations, missing keys). On invariant violation, mark the offending entry with a <!-- TODO: invariant ... --> comment instead of rewriting it.
• Transcript empty or trivial: emit "No update needed." and skip the write.
• .roc/rocket/ directory missing: create it before writing (mkdir -p .roc/rocket/).

What NOT to do

• Do NOT modify any file other than .roc/rocket/lexicon.md and the temp/lock siblings.
• Do NOT run shell commands beyond what is needed to acquire the lock and perform the atomic write.
• Do NOT include prose, examples, or commentary inside the lexicon file. Entries are definition + relationships only.
• Do NOT rename existing concept names unless merging duplicates. Stable names matter.
• Do NOT add entries for generic technical vocabulary that has no project-specific meaning.
• Do NOT surface the summary to the user when in hook mode (the wrapper handles logging).

Good summary examples

Lexicon updated: 2 added, 1 merged, 0 flagged. Flagged: none.

Lexicon updated: 0 added, 3 merged, 1 flagged. Flagged: Outbound webhook.

No update needed.

Bad summary examples

Hi! I added two new entries to the lexicon. The first one is about webhooks...

(Too verbose, friendly tone, restates content already in the file.)

Implementation notes

• Multi-stage pipeline (v2): the wrapper at plugins/rocket/hooks/update-context.sh orchestrates a pipeline: recursion guard, project toggle check (Background context: enabled in CLAUDE.md), debounce (300s), heuristic pre-filter (context-gate should-fire), Haiku gate classifier, then a scoped Sonnet writer. Each stage can exit early, reducing background cost by ~95% compared to v1.
• context-gate binary: a compiled Python binary at plugins/rocket/bin/context-gate with 7 subcommands (extract-delta, should-fire, format-gate-prompt, parse-gate-response, format-writer-prompt, update-cursor, read-cursor). Source at plugins/rocket/build/src/context_gate.py, built via plugins/rocket/build/build.sh (PyInstaller --onefile).
• Cursor-based delta tracking: the wrapper tracks the last processed transcript line in .roc/rocket/context-gate-state.json. Each fire processes only lines added since the last fire instead of re-tailing the last 500 lines. If the cursor exceeds the transcript length (rotation/truncation), extract-delta falls back to the last 500 lines.
• Per-project toggle: the Stop hook checks CLAUDE.md for - Background context: enabled. If the line is absent or says disabled, the hook exits immediately (zero cost). Manual /rocket:context-update is unaffected by the toggle.
• Fallback: if the context-gate binary is not found, the wrapper falls back to v1 behavior (30s debounce, tail 500 lines, pipe to Sonnet). A log warning is emitted.
• The wrapper reads the hook payload from stdin (JSON with a transcript_path field).
• The wrapper sets and exports ROCKET_CONTEXT_UPDATE_INVOKED=1 before spawning the claude -p subprocess to prevent recursion.
• The wrapper exits 0 unconditionally because this is an async hook; propagating the subprocess status would risk emitting exit code 2 (the Stop-hook block signal) into the user's main session.
• Both wrapper and skill use non-blocking atomic mkdir .roc/rocket/lexicon.md.lock.d/. Concurrent fires skip rather than queue.

Manual validation

Run these scenarios after any change to this skill, the wrapper, or the hook config. There is no automated test suite.

1. Cold start — fresh project with no .roc/rocket/ directory. Run /rocket:setup. Expected: .roc/rocket/lexicon.md created with the canonical header line, ## Project semantic context block inserted in CLAUDE.md.
2. First hook fire — finish one assistant turn that introduces a new domain concept. Expected: .roc/rocket/lexicon-update.log records start + end, lexicon receives a new entry, exit status 0.
3. No-op turn — finish a turn that introduces nothing new. Expected: log records the run; the skill's summary in the log says No update needed.; lexicon mtime unchanged; next turn fires again without infinite loop (the ROCKET_CONTEXT_UPDATE_INVOKED sentinel prevents recursion regardless of mtime).
4. Debounce — finish two assistant turns within 300 s, both updating the lexicon. Expected: second fire logs skip: debounced (...) and exits 0.
5. Lock contention — start two manual /rocket:context-update invocations simultaneously (or trigger one manually while a hook fire is in progress). Expected: one acquires the lock, the other logs skip: lock held by another invocation (wrapper) or emits Lexicon update already in progress. (skill).
6. claude CLI missing — temporarily remove claude from PATH. Expected: hook exits silently, no log entry, no error surfaced to the user.
7. Manual lexicon edit — edit .roc/rocket/lexicon.md by hand to add a malformed entry (e.g. missing Aliases bullet). Run /rocket:context-update. Expected: skill flags the entry with <!-- TODO: invariant ... --> rather than rewriting it; existing valid entries untouched.
8. Idempotent re-run — invoke /rocket:context-update twice in a row on an unchanged conversation. Expected: second invocation outputs No update needed. and does not rewrite the file.
9. Size cap — manually balloon the lexicon past 300 lines, then run the skill. Expected: oldest non-flagged, non-referenced entries pruned until the file fits.
10. Recursion guard — inspect the log of any successful run. Expected: never two consecutive start: lines without an intervening end:; never an exponential growth of log lines from a single user turn.