tlc-claude-code 2.4.2 → 2.4.4

package/.claude/commands/tlc/recall.md

@@ -1,87 +1,59 @@
-# /tlc:recall - Semantic Memory Search
-
-Search your project's memory by meaning. "What did we decide about X?"
-
-## Usage
-
-```
-/tlc:recall <query>
-```
-
-## What This Does
-
-1. Searches the vector memory store using semantic similarity
-2. Ranks results by: similarity (50%) + recency (25%) + project relevance (25%)
-3. Returns top-5 results with scores, types, and excerpts
-4. Permanent memories get a 1.2x boost in scoring
-
-## Options
-
-```
-/tlc:recall database architecture
-/tlc:recall --scope workspace authentication approach
-/tlc:recall --type decision deployment strategy
-/tlc:recall --limit 10 API design
-```
-
-| Flag | Values | Default | Description |
-|------|--------|---------|-------------|
-| `--scope` | `project`, `workspace`, `global` | `project` | Search scope (auto-widens if few results) |
-| `--type` | `decision`, `gotcha`, `conversation`, `all` | `all` | Filter by memory type |
-| `--limit` | 1-20 | 5 | Maximum results |
-
-## Process
-
-### Step 1: Parse Query
-
-Extract the search query and any flags from the arguments.
-
-### Step 2: Semantic Search
-
-1. Generate embedding for the query
-2. Search vector store for nearest neighbors
-3. Score results: `similarity * 0.5 + recency * 0.25 + projectRelevance * 0.25`
-4. Boost permanent memories by 1.2x
-5. Apply scope, type, and limit filters
-
-### Step 3: Display Results
-
-```
-## Memory Recall: "database architecture"
-
-1. **Use SQLite for vector storage** (92% match) [decision]
-   Date: 2026-02-09
-   Zero infrastructure, single file, ships with TLC
-   Source: memory/decisions/2026-02-09-use-sqlite-for-vector-storage.md
-
-2. **[PERMANENT] Always use WAL mode** (87% match) [gotcha]
-   Date: 2026-02-08
-   WAL mode required for concurrent reads during indexing
-   Source: memory/gotchas/2026-02-08-always-use-wal-mode.md
-
-3. **Database migration strategy** (81% match) [conversation]
-   Date: 2026-02-07
-   Discussed migration approach, decided on schema-first
-   Source: memory/conversations/2026-02-07-database-migration.md
-```
-
-### Step 4: Fallback
-
-If the vector store is unavailable (Ollama not running, no embeddings):
-- Falls back to keyword-based text search
-- Shows a notice that semantic search is unavailable
-
-## Examples
-
-```
-/tlc:recall what database should we use
-/tlc:recall deployment strategy --scope global
-/tlc:recall --type decision authentication
-/tlc:recall testing approach --limit 10
-```
-
-## Graceful Degradation
-
-- **No Ollama**: Falls back to text search with keyword matching
-- **Empty store**: Shows "No memories indexed yet" with guidance to run `/tlc:remember`
-- **No results**: Shows "No matching memories" with search suggestions
+# /tlc:recall - Team Memory Search
+
+Search TLC team memory using plain grep. This is intentional: no vector search, no extra services.
+
+## Usage
+
+```text
+/tlc:recall <query>
+```
+
+## What This Does
+
+1. Searches `.tlc/memory/team/` with `grep -rl "query" .tlc/memory/team/`.
+2. Looks in both `.tlc/memory/team/decisions/` and `.tlc/memory/team/gotchas/`.
+3. Shows the file path, date from the filename, and a matching excerpt.
+4. Uses grep only because it works everywhere.
+
+## Search Rules
+
+- Search both `decisions/` and `gotchas/`.
+- Do not use vector search.
+- Do not depend on embeddings, databases, or external services.
+- Prefer simple recursive grep so the command works across projects.
+
+## Process
+
+### Step 1: Find matching files
+
+```bash
+grep -rl "query" .tlc/memory/team/
+```
+
+### Step 2: Display matches
+
+For each matching file, show:
+
+- File path
+- Date parsed from the filename prefix
+- A short matching excerpt from the file body
+
+## Example Output
+
+```text
+Memory recall: "utc"
+
+File: .tlc/memory/team/decisions/2026-03-28-use-utc-timestamps.md
+Date: 2026-03-28
+Excerpt: Always use UTC timestamps in the database and in exported logs.
+
+File: .tlc/memory/team/gotchas/2026-03-21-local-time-breaks-reporting.md
+Date: 2026-03-21
+Excerpt: Local timezone conversion caused reporting drift in scheduled jobs.
+```
+
+## Notes
+
+- If there are no matches, say so directly.
+- Keep excerpts short and relevant.
+- Search TLC memory under `.tlc/memory/team/`, not Claude-managed memory.

package/.claude/commands/tlc/remember.md

@@ -1,71 +1,76 @@
-# /tlc:remember - Permanent Memory Capture
-
-Save important context permanently so it survives context compaction.
-
-## Usage
-
-```
-/tlc:remember <text>
-```
-
-Or without arguments to capture recent exchanges:
-```
-/tlc:remember
-```
-
-## What This Does
-
-1. Captures the provided text (or recent conversation) as a **permanent memory**
-2. Writes it to `memory/conversations/` with `[PERMANENT]` prefix and `permanent: true` frontmatter
-3. Indexes it in the vector store for semantic recall
-4. Permanent memories are **never pruned** and get a **1.2x boost** in recall scoring
-
-## Process
-
-### Step 1: Determine What to Remember
-
-**With text argument:**
-- Use the provided text as the memory content
-
-**Without arguments:**
-- Capture the recent conversation exchanges from the current session
-- Generate a summary from the exchanges
-
-### Step 2: Write Permanent Memory
-
-1. Create a conversation chunk with `permanent: true`
-2. Title prefixed with `[PERMANENT]`
-3. Write to `memory/conversations/YYYY-MM-DD-{slug}.md`
-4. YAML frontmatter includes `permanent: true`
-
-### Step 3: Index in Vector Store
-
-1. Generate embedding for the memory content
-2. Store in vector database with `permanent = 1` flag
-3. This memory will be boosted 1.2x in future recall searches
-
-### Step 4: Confirm
-
-```
-Remembered permanently: {summary}
-File: memory/conversations/2026-02-09-always-use-utc.md
-```
-
-## Examples
-
-```
-/tlc:remember Always use UTC timestamps in the database, never local time
-
-/tlc:remember The API rate limit is 100 requests per minute per user
-
-/tlc:remember
-(captures recent conversation context)
-```
-
-## When to Use
-
-- **Architecture decisions** that should never be forgotten
-- **Environment gotchas** that are hard to rediscover
-- **Team conventions** that must be consistent
-- **Critical constraints** from stakeholders
-- Any knowledge you want to survive across sessions and context compaction
+# /tlc:remember - Team Decision Capture
+
+Save an important decision into TLC's shared team memory.
+
+## Usage
+
+```text
+/tlc:remember <decision text>
+```
+
+Or without arguments:
+
+```text
+/tlc:remember
+```
+
+## What This Does
+
+1. Captures the provided decision text, or extracts decisions from the recent conversation context if no argument is given.
+2. Writes a markdown file to `.tlc/memory/team/decisions/{date}-{slug}.md`.
+3. Stores TLC-owned frontmatter for later grep-based recall.
+4. Never writes to `~/.claude/projects/.../memory/` because that is Claude memory, not TLC memory.
+
+## Write Format
+
+Write the decision as a markdown file with YAML frontmatter:
+
+```yaml
+---
+provider: claude
+source: manual
+timestamp: 2026-03-28T12:34:56Z
+type: decision
+scope: team
+---
+```
+
+The filename must be:
+
+```text
+.tlc/memory/team/decisions/{date}-{slug}.md
+```
+
+Example:
+
+```text
+.tlc/memory/team/decisions/2026-03-28-use-utc-timestamps.md
+```
+
+## Process
+
+### With an argument
+
+- Use the argument as the decision content.
+- Generate a short slug from the decision.
+- Write the file under `.tlc/memory/team/decisions/`.
+
+### Without an argument
+
+- Review the recent conversation context.
+- Extract concrete decisions, conventions, or constraints worth preserving.
+- Summarize them clearly.
+- Write one decision file under `.tlc/memory/team/decisions/`.
+
+## Confirmation
+
+```text
+Remembered: {summary}
+File: .tlc/memory/team/decisions/2026-03-28-use-utc-timestamps.md
+```
+
+## Notes
+
+- Prefer concise, durable statements over raw transcript dumps.
+- Record decisions, not general chatter.
+- Use `.tlc/memory/team/gotchas/` for gotchas, not this command.

package/.claude/commands/tlc/review.md

@@ -127,7 +127,7 @@ TLC automatically uses ALL providers configured for the `review` capability in `
 
 **With this config, `/tlc:review` will:**
 1. Run Claude's review (current session)
-2. Invoke Codex CLI for second opinion: `codex "Review this diff: ..."`
+2. Invoke Codex CLI for second opinion: `codex exec review --base main -m gpt-5.4 --json --ephemeral`
 3. Combine verdicts - both must approve for APPROVED
 
 ## Usage
@@ -295,31 +295,86 @@ Coding Standards:
 
 **Fail if:** Any `any` types in new code, or files >1000 lines.
 
-### Step 6: Invoke External Providers (Codex, Gemini)
+### Step 6: Invoke External Providers (Codex, Gemini)
 
 **CRITICAL: This step runs automatically when providers are configured.**
 
 For each provider in `reviewProviders` (except `claude` which is the current session):
 
-**How to invoke:**
-
-**Codex** — use its built-in `review` subcommand. It reads the git diff natively, no need to pipe files:
-
-```bash
-# Review current branch against main (default)
-codex review --base main "Focus on: bugs, security issues, missing edge cases, test coverage gaps. End with APPROVED or CHANGES_REQUESTED."
-
-# Review uncommitted changes only
-codex review --uncommitted
-
-# Review a specific commit
-codex review --commit <sha>
-
-# Custom instructions via prompt
-codex review --base main "Check for TDD compliance: were tests written before implementation? Flag any implementation without corresponding test files."
-```
-
-`codex review` outputs a structured review to stdout. No `--print` flag needed — it's already non-interactive.
+**How to invoke:**
+
+**Codex** — use `codex exec review` with explicit model selection, JSON output, and `--ephemeral` for CI-style stateless runs. It reads the git diff natively, no need to pipe files.
+
+Before invoking Codex, compute diff stats:
+
+```bash
+FILES=$(git diff --name-only main...HEAD | wc -l)
+LINES=$(git diff --stat main...HEAD | tail -1 | grep -oE '[0-9]+ insertion|[0-9]+ deletion' | grep -oE '[0-9]+' | paste -sd+ | bc)
+```
+
+**Size-aware Codex review strategy:**
+
+**Small diff (`<=15` files, `<=1200` lines):**
+
+Single pass:
+
+```bash
+codex exec review --base main -m gpt-5.4 --json --ephemeral
+```
+
+**Medium diff (`15-25` files, `1200-2500` lines):**
+
+Two passes:
+
+1. Broad pass:
+   ```bash
+   codex exec review --base main -m gpt-5.4 --json --ephemeral
+   ```
+2. Focused pass on the highest-risk area via `codex exec` with a targeted prompt:
+   ```bash
+   codex exec -m gpt-5.4 --json --ephemeral "Review the changes against main. Focus only on these files: <highest-risk file list>. Focus only on: correctness bugs, behavioral regressions, broken assumptions across module boundaries, missing validation/auth/error handling, schema/API compatibility. Do not spend time on style or naming. Prefer findings with: severity, why it is a bug, exact file/line, minimal breaking scenario."
+   ```
+
+**Large diff (`25+` files, `2500+` lines):**
+
+Multi-pass:
+
+1. Per-commit:
+   ```bash
+   codex exec review --commit <sha> -m gpt-5.4 --json --ephemeral
+   ```
+   Run once for each non-merge commit.
+2. Per-area:
+   Chunk by directory, then run `codex exec` with a prompt listing the chunk files:
+   ```bash
+   codex exec -m gpt-5.4 --json --ephemeral "Review the changes against main. Focus only on these files: <chunk file list>. Focus only on: correctness bugs, behavioral regressions, broken assumptions across module boundaries, missing validation/auth/error handling, schema/API compatibility. Do not spend time on style or naming. Prefer findings with: severity, why it is a bug, exact file/line, minimal breaking scenario."
+   ```
+3. Integration sweep:
+   ```bash
+   codex exec -m gpt-5.4 --json --ephemeral "Review the full diff against main but do not re-check every local edit. Focus only on cross-file regressions: changed call sites vs function contracts, schema changes vs readers/writers, auth/permission drift, partial migrations."
+   ```
+
+**Confidence escalation:**
+
+- Finding repeated across passes -> high confidence
+- Finding from only one broad pass -> medium confidence
+- Zero findings on huge diff -> LOW CONFIDENCE (not "clean"); flag for human review
+
+**Prompt templates:**
+
+Per-commit/per-area prompt:
+
+```text
+Review the changes against main. Focus only on: correctness bugs, behavioral regressions, broken assumptions across module boundaries, missing validation/auth/error handling, schema/API compatibility. Do not spend time on style or naming. Prefer findings with: severity, why it is a bug, exact file/line, minimal breaking scenario.
+```
+
+Integration sweep prompt:
+
+```text
+Review the full diff against main but do not re-check every local edit. Focus only on cross-file regressions: changed call sites vs function contracts, schema changes vs readers/writers, auth/permission drift, partial migrations.
+```
+
+Use `codex exec review`, not plain `codex review`, for better automation controls. Always include `-m gpt-5.4`, `--json`, and `--ephemeral` in automated runs.
 
 **Gemini** — no built-in review command, so save diff and invoke: