@abarcenas/ai-workflow-template 1.41.0 → 1.44.0

package/.agents/instructions/knowledge-retrieval.instructions.md

@@ -0,0 +1,69 @@
+---
+applyTo: "**"
+---
+
+# Knowledge Retrieval Protocol
+
+Every agent MUST follow this 3-layer protocol before planning, deciding, or implementing.
+This protocol is **mandatory to attempt** but **graceful to fail** — no layer is a hard dependency.
+
+## Layer 1: Memory Bank (always available — embedded SQLite)
+
+Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search`
+for semantic context retrieval and `memory_bank_memory_get` for full file reads.
+
+## Layer 2: Learned Knowledge (always available — git-committed markdown)
+
+Skim `.agents/instructions/learned-knowledge.instructions.md` for patterns, conventions,
+gotchas, and agent tuning notes relevant to your role and current task. Focus on sessions
+that match your pipeline type and agent role.
+
+## Layer 3: Cross-Project Knowledgebase (graceful — requires PG + pgvector)
+
+Call `knowledgebase_knowledgebase_search` (MCP) with a task-relevant query.
+
+**This is mandatory to ATTEMPT, but graceful to fail:**
+
+| Outcome | Required Action |
+|---------|----------------|
+| **Success** | Explicitly note in your reasoning and final summary: "knowledgebase_search executed — N results returned." |
+| **Error / Unavailable** | Explicitly note: "knowledgebase_search NOT executed (PG vector unavailable)." Do NOT block, fail, or retry. Proceed normally. |
+
+### Graceful Failure Wrapper
+
+```
+try {
+  const results = await knowledgebase_knowledgebase_search({
+    query: "<task-relevant query>",
+    topK: 5
+  });
+  // Note: "knowledgebase_search executed — N results returned."
+  // Use results to inform your approach
+} catch (err) {
+  // Note: "knowledgebase_search NOT executed (PG vector unavailable)."
+  // Proceed with the task using memory-bank + learned-knowledge only
+}
+```
+
+**Your final output summary MUST state which outcome occurred ("accessed" or "skipped").
+This disclosure is not optional — every agent response must include it.**
+
+### Canonical projectId
+
+When calling `knowledgebase_knowledgebase_index`, the `projectId` parameter MUST equal
+`require('./package.json').name` — the scoped package name if one exists (e.g.,
+`@abarcenas/ai-workflow-template`). Never derive projectId from directory names,
+orchestrator context, or display strings. The `package.json` `name` field is the
+single source of truth.
+
+When calling `knowledgebase_knowledgebase_search`, `projectId` is optional — omitting
+it searches across all indexed projects (cross-project match-all). If you do pass one,
+derive it from `package.json` `name` the same way.
+
+## Retrieval Order
+
+1. Memory bank (`memory_bank_memory_search` + `memory_bank_memory_get`)
+2. Learned knowledge (skim `.agents/instructions/learned-knowledge.instructions.md`)
+3. Knowledgebase (`knowledgebase_knowledgebase_search` with graceful failure)
+4. Project files (read specific source files as needed)
+5. Proceed with the task

package/.agents/instructions/knowledgebase.instructions.md

@@ -8,11 +8,13 @@ You have access to a centralized knowledgebase containing learned knowledge from
 pipeline sessions across all projects that have been indexed. The knowledgebase is
 powered by PostgreSQL + pgvector with semantic (cosine similarity) search.
 
-**MANDATORY REQUIREMENT — NOT BEST EFFORT:** You MUST query the knowledgebase before
-planning any task, when encountering errors, and when starting work on a known area.
-This is not optional — it is a core part of your decision-making process. Skipping
-knowledgebase queries in these scenarios will result in missed context and degraded
-output quality.
+**MANDATORY TO ATTEMPT, GRACEFUL TO FAIL:** You MUST attempt to query the knowledgebase
+before planning any task, when encountering errors, and when starting work on a known
+area. The attempt is mandatory — but the outcome is graceful: if the knowledgebase is
+unavailable or the search errors, explicitly note the skip and continue. Never block or
+fail the task because the knowledgebase is unavailable. See
+`.agents/instructions/knowledge-retrieval.instructions.md` for the full protocol
+including the required explicit reporting.
 
 ## MCP Tools
 
@@ -22,7 +24,7 @@ The knowledgebase is accessed via the `knowledgebase` MCP server configured in
 | Tool | Purpose | Parameters |
 |------|---------|------------|
 | `knowledgebase_search` | Semantic search across learned knowledge from all indexed projects | `query` (required), `topK` (default 5), `projectId` (optional) |
-| `knowledgebase_index` | Index or re-index a project's learned-knowledge.instructions.md | `projectId` (optional) |
+| `knowledgebase_index` | Index or re-index a project's learned-knowledge.instructions.md | `projectId` (required — from `package.json` `name` field) |
 | `knowledgebase_stats` | Get knowledgebase statistics (total projects, chunks, DB size) | None |
 | `knowledgebase_list` | List all projects currently indexed in the knowledgebase | None |
 
@@ -30,11 +32,14 @@ The knowledgebase is accessed via the `knowledgebase` MCP server configured in
 
 - **`knowledgebase_search`** — Use for finding relevant patterns, past decisions, and solutions.
   Returns results ranked by cosine similarity with metadata (project, date, pipeline, content).
-  Results are OpenAI-compatible tool call responses with structured text content.
+  Results are OpenAI-compatible tool call responses with structured text content. Restart
+  OpenCode after code changes to pick up updates.
 
 - **`knowledgebase_index`** — Use to manually trigger re-indexing of a project's learned knowledge
   file. Idempotent: unchanged sessions are skipped. Typically used when the post-commit hook
-  did not fire or you want to index changes before committing.
+  did not fire or you want to index changes before committing. The `projectId` MUST be the scoped
+  package name (e.g., `@abarcenas/ai-workflow-template`), read from `package.json` `name`. This
+  ensures a single canonical project per repository.
 
 - **`knowledgebase_stats`** — Use to check whether the knowledgebase has data and how much.
   Useful for diagnosing empty results or confirming indexing worked.
@@ -160,22 +165,38 @@ Each result includes these fields:
 your question, you do not need to examine lower-ranked results. If all results are below
 0.70, refine your query with more specific terminology before proceeding.
 
-## Graceful Degradation
+## Graceful Degradation (Mandatory to Attempt, Graceful to Fail)
 
-The knowledgebase is **optional** — it requires a PostgreSQL database with pgvector
-extension. If the MCP server is unavailable or `DATABASE_URL` is not configured:
+Querying the knowledgebase is **mandatory to attempt** but **graceful to fail** — it
+requires a PostgreSQL database with pgvector extension. If the MCP server is
+unavailable, `DATABASE_URL` is not configured, or the search call errors:
 
 1. **Do NOT block or fail** — Proceed with your task without the knowledgebase.
-2. **Make a note** — Record in your reasoning that the knowledgebase was unavailable.
+2. **Explicitly report the skip** — Note in your reasoning and final summary:
+   "knowledgebase_search NOT executed (PG vector unavailable)."
 3. **Fall back to memory-bank** — Use `memory_search` and `memory_get` for local context.
 4. **Proceed normally** — The knowledgebase is an enhancement, not a dependency.
 
+On a **successful** search, explicitly report the outcome in your reasoning and final
+summary: "knowledgebase_search executed — N results returned." (N = number of results returned.)
+
+This explicit-report protocol is the canonical graceful-failure contract defined in
+`.agents/instructions/knowledge-retrieval.instructions.md`.
+
 The MCP tools return descriptive messages when the database is unavailable:
 - `knowledgebase_search` → "Knowledgebase not available: DATABASE_URL is not configured."
 - `knowledgebase_index` → "Knowledgebase not available: DATABASE_URL is not configured."
 - `knowledgebase_stats` → Returns zero counts (not an error).
 - `knowledgebase_list` → Returns empty list (not an error).
 
+### MCP Server Restart After Configuration Changes
+
+When `mcp-knowledgebase-server.js` is updated (e.g., a threshold fix or handler change), the
+MCP server process spawned by OpenCode may hold a stale copy. **After any code change to the
+knowledgebase server or scripts, restart OpenCode** (or reload MCP servers) to pick up the
+latest version. Common gotcha: `knowledgebase_search` returns 0 results despite chunks in the
+DB because the MCP process is using an old threshold default. Restart resolves this.
+
 ## When NOT to Query
 
 Do NOT use the knowledgebase for:
@@ -194,7 +215,7 @@ Do NOT use the knowledgebase for:
 
 The knowledgebase and memory bank serve complementary but distinct roles:
 
-| Aspect | Knowledgebase (Layer 3) | Memory Bank (Layer 2) |
+| Aspect | Knowledgebase (storage Tier 3) | Memory Bank (storage Tier 2) |
 |--------|------------------------|----------------------|
 | **Scope** | Cross-project — all indexed projects | Per-project — current project only |
 | **Content** | Learned patterns, conventions, gotchas | Current state, tasks, architecture |
@@ -206,19 +227,19 @@ The knowledgebase and memory bank serve complementary but distinct roles:
 **Think of the knowledgebase as "what we've learned across all projects" and the memory
 bank as "what's happening right now in this project."**
 
-The full three-layer knowledge architecture is:
+The storage hierarchy is a **storage-tier** taxonomy (Tier 1 → Tier 3), distinct from the
+**retrieval-layer** numbering (L1 → L3) used in
+`.agents/instructions/knowledge-retrieval.instructions.md`:
 
 ```
-Layer 3: Knowledgebase → Cross-project learned patterns (PostgreSQL + pgvector)
-Layer 2: Memory Bank  → Per-project current state (SQLite + sqlite-vec)
-Layer 1: Markdown     → Git-committed source of truth (filesystem)
+Tier 3: Knowledgebase → Cross-project learned patterns (PostgreSQL + pgvector)
+Tier 2: Memory Bank  → Per-project current state (SQLite + sqlite-vec)
+Tier 1: Markdown     → Git-committed source of truth (filesystem)
 ```
 
-When you start a session, follow this order:
-1. Load memory bank context (`memory_search`)
-2. Query the knowledgebase for relevant past patterns (`knowledgebase_search`)
-3. Read specific project files as needed
-4. Proceed with the task
+When you start a session, follow the protocol in
+`.agents/instructions/knowledge-retrieval.instructions.md` for the complete 3-layer
+retrieval order (memory-bank → learned-knowledge → knowledgebase_search → project files).
 
 ## Closed-Loop Workflow
 

package/.agents/instructions/learned-knowledge.instructions.md

@@ -227,3 +227,183 @@
 - **researcher**: CLI-search diagnostics are the fastest way to compare thresholds — running the SAME query through `knowledgebase-cli.js` at `--threshold 0.0` vs `--threshold 0.6` reproduced the bug exactly and quantified the real similarity range (0.01–0.41). When an MCP tool returns empty but the data exists, use the CLI to isolate whether the problem is the tool's defaults vs. the data itself.
 - **coder**: When fixing a default-value bug (`||` → `??`), scan sibling call sites for the same falsy-coercion pattern — the same class of bug can hide in `args.limit || 5` (also in this handler) and any other `||` default.
 - **tracker**: Record MCP-server restart requirements as a universal gotcha — live MCP tools run long-lived processes that do NOT hot-reload code changes; document the restart step in verification notes.
+
+## Session: 2026-08-02 — PG Knowledgebase Write Bug Fix (registerProject upstream)
+
+**Pipeline:** implementer (bootstrap) → implementer (planning) → coder (Batch A: T1+T2 combined, T5) → coder (Batch B: T3) → unit-tester (T4) → reviewer → tracker
+**Coverage:** 176/176 tests passing across 10 test files, 0 failures; `mcp-knowledgebase-server.js` at 79.66% stmts / 81.03% lines (up from 0% test coverage — the MCP server previously had zero tests)
+**TDD Iterations:** 0 (bug-fix pipeline, not TDD)
+
+**New knowledge:**
+- **FK-violation bug class: writing to a child table before ensuring the parent row exists** — `knowledge_chunks.project_id` has a FOREIGN KEY to `projects(id)`. The MCP `knowledgebase_index` handler called `upsertChunks()` without ever calling `registerProject()`, so inserts for non-bootstrap-registered projects failed with PG error `23503` (foreign_key_violation). **The failure was invisible**: `upsertChunks()`'s generic catch-all swallowed the error and counted the chunk as `skipped`, producing a misleading "indexed 0, updated 0, skipped N" result. **Universal pattern:** when a handler writes rows that FK-reference a parent table, ensure the parent row exists first (idempotent upsert), and audit catch-all error handlers that can silently convert real failures into "skipped" counts.
+- **The registerProject fix pattern for the MCP server mirrors the CLI** — `scripts/knowledgebase-cli.js:122` already called `registerProject(projectId, projectId)` before `upsertChunks()`. The MCP server was the only caller missing it. **Universal pattern:** when one entry point in a family has the correct call sequence, diff all sibling entry points (CLI vs MCP vs setup) for the same missing call — the "one fixed, sibling missed" pattern has now hit this project repeatedly (dotenv imports, threshold defaults, registerProject).
+- **Call ordering convention: guard first, then register, then upsert** — the `registerProject()` call goes AFTER the `chunks.length === 0` guard (avoids a DB call for empty input) and BEFORE `upsertChunks()`. `registerProject()` is idempotent (`INSERT … ON CONFLICT DO UPDATE`) so re-indexing existing projects is a no-op. Placing it after the guard matches the CLI convention and avoids creating parent rows for invalid/empty content.
+- **`(projectId, projectId)` argument convention** — `registerProject(projectId, name)` is called with `projectId` for both args because project ID == display name in this system. The CLI and MCP server both use this convention.
+- **Testability seam for MCP stdio servers: export the handler + guard the bootstrap** — to unit-test an MCP server that auto-starts a stdio transport on import, (1) extract the `CallToolRequestSchema` handler into an exported `handleToolCall(request)` (body unchanged) and (2) guard the `main()`/SIGTERM bootstrap with an `isDirectRun` check (`process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)`). Importing the module in tests then opens no transport and exits cleanly; direct execution (`node scripts/mcp-knowledgebase-server.js`) is unchanged. This seam enabled the MCP server's first-ever test suite (16 tests).
+- **Mutation testing proves a regression guard is non-vacuous** — after writing the tests, the unit-tester and reviewer independently removed the `registerProject` call in a temp copy and re-ran the suite: TEST-01 (`toHaveBeenCalledTimes(1)` got 0) and TEST-16 failed. A passing suite alone does not prove a test catches the regression — only a mutation check does. This is now the established validation for any "regression guard" claim.
+- **Order assertions with `mock.invocationCallOrder`** — to assert `registerProject` resolves BEFORE `upsertChunks` starts, compare `kb.registerProject.mock.invocationCallOrder[0]` vs `kb.upsertChunks.mock.invocationCallOrder[0]` rather than only checking call counts. Call-count assertions catch "called or not", but not "called in the right order".
+- **Coverage gap on the direct-run bootstrap is acceptable for unit tests** — remaining uncovered lines (`ListToolsRequestSchema` tools builder, `main()`, `isDirectRun`, SIGTERM) require either production seams or a manual live-spawn smoke test (plan TEST-12). The 79.66% file coverage is a huge improvement over the previous 0%; the global 40.93% below the 90% gate is pre-existing and out of scope.
+
+**Agent tuning notes:**
+- **implementer (planning)**: When two tasks edit the SAME file, merge them into one task — the plan's T1+T2 both touched `scripts/mcp-knowledgebase-server.js`, and the orchestrator combined them into a single coder invocation to avoid read-modify-write clobbering. Also, when planning a fix for a missing call, verify the correct pattern exists elsewhere in the codebase (the CLI was the reference) and make the plan's snippet match the ACTUAL file style — the plan claimed "semicolon-free convention" but the server file uses semicolons, a minor doc/code mismatch the reviewer flagged.
+- **coder**: When adding an imported function for the first time, verify it is actually exported from the source module before writing the import (this plan confirmed `registerProject` is exported at `knowledgebase-index.js:782`). Keep the fix minimal and sibling-call-site consistent — one file, two lines, plus the testability seam.
+- **unit-tester**: For MCP servers, mock the core engine (`vi.mock('./knowledgebase-index.js')`) and `node:fs`'s `readFileSync` to test handler logic hermetically — no DB, no stdio. Assert call ORDER with `invocationCallOrder` in addition to call counts. Run a mutation test on the fix line to prove the guard catches regression.
+- **reviewer**: Re-run the mutation test independently (the reviewer's run failed 2 tests vs the unit-tester's 1 — both prove non-vacuous). Distinguish pre-existing nits (schema default 0.6 mismatch, raw `err.message`, whitespace projectId, plan wording) from fix-introduced issues. The `isDirectRun` symlink concern is theoretical and non-blocking.
+- **tracker**: Record FK-parent-insertion and "one-entry-point-fixed, sibling-missed" as universal patterns — both are recurring bug classes in this codebase. The MCP-server testability seam (export handler + `isDirectRun` guard) is a reusable pattern for any stdio MCP server needing unit tests.
+
+## Session: 2026-08-02 — Knowledgebase registerProject Follow-up (nits, TEST-12 live smoke, fail-closed redaction)
+
+**Pipeline:** coder (nits) → unit-tester (TEST-12 live-spawn) → reviewer (⚠️ CHANGES REQUESTED) → coder (redaction hardening) → reviewer (✅ APPROVED) → tracker
+**Coverage:** 181/181 tests passing across 10 test files, 0 failures; MCP server test file 21/21
+**TDD Iterations:** 0 (bug-fix follow-up pipeline, not TDD)
+
+**New knowledge:**
+- **`new URL()` throws on unix-socket-style connection-string authorities — URL-parse-based redaction FAILS OPEN** — `postgres://user:secret@/var/run/postgresql` (and `postgresql://user:secret@/tmp?host=/tmp`) make `new URL()` throw "Invalid URL". A helper with `try { new URL(match[1]) } catch { return message }` returns the message UNCHANGED, leaking `user:secret` into MCP error responses. The engine helper (`knowledgebase-index.js:62`) fails CLOSED (`'***'`) for the same input — a local helper must never be WEAKER than the engine it mirrors. **Universal pattern:** for credential redaction in error messages, prefer a pure regex that strips `userinfo@` (`/(postgres(?:ql)?:\/\/)([^/\s]+)@/gi → '$1***@'`) over URL parsing — there is no parse to fail, so unparseable tokens are redacted by construction (fail-closed).
+- **`[^/\s]+` beats `[^@\s]+` for credential redaction** — the reviewer suggested `[^@\s]+`, but that stops at the first `@`, leaking a password containing `@` (`postgres://user:p@ss@host` → would leave `ss@host`). `[^/\s]+` consumes the entire userinfo up to the authority delimiter, fully redacting such passwords. Socket-only (`postgres:///var/run/postgresql`) and host-only (`postgres://10.0.0.5:5432/db`) forms have no `@` → regex matches nothing → message unchanged (no over-matching).
+- **Global-flag regex redacts ALL tokens in one pass** — `message.replace(/.../gi, ...)` with the `g` flag rewrites every `postgres://` token in a message, satisfying "redact all tokens" without a loop. A parse-based helper that does `replace(match[1], redacted)` and returns only redacts the FIRST token — and would leak a second unparseable token when the first parses.
+- **Live-spawn smoke tests are the proof for direct-run bootstrap paths** — the MCP server's `main()`/`isDirectRun`/SIGTERM path is not unit-testable without production seams. A real stdio spawn against the live DB (`DATABASE_URL` in `.env`, absent from process env) closed that last coverage gap: `initialize` handshake OK, `tools/call knowledgebase_index` with a fresh projectId returned **"Indexed 1 chunks, updated 0, skipped 0"** (NOT "skipped 1") — direct evidence `registerProject()` ran before `upsertChunks()`. Cleanup (DELETE test rows) + post-cleanup `SELECT count(*)` verified 0 residue; SIGTERM handled cleanly.
+- **Whitespace-validation strengthening made the regression guard STRICTLY stronger** — after adding `!projectId?.trim()` + trim-flow, the mutation test (remove `registerProject(pid, pid)`) now fails **3 tests** (TEST-01 `toHaveBeenCalledTimes(1)`, TEST-16 error path, TEST-06c `toHaveBeenCalledWith('test-project','test-project')`) instead of 2. A trim-downstream assertion also fails when the call is missing — validation fixes can accidentally weaken guards, but here the new trim test added a third independent detector.
+- **Non-vacuous redaction tests via replay** — the new redaction tests (TEST-17/18/19) exercise the real outer-catch path by rejecting `upsertChunks` with URL-bearing messages. Non-vacuousness was proven by replaying the OLD helper (from git diff): all 3 new tests fail against it (TEST-17 leaks `user:secret`, TEST-18 output mismatch + leak, TEST-19 leaks the second token). Replaying the pre-fix implementation is a cheap, decisive way to prove a security test matters.
+- **Helper kept private; tests hit the real production path** — the redaction helper is intentionally NOT exported. Tests reject `upsertChunks` with error messages containing URLs, so they verify the actual outer-catch behavior (`Error: ${redactConnectionString(err.message)}`) rather than the helper in isolation — zero production surface change.
+
+**Agent tuning notes:**
+- **reviewer**: When a redaction/security helper is introduced, probe it with unparseable input classes (unix-socket authorities, invalid percent-encoding, `?host=` variants) — a passing happy-path test does not prove fail-closed behavior. Empirically copy the exact helper code into node and run it against adversarial inputs before trusting it. Also re-run the full suite independently (reviewer's run must match the unit-tester's count) and replay the old implementation to confirm new tests are non-vacuous.
+- **coder**: For fail-closed security fixes, prefer regex-only construction ("nothing to fail") over catch-fallback layers ("a second failure mode can still leak"). When choosing a regex character class for userinfo redaction, prefer `[^/\s]+` (stops at the authority delimiter) over `[^@\s]+` (stops at the first `@`). Always add a JSDoc rationale explaining WHY the construction is fail-closed so the next reader doesn't "simplify" it back into a parse-based helper.
+- **unit-tester**: A live-spawn smoke test needs disciplined cleanup + verification — delete test rows via direct SQL, then `SELECT count(*)` to prove 0 residue, and terminate via SIGTERM to exercise the shutdown path. When validating a mutation guard after unrelated validation changes, re-run the mutation test: the expected failure count can legitimately grow (3 tests now) — that is strictly stronger, not a problem.
+- **tracker**: Record regex-redaction and live-spawn-smoke-test as reusable patterns; they complement the existing MCP testability-seam pattern and apply to any stdio MCP server that surfaces raw error messages.
+
+## Session: 2026-08-02 — Knowledgebase Final Minor-Hygiene Pass (search trim, limit `??`, query-string redaction)
+
+**Pipeline:** coder (3 minors) → unit-tester (independent validation) → reviewer (final sign-off) → tracker
+**Coverage:** 185/185 tests passing across 10 test files, 0 failures; MCP server test file 25/25
+**TDD Iterations:** 0 (bug-fix hygiene follow-up pipeline, not TDD)
+
+**New knowledge:**
+- **Search-filter vs write-target asymmetry is a deliberate design pattern** — for an OPTIONAL, read-only filter (`knowledgebase_search.projectId`), an invalid/whitespace-only value DEGRADES to match-all (`undefined`) instead of erroring; for a REQUIRED write-target (`knowledgebase_index.projectId`), a whitespace-only value hard-errors. The asymmetry is intentional (read-only filters may degrade; write targets must not silently target the wrong scope) and MUST be documented in a code comment at the call site so future readers don't "fix" it into a surprising inconsistency. Trim happens at the handler boundary (`args.projectId?.trim() || undefined`) and the engine only applies the `AND project_id = $n` clause when the filter is truthy.
+- **`?? 5` vs `|| 5` — explicit-zero honoring (same falsy-coercion class as `threshold`)** — `args.limit || 5` silently coerces an explicit `limit: 0` to the default 5 because `0` is falsy. `args.limit ?? 5` honors `limit: 0` (`LIMIT 0`), which is legitimate caller intent since the engine passes `limit` straight to SQL. This is the SAME bug class as the earlier `args.threshold || 0.6` → `?? 0.1` fix — **Universal pattern:** after fixing one `||`-default to `??`, scan ALL sibling `|| default` expressions in the same handler/file; a `limit`/`topK` default is typically the next one hiding the same bug.
+- **Query-string/fragment redaction extends the regex pattern without losing fail-closed** — the pure-regex redaction helper was extended from `/(postgres(?:ql)?:\/\/)([^/\s]+)@/gi → '$1***@'` to `/(postgres(?:ql)?:\/\/)([^/\s]+)@([^?#\s]*)([?#][^\s]*)?/gi` with a callback that replaces the query or fragment with `?***`/`#***` while preserving host/path (`postgres://user:secret@host:5432/kb?password=hunter2` → `postgres://***@host:5432/kb?***`). Because it is still a pure regex with no `new URL()`, the fail-closed-by-construction property is preserved — unparseable tokens remain redacted, `@`-in-password still fully redacted, non-URL messages unchanged. **Universal pattern:** a fail-closed regex can be EXTENDED (add capture groups + callback) without reopening the failure mode that URL parsing introduced.
+- **Real temp mutations are the decisive non-vacuity proof for hygiene fixes** — the unit-tester created a temp copy of the server + tests + real engine and reverted each fix one at a time: `?? 5`→`|| 5` fails TEST-21; trim removed fails TEST-20+TEST-20b; old redaction regex fails TEST-18+TEST-22; removing `registerProject` fails TEST-01+06c+16. Four independent guards, four matching mutations — each new test genuinely catches its fix's regression. This is the established validation standard (mutation testing) applied to one-line hygiene fixes, not just the original bug fix.
+- **Informational schema descriptions can go stale when defaults honor explicit zero** — after `?? 5`, the search schema `limit` description "(1–50)" no longer describes actual behavior (0 is now honored). When a default's semantics change, audit the accompanying inputSchema description for the same staleness.
+- **CLI/MCP parity is a separate, constraint-scoped concern** — `knowledgebase-cli.js` still uses `topK || 5` and an untrimmed `--project`; it was deliberately out of scope for the MCP-focused hygiene pass. Parity fixes across sibling entry points are best tracked explicitly as a future item rather than silently expanded mid-pipeline.
+
+**Agent tuning notes:**
+- **coder**: When applying a `||`→`??` default fix, grep the same file/handler for other `|| default` expressions (this pass found `args.limit || 5` one line away from the already-fixed `threshold`). When extending a fail-closed regex, preserve the "no URL parse → nothing to fail" property and update the JSDoc rationale so the next reader doesn't regress it to a parse-based helper.
+- **unit-tester**: For one-line hygiene fixes, still run real temp mutations (not reasoning) to prove each new test is non-vacuous — this pass's 4-guard mutation matrix is the reference pattern. Confirm the exact count with the coder's report (25/25 and 185/185 matched).
+- **reviewer**: Run an empirical regex probe (12 cases: unix-socket, `?host=`, `?password=`, `#fragment`, multi-token, `@`-in-password, non-URL, socket/host-only, uppercase scheme) against the EXACT helper code before approving, and verify git diff scope discipline (only the intended files changed). Distinguish informational doc nits (schema description stale) from code issues.
+- **tracker**: Record the search-filter vs write-target asymmetry and the extended-regex-preserves-fail-closed pattern as reusable design knowledge; note CLI/MCP parity gaps as explicit follow-ups rather than letting them fall through the cracks.
+
+## Session: 2026-08-03 — README Trim + Instructions-on-Top (docs accuracy audit)
+
+**Pipeline:** coder (README rewrite) → reviewer (✅ APPROVED) → coder (1-line graphify nit) → tracker
+**Coverage:** N/A (documentation-only pipeline — no code or tests changed; 185/185 suite unaffected)
+**TDD Iterations:** 0 (docs pipeline, not TDD)
+
+**New knowledge:**
+- **README/doc accuracy-audit pattern — verify every factual claim against the filesystem and CLI before writing** — the rewrite's four corrections came from an explicit verification pass: skill counts via `ls .agents/skills/*/SKILL.md | wc -l` (claimed 27, actually 29), file paths via `ls` (orchestrator agent at `.opencode/agents/orchestrator/orchestrator.agent.md`), CLI flags via `node bin/setup.js --help` (added the real `--knowledgebase`), and existence checks for referenced directories (`.agents/compress/` and `.agents/agents/` do NOT exist and were removed). **Universal pattern:** any documentation that enumerates filesystem entities (skill/agent counts, paths, dirs) or CLI surface (flags, commands) MUST be verified against the actual filesystem and `--help` output before writing — a docs edit that "looks right" but contains stale facts is worse than a long README.
+- **"Instructions on the very top" means the first screen (~30 lines), not "somewhere near the top"** — the accepted structure is: title → one-line description → **Install** → **Git Hook Setup** (first screen), then a condensed capability list, then reference sections. For a developer-tool README, a new user must be able to install and configure without scrolling. Instructions confirmed at lines 1–51; Install at line 5, Git Hook Setup at line 13.
+- **Fluff-cut criterion: drop only what is non-actionable; preserve every command/option/path/table/link** — removed: emoji decoration, salesy intro prose, a verbose run-flow list (condensed to 2 bullets), a YAML frontmatter example (condensed to 1 sentence), stale structure-tree entries. Survived (verified via diff audit + grep): every install/setup/sync command, all setup options (incl. `--knowledgebase`), orchestrator usage examples, all 11 agent-table rows + paths, TDD table, memory-bank MCP tools, local dev commands (cross-checked against package.json), publish flow + NPM_TOKEN steps, external links. 469 → 289 lines (−38%) with zero actionable-content loss.
+- **Global skills vs package skills is a real documentation trap** — `graphify` lives at `~/.config/opencode/skills/` (installed globally), NOT in `.agents/skills/` (package-shipped). Only `graphify-framework-aware` is shipped with the package. The reviewer caught the README's Featured Skills list presenting `graphify` as a package skill; the fix marks it `(global skill)` and adds the actually-shipped sibling. **Universal pattern:** when documenting skills/tools, verify WHERE each one lives (global config vs repo) before claiming it is part of the distributed package.
+- **markdownlint as a doc-quality gate — separate structural errors from stylistic noise** — `npx markdownlint-cli2 README.md` reported **0 structural errors** after the rewrite; the only remaining finding is MD013 (line-length), a stylistic default with no repo config (39 findings vs 42 in the old README). The old README failed structural rules MD001/032/040/058/060/031 — all now clean. Run markdownlint with MD013 disabled (or interpret it separately) so structural quality stays visible despite default line-length noise.
+- **The reviewer's independent re-verification is the trust anchor for docs changes** — the reviewer re-confirmed all 4 coder accuracy claims (skills 29, orchestrator path exists, `--knowledgebase` real, removed dirs don't exist) against the filesystem/CLI rather than trusting the coder's report, and diff-audited the old vs new README to prove no actionable content was lost. Even a small docs change warrants the verify-before-trust loop.
+
+**Agent tuning notes:**
+- **coder**: For README/doc rewrites, run the fact-verification pass FIRST (counts, paths, flags) and keep a checklist of claims you changed; verify every command against `package.json` scripts and every flag against `--help` before writing. After the edit, run markdownlint (0 structural errors) and grep to confirm no command/table/option was dropped.
+- **reviewer**: For docs pipelines, perform independent accuracy spot-checks (skill counts via filesystem, paths via `ls`, flags via `--help`, existence of removed/kept references) and diff-audit against the old version to confirm only non-actionable content was removed — distinguish "dropped" (fluff) from "lost" (actionable). A single informational nit (global vs package skill) is exactly what an accuracy-focused review catches.
+- **tracker**: Record the doc-accuracy verification pattern as universal — the "skill count wrong / path wrong / flag missing / removed dirs still referenced" cluster is the recurring failure mode in README maintenance, and the fix pattern (verify against filesystem + CLI `--help` before writing, then reviewer re-verification) applies to any documentation that enumerates filesystem entities or CLI surface.
+
+## Session: 2026-08-03 — Vocab-Sync: Pre-commit Auto-Update of Memory-Bank Vocabulary JSON
+
+**Pipeline:** implementer (bootstrap) → implementer (planning) → coder (Batch A: 7 parallel) → coder (Batch B: 3 parallel) → unit-tester → reviewer (⚠️ CHANGES REQUESTED) → coder (review fixes) → reviewer (✅ APPROVED) → tracker
+**Coverage:** 259/259 tests passing across 12 files, 0 failures; setup suite 104/104 across 6 files; vocab-sync.js 98.91% stmts / 92.15% branch / 100% lines; validate-memory-schema.js 92.7% stmts / 93.1% branch / 92.47% lines (both ≥ 90% gate)
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **Staged-files-only pre-commit auto-sync is the right scope for vocabulary maintenance** — `scripts/vocab-sync.js` scans ONLY staged memory-bank files (`git diff --cached --name-only --diff-filter=ACM`, `memory-bank/*.md`, excluding `/.index/`), builds a known-tag set from ALL `tags.*` group values PLUS `entity_patterns` keys, normalizes candidates (lowercase → kebab-case, drop empty, dedupe), appends genuinely-new tags to the `topic` catch-all group (sorted, idempotent), and runs `git add memory-bank/.vocabulary.json` inside try/catch so the vocab commits with the same change. Warning-only contract: exits 0 in every graceful path (no staged files → silent; missing/malformed vocab → warn + skip); only unhandled errors exit 1. Scanning ALL memory-bank files instead would produce noisy writes from unrelated files — the staged diff is the only thing that matters in a pre-commit context.
+- **Sync-before-validate ordering eliminates the chicken-and-egg false positive** — `vocab-sync.js` must run BEFORE `validate-memory-schema.js` in the pre-commit hook (both this repo's `.husky/pre-commit` and the setup tool's `TEMPLATE_HOOKS['pre-commit'].content`), so first-time tags are appended to `.vocabulary.json` before the validator's unknown-tag check. Verified empirically in a scratch temp git repo: staged `brand-new-tag` → vocab-sync appended it → validator ran with NO unknown-tag warning, exit 0 → second vocab-sync run was a silent no-op (idempotent). **Universal pattern:** when a validator warns about data that a companion tool can auto-heal, order the healer FIRST in the same hook.
+- **`entity_patterns` keys are known tags — a validator can produce false-positive warnings by ignoring them** — the original trigger was pre-commit warnings `[float32array, learned-knowledge, npm, package-structure, readme]`; the validator only checked `tags.*` groups, but entity/tool names (`npm`, `vitest`, `playwright`, …) live as `entity_patterns` keys, not tags. Fix: `allTags = [...Object.values(vocab.tags).flat(), ...Object.keys(vocab.entity_patterns || {})]` with a `|| {}` guard so a vocab lacking the key doesn't crash. **Universal pattern:** when auditing "unknown X" warnings, enumerate ALL places valid values can live, not just the obvious collection.
+- **Normalization PARITY between producer and consumer is a hidden correctness requirement (reviewer M1)** — vocab-sync normalizes tags (lowercase/kebab) but the validator originally compared raw frontmatter tags exactly, so a mixed-case `My Tag` still warned on every commit after vocab-sync appended `my-tag` — the chicken-and-egg fix was incomplete for non-normalized tags, and no test covered it (all 15 validator tests used lowercase). Fix: the validator applies the SAME `normalizeTag` to both frontmatter tags and vocab `allTags` before the unknown-tag filter (+3 tests: `My Tag` no longer flagged once `my-tag` in vocab; controls still warn). **Universal pattern:** when two tools normalize the same input, they must normalize IDENTICALLY — duplicate the normalization on both sides or the "known" set drifts.
+- **Strict JSON forbids comment syntax in docs instructions (reviewer M2)** — an instruction telling agents to "add a one-line comment in the JSON" is impossible in strict JSON; following it literally corrupts `.vocabulary.json`. The correct instruction: record rationale in the commit message/PR/review report or in existing string fields like `categories` descriptions, with an explicit "strict JSON — no comment syntax" warning. **Universal pattern:** before writing documentation that instructs editing a data file, verify the instruction is valid for that file's format — reviewers should grep doc instructions for format-illegal suggestions.
+- **Consumer-controlled malformed data needs array guards (reviewer minor 1)** — `buildKnownTags` iterates `Object.values(vocab.tags)`; if a consumer's `vocab.tags` is an array (or a group is a plain string), iterating a group directly walks CHARACTERS instead of tags. The `if (!Array.isArray(group)) continue;` guard before iteration is the fix (+2 malformed-shape tests). **Universal pattern:** any code parsing a consumer/maintainer-editable JSON file must defend against shape surprises, not just missing keys.
+- **Test-fixture parity with the real sync array is what catches distribution regressions (reviewer minor 3)** — `scripts/sync.test.js` had a hand-maintained `scriptsToSync` fixture that omitted `vocab-sync.js`, so a future removal from the real array would go uncaught. Fix: fixture now byte-matches the real 7-entry array (vocab-sync adjacent to validator). **Universal pattern:** when a distribution list (sync array, files list, manifest) has a test fixture, keep them byte-identical — fixture drift silently disables the regression guard.
+- **Consumer distribution of a hook script is layered and must be wired in EVERY channel** — the new script reaches consumers via: (1) npm tarball (`files` includes `scripts/`), (2) `sync.js` `scriptsToSync` (copies to consumer's `scripts/`), (3) the hook CONTENT via setup `TEMPLATE_HOOKS['pre-commit'].content` (written by `npx ai-workflow-setup`). All three must be updated or a consumer gets a hook line pointing at a missing script. The setup hook tests needed ZERO edits because `expectedContent()` auto-derives from `TEMPLATE_HOOKS` — the marker-first idempotency detection (`discover.js` compares only the first line) survives mid-content additions.
+- **`isDirectRun` testability seam is the established convention for direct-run scripts** — `vocab-sync.js` and `validate-memory-schema.js` both use `process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)` + `export { … }`, matching `mcp-knowledgebase-server.js`. Importing in tests triggers no side effects; direct execution is unchanged. The validator's first-ever test suite (15 tests + 3 M1 tests) was enabled by this seam.
+
+**Agent tuning notes:**
+- **implementer (planning)**: Map the distribution mechanism BEFORE writing tasks — this plan's key insight was that a hook script needs FOUR channels (npm files, scriptsToSync, TEMPLATE_HOOKS content, and the repo's own hook file) and each channel is a distinct task. The parallel-batch table (A: 7 files, all disjoint; B: 3 tests) again prevented collisions — but note T10 required an ADDITIONAL seam change to `validate-memory-schema.js` that T3 also touched; batch planning should flag when a Batch B test task requires modifying a Batch A production file (the seam was additive, so no conflict occurred).
+- **coder (parallel batches)**: When one batch task adds a testability seam to a file another task modifies, keep the seam purely additive (new import + guard + exports, no behavior change) to stay collision-safe. Preserve file metadata on hook edits — the `.husky/pre-commit` executable bit (100755) survived the one-line insertion. For hook template changes, update the hook's `description` string too, not just the content array.
+- **unit-tester**: Prove non-vacuity with real temp mutations even for small features — removing the `entity_patterns` merge fails validator TEST-01/04; disabling the new-tag append fails 14 vocab-sync tests. Scratch-repo smoke tests (git init → stage file with new tag → run hook scripts in order → assert no warning → re-run assert idempotent) are the definitive end-to-end proof for pre-commit features. M1 re-verification must use a mixed-case tag (`My Tag`), not just lowercase — lowercase-only fixtures hid the parity gap.
+- **reviewer**: For auto-heal/validator pairs, check NORMALIZATION PARITY (does the consumer compare against the same normalized set the producer writes?) — this was the M1 catch no test covered. Grep doc instructions for format-illegal suggestions (JSON comments) before approving. Probe consumer-controlled data shapes (tags-as-array, string group) in addition to missing keys. Verify test fixtures against the real production array for distribution features.
+- **tracker**: Record sync-before-validate ordering, normalization parity, and "verify doc instructions are format-legal" as universal patterns — all three are reusable beyond vocab-sync (any auto-generated data file with a validator, any producer/consumer pair with normalization, any JSON-format documentation).
+
+## Session: 2026-08-03 — Knowledge-Vector Gap Closure with Graceful-Failure KB Access
+
+**Pipeline:** implementer (planning) → coder (4 parallel batches A–D, 18 tasks) → unit-tester (independent validation) → reviewer (⚠️ CHANGES REQUESTED) → coder (fix pass M1+M2+B1-B4) → reviewer (✅ APPROVED) → tracker
+**Coverage:** 14 files / 273 tests, 0 failures; 14/14 new spec-wiring tests (6 grep-based + 8 orchestrator-parity); 0 production code changed (docs/spec wiring only)
+**TDD Iterations:** 0 (docs/spec wiring pipeline, not TDD)
+
+**New knowledge:**
+- **Shared-protocol-file pattern beats inline duplication for cross-cutting agent behavior** — the 3-layer knowledge-retrieval protocol (memory-bank → learned-knowledge → knowledgebase_search → project files) lives ONCE in `.agents/instructions/knowledge-retrieval.instructions.md`; 14 agent specs + orchestrator templates only REFERENCE it with a single line each. Inline duplication would have been ~112 lines of repeated text and any graceful-failure wording change would require updating all 14 files (duplication drift is a proven risk — the old "Check Memory Bank" step already drifted between agents). **Universal pattern:** when N files must share identical behavioral text, extract a shared instruction file and reference it; keep the shared file the single source of truth. `memory-bank.instructions.md` was the pre-existing precedent.
+- **Graceful-failure contract: "mandatory to ATTEMPT, graceful to fail" with non-optional explicit reporting** — the governing user requirement: the PG knowledgebase is mandatory to attempt but MUST NOT be a hard dependency. Every agent (a) attempts `knowledgebase_knowledgebase_search` wrapped in try/catch, (b) on success notes "knowledgebase_search executed — N results returned.", (c) on error/unavailability notes "knowledgebase_search NOT executed (PG vector unavailable)." and continues (never blocks, fails, or retries), and (d) states the outcome in its FINAL SUMMARY — the disclosure is not optional. Accountability comes from the explicit report: agents can't silently skip; they must declare "accessed" or "skipped". **Universal pattern:** any optional external service integration should pair "attempt is mandatory" with "failure is graceful" and "outcome is reported" — the report requirement is what prevents silent degradation from becoming permanent.
+- **Grep-based spec-integrity tests with occurrence-count guards are the right regression guard for docs-wiring** — `tests/spec-knowledge-retrieval.test.js` (6 tests) reads the REAL spec files from disk (`fs.readFileSync` + `String.includes`, repo-root from `import.meta.url`, no external deps) and asserts the wiring exists; `tests/spec-orchestrator-parity.test.js` (8 tests) extracts fenced delegation blocks robustly (trimmed fence detection, marker classification by stable placeholders like `Work on "{work_unit}"` — NOT hardcoded line numbers) and adds **occurrence-count guards** (`knowledge-retrieval.instructions.md` = exactly 2 in main orchestrator, `knowledgebase_knowledgebase_search` = exactly 2 in feature-pipeline, `knowledge-retrieval.instructions.md` = exactly 6 in TDD). Occurrence counts catch BOTH missing AND duplicate injections — a naive `.includes()` check can't distinguish one copy from three. **Universal pattern:** for "every file must reference X exactly once" invariants, count occurrences, don't just check presence.
+- **Orchestrator delegation-template symmetry is a first-class review dimension** — the audit found asymmetric knowledge injection across delegation types (parallel-coder dropped learned-knowledge + architecture-context vs standard; TDD Phase 5 reviewer had ZERO injection). The fix made all delegation templates symmetric and the parity tests enforce it. The reviewer's B4 catch (main orchestrator parallel-coder lacked architecture-context while feature-pipeline had it) proved that even after the main fix, cross-orchestrator symmetry needs explicit checking. **Universal pattern:** when orchestrators delegate to the same set of agents, every delegation type/phase should carry the SAME context lines (memory-bank, learned-knowledge, architecture-context, knowledgebase) — audit horizontally (across types) AND vertically (across phases).
+- **Plan-authoritative FILE mapping is essential when delegating parallel tasks — coders must verify against the plan, not assume** — in this pipeline the orchestrator's initial batch summary guessed T3→coder, but the plan's FILE-xx table authoritatively assigned T3→architect, T4→coder, T8→implementer. The coders followed the plan, avoiding same-file collisions. **Universal pattern:** in a parallel delegation, the plan's explicit per-task FILE assignment is the source of truth; a coder receiving a task should verify its target file against the plan's FILE table rather than trusting a parent summary — and a parent should not "correct" a child who followed the plan.
+- **Retrieval LAYERS ≠ storage TIERS — two numbering systems collide** — the shared protocol numbers retrieval order L1=Memory Bank/L2=Learned Knowledge/L3=Knowledgebase, while `knowledgebase.instructions.md` documented a storage taxonomy L1=Markdown/L2=Memory Bank/L3=Knowledgebase. Same "L3" label, different meanings — reviewer M2 caught the drift. Fix: relabel the storage taxonomy to **"Tier N"** (Tier 1 Markdown / Tier 2 Memory Bank / Tier 3 Knowledgebase) with an explicit disambiguation note. **Universal pattern:** when two documents use numbered taxonomies for related-but-distinct concepts, use different label families (Layer vs Tier) and add an explicit cross-reference note — numbered collisions are silent correctness traps.
+- **Canonical phrase parity across files is a real review finding (B1)** — `knowledgebase.instructions.md` said "executed — N results." while the shared protocol says "executed — N results returned."; a reviewer caught the drift. **Universal pattern:** when a phrase is contractually required (the explicit-report phrases), grep for exact-parity across all files that quote it — near-identical wording quietly becomes a different contract.
+- **New tests outside `scripts/` require a `vitest.config.ts` include extension** — the project's config only included `scripts/**/*.test.{js,ts}`, so `tests/spec-knowledge-retrieval.test.js` would never be collected. Extended to `['scripts/**/*.test.{js,ts}', 'tests/**/*.test.{js,ts}']` (does not affect Playwright `.spec.ts`). **Universal pattern:** before planning a test file in a directory not yet covered by the test-runner include, verify the include glob — a test that is never collected is a false sense of security.
+- **The tracker pre-append read closes the duplicate-session risk** — the tracker's new step 1 requires reading `.agents/instructions/learned-knowledge.instructions.md` BEFORE appending a Session, to review existing sessions for related patterns and avoid duplicate/contradictory entries (REQ-06). This meta-requirement was itself a task in the pipeline (T11). **Universal pattern:** any agent that APPENDS to a growing knowledge file should READ the file first — append-without-read is how contradictions accumulate.
+
+**Agent tuning notes:**
+- **implementer (planning)**: When an audit reveals "declared but unreferenced" capabilities (e.g., knowledgebase instructions declared MANDATORY but zero agents referenced it), plan a shared protocol file + per-file one-line references rather than inline text; include an explicit FILE-xx mapping table so parallel coders can verify targets; scope `plan.agent.md`-style standalone agents out explicitly (ALT) to prevent scope creep.
+- **coder (parallel batches)**: Verify your assigned target file against the plan's FILE table, not a parent summary — the plan is authoritative; keep each task to exactly ONE file (disjoint batches prevented all collisions); preserve YAML frontmatter + sequential step numbering; for a shared protocol file, never edit it in a later fix pass unless the task says so (the fix pass left the shared file 0-diff).
+- **unit-tester**: For docs-wiring pipelines, build grep-based tests that read the REAL files (fs + String.includes) rather than mocks — they assert the actual repo state; add occurrence-count guards for "exactly once" invariants; independently re-run the full suite and spot-check files at the exact lines the coders claimed (never trust coder counts).
+- **reviewer**: Add delegation-template symmetry to the review checklist — compare standard vs parallel-coder context lines, and every TDD phase; grep for hard-dependency language ("must succeed", "required to function") and for exact-phrase parity across files; distinguish storage tiers from retrieval layers when numbering taxonomies; for doc-only pipelines, confirm the shared protocol file has 0 diff in the fix round.
+- **tracker**: Execute the pre-append read of learned-knowledge before writing a Session (this pipeline's own step 1); record the knowledgebase outcome (executed vs NOT executed) in the tracker summary per the protocol; capture "declared-but-unreferenced" as a recurring audit class — this pipeline's entire trigger was an instruction file declaring a mandate that no agent actually followed.
+
+## Session: 2026-08-03 — KB Consolidation + projectId Standardization (data-consolidation safety)
+
+**Pipeline:** implementer (planning) → coder (Batch A: 6 parallel) → coder (T2 sequential SQL delete) → coder (Batch B: 2 parallel) → coder (T10 sequential) → unit-tester → reviewer (✅ APPROVED) → tracker
+**Coverage:** 15 files / 284 tests, 0 failures; setup 104/104; store consolidated 5 projects/53 chunks → 4 projects/37 chunks (zero data loss); 0 production code changed (docs + DB operation only)
+**TDD Iterations:** 0 (process/data pipeline, not TDD)
+
+**New knowledge:**
+- **Data-consolidation safety pattern: RE-INDEX FROM SOURCE, THEN DELETE with transactional guards** — when two rows/projects hold duplicate content and a canonical source file exists (`learned-knowledge.instructions.md` is the source of truth), the fail-safe order is: (1) re-index the canonical target idempotently (`knowledgebase_index` upsert: "Indexed 1, updated 15" → canonical 16 chunks), (2) verify the canonical target is complete (≥ expected count), (3) delete the duplicate with transactional guards. The delete is never reached if the re-index fails (SEC-01/DEP-01). Rejected alternatives: UPDATE-in-place (violates the `uq_knowledge_chunk (project_id, session_date, content_hash)` unique constraint — 15/16 chunks collided with existing canonical rows), content-level merge (high complexity, zero benefit), delete-first (data-loss risk). **Universal pattern:** whenever data is duplicated across identity variants and a source of truth exists, "populate-then-delete" with read-only verification gates is safer than any merge or in-place UPDATE.
+- **Canonical projectId derivation rule: `projectId` SHALL equal `require('./package.json').name`** — package.json `name` is the single source of truth; never derive projectId from directory names, orchestrator `projectName`, or display strings. Root cause of the duplicate: Pipeline 7's tracker passed the hardcoded unscoped `ai-workflow-template` (from the orchestrator's projectName) to `knowledgebase_index`, creating a second project row. **Universal pattern:** when an identity value (projectId, project name, package identifier) has a canonical definition, the canonical source must be enforced at EVERY call site and codified in a spec test — a single agent passing a display-name variant silently forks the data.
+- **`knowledgebase_index` projectId is a required write-target; `knowledgebase_search` projectId is an optional read-filter (deliberate asymmetry)** — the index tool marks `projectId` "required — from package.json name field"; the search tool keeps it "(optional)" because a read-only filter may degrade to match-all. This extends the documented search-filter vs write-target asymmetry (2026-08-02 hygiene session) into the tool documentation.
+- **Transactional parameterized SQL cleanup when the CLI lacks a command** — the knowledgebase CLI has no delete command (sync/search/list/stats only). T2 used a temp Node script (in OS temp dir, NOT in repo) with `pg`: `BEGIN` → verify project row exists + chunk count = exactly 16 (pre-delete COUNT guard) + canonical ≥ 16 → `DELETE FROM projects WHERE id='ai-workflow-template'` (rowCount 1; `ON DELETE CASCADE` removed 16 chunks) → verify 0 chunks remain + totals → `COMMIT` (ROLLBACK on any guard failure). Parameterized to avoid injection; temp script outside the repo leaves zero artifacts. **Universal pattern:** when a data operation lacks a CLI surface, a guarded transactional script with verify-before-commit is the safe fallback — never a bare SQL string.
+- **`ON DELETE CASCADE` makes project-level cleanup safe AND is the same FK that caused the registerProject bug** — deleting the `projects` row cascades to all 16 `knowledge_chunks` rows. The FK that produced the 2026-08-02 registerProject 23503 failure is the same mechanism that makes consolidation cleanup trivial — a design double-edged sword worth remembering.
+- **Restart-required gotcha for MCP server code changes is now codified in instructions** — the threshold-fix restart lesson (2026-08-02 housekeeping session) is now a permanent `### MCP Server Restart After Configuration Changes` section in `knowledgebase.instructions.md` + a search-tool cross-ref: a stale MCP process can return 0 results despite chunks in the DB. **Universal pattern:** when a gotcha causes silent operational confusion, promote it from a session note to a standing instruction section.
+- **Spec-wiring tests should include a NEGATIVE assertion (reviewer minor)** — `tests/spec-kb-consolidation.test.js` TEST-05 asserts the tracker spec references package.json name positively, but lacks a negative assertion that a hardcoded `projectId: 'ai-workflow-template'` fails the guidance. **Universal pattern:** for convention-enforcement tests, assert both the presence of the correct pattern AND the absence of the incorrect one — positive-only greps let a regression slip back in.
+- **Pre-existing security debt surfaced, not introduced: `.env` tracked with a live credential** — `.env` (real 32-char DATABASE_URL password) is tracked in git (added `d788f68`, no `.gitignore`). Remediation documented: rotate the credential, `git rm --cached .env`, add `.env` to `.gitignore`, purge history. The reviewer correctly labeled it PRE-EXISTING (not from this pipeline) and blocked shipping until addressed. **Universal pattern:** a docs/data pipeline is a good moment to surface tracked-secret debt; label it pre-existing and require remediation before the commit ships.
+- **Docs-only pipelines keep coverage bit-identical — use that as a regression signal** — global coverage 48.12% was bit-for-bit identical to the pre-pipeline baseline because 0 `scripts/` files changed. **Universal pattern:** in a docs-only pipeline, a coverage delta ≠ 0 would be a red flag for scope creep; identical coverage is the expected, verifiable invariant.
+
+**Agent tuning notes:**
+- **implementer (planning)**: For consolidation plans, explicitly enumerate rejected alternatives with WHY (UPDATE-in-place → unique-constraint violation; merge → complexity; delete-first → data-loss risk) — the ordering argument (populate-then-delete) is the plan's core safety claim and must be traceable. Include a COUNT-verify guard in the plan (RISK-02: pre-delete `SELECT COUNT(*)` must equal the expected chunk count).
+- **coder (T1/T2 — data operations)**: When re-indexing, confirm the upsert result counts ("Indexed X, updated Y, skipped 0") and verify store state via stats/list BEFORE the destructive step. For the delete, write a transactional parameterized script in the OS temp dir (never the repo), verify at every stage, and COMMIT only after all guards pass. Re-batching same-file tasks (T5 absorbing plan T7) avoids parallel write races.
+- **unit-tester**: For consolidation pipelines, verify store state via `knowledgebase_list`/`knowledgebase_stats` (4 projects / 37 chunks, duplicate ABSENT, canonical 16, math 16+12+3+6=37) AND grep the standardization wiring at exact lines (tracker.agent.md:30, protocol :51, knowledgebase.instructions.md:27/:192, all 3 orchestrators). Confirm the spec-wiring trio (25/25) and full suite independently — never trust coder counts.
+- **reviewer**: For data-deletion pipelines, verify the safety story independently: parameterized/transactional/guarded temp script outside the repo, zero repo artifacts, source-of-truth parity (16 `## Session:` entries = 16 canonical chunks = zero data loss), no hardcoded unscoped projectId (grep), no hard-dependency language. Separate pre-existing security issues (tracked `.env` credential) from pipeline findings and require remediation before shipping. Recommend negative assertions for convention tests.
+- **tracker**: When re-indexing learned-knowledge after a session, use the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) — NOT a short/unscoped form; this pipeline's own rule is the lesson. Record data-consolidation safety, canonical-identity-derivation, and negative-assertion hardening as universal patterns.
+
+## Session: 2026-08-03 — .env Credential Remediation + TEST-05 Hardening + Commit Pipelines 7-9 (tracked-secret remediation)
+
+**Pipeline:** implementer (planning) → coder (Batch A: T1+T2 parallel) → coder (T3 commits) → unit-tester → reviewer (✅ APPROVED with conditions) → coder (condition #1 redaction) → reviewer (⚠️ CHANGES REQUESTED — C1) → coder (C1 redaction) → reviewer (✅ APPROVED) → tracker
+**Coverage:** 15 files / 285 tests, 0 failures; spec trio 26/26; TEST-05 negative assertion non-vacuous (proven twice)
+**TDD Iterations:** 0 (security-remediation + commit pipeline, not TDD)
+
+**New knowledge:**
+- **Tracked-secret remediation pattern: `git rm --cached` + `.gitignore` + redact-all-sources + commit split `fix(security)`/`feat`** — when a real credential file (`.env` with a live `DATABASE_URL` password) is tracked in git, the safe order is: (1) `git rm --cached <file>` (stops tracking, PRESERVES the local file so tooling keeps working — SEC-04), (2) add the file to `.gitignore` (line-level entry prevents re-add), (3) verify `.env.example` remains placeholder-only, (4) scan for the credential elsewhere (`grep` with CORRECT globs — quoted `--include="*.{js,ts,md}"` brace globs are an fnmatch false-negative that silently matches nothing; use separate `--include` flags per extension), (5) commit the security fix SEPARATELY from feature work so it is visible in git log (ALT-02 rejected single-commit). The two-commit split keeps the security signal auditable. Credential rotation + history purge (`git filter-repo`) are MANUAL user steps the agent cannot automate (remote PG access / destructive force-push) — document them in the commit body and plan.
+- **Redaction must cover ALL sinks — commit trees, working tree, memory-bank, vector index incl. WAL** — this pipeline's two reviewer loops proved that "the commit is clean" is NOT the end state. Sinks where the secret reappeared: (1) untracked plan file held the raw value 3× (commit-tree redaction missed the untracked file); (2) pipeline agents' own uncommitted memory-bank entries QUOTED the full value inside backticked grep verification commands (activeContext.md:887, progress.md:2306, tasks/_index.md:17) — validation-report quoting re-entrenches the leak. Vector-index sinks: the local `memory-bank/.index/memory.db` binary + WAL retained the pre-redaction value even after the source files were redacted; `memory_bank_memory_rebuild` alone was insufficient — a **VACUUM** was needed to purge WAL residue (reviewer-actioned). **Universal pattern:** after any secret redaction, verify with `git grep -F` (0 hits), then `rg` the full value repo-wide, then rebuild/purge every derived index (memory-bank vector index incl. WAL/SHM, PG knowledgebase re-index) — grep-clean sources do not imply grep-clean derived artifacts.
+- **Untracked secret-bearing files are a re-leak footgun — redact + commit or delete** — an untracked file containing the secret (the remediation plan itself) is one `git add -A` away from shipping the leak into new history. The reviewer made it condition #1 (🟡 major). The accepted fix: redact all occurrences to `<REDACTED>`, verify `grep -c` 0 + `git grep HEAD` 0, then COMMIT the redacted file so it becomes part of the tracked corpus (a redacted remediation plan is valuable documentation; an untracked one is a hazard). Never leave a secret-bearing file untracked "temporarily."
+- **The `9sso…` 5-char truncated-prefix redaction convention is traceable without reconstructable** — keeping a short prefix of the leaked value (few chars) provides grep-ability for regression scanning while being insufficient to reconstruct the secret. It is now the established convention across commit trees, working tree, memory-bank entries, and this tracker log. Informational review note confirmed it: "cannot reconstruct secret; consistent with accepted convention."
+- **Negative-assertion hardening for spec tests (closing the Pipeline 9 minor)** — `tests/spec-kb-consolidation.test.js` TEST-05 gained a negative assertion: a deterministic flat file list (22 files across `.opencode/.agents/scripts`) is grepped for `/projectId\s*[:=]\s*['"]ai-workflow-template['"]/g` and the match count must be 0. Key design choices: the flat list (RISK-06) is intentionally explicit — adding a new agent/script file requires extending the test, which is exactly when an audit should trigger; `learned-knowledge.instructions.md` is documented-excluded (historical journal legitimately documents the pattern — scanning it would false-fail); the regex covers `:` (JS object), `=` (assignment), and markdown forms while scoped `@abarcenas/...` never matches. **Non-vacuity was proven twice** (coder + unit-tester): temp-injecting the pattern into `tracker.agent.md` makes the test FAIL listing the offender, restore → PASS. **Universal pattern:** convention-enforcement tests assert BOTH the presence of the correct pattern AND the absence of the incorrect one, and must be mutation-proven to actually detect a violation.
+- **Reviewers should NOT append to a dirty memory-bank to avoid entrenching a leak** — when the working tree already contains the secret (C1 state), a reviewer appending their verdict would ADD another copy of the value to tracked files, deepening the leak before the fix lands. The reviewer in this pipeline deliberately skipped the memory-bank append and reported the leak instead. **Universal pattern:** before ANY agent appends to memory-bank/activeContext/progress during a security-remediation pipeline, grep the working tree for the secret — if dirty, fix first, then document.
+- **`--no-verify` for doc-only commits is justified when the pre-commit hook auto-bumps the version** — the Husky `bump-version.js` would bump `package.json` on doc-only changes; `--no-verify` skips ALL hooks (incl. memory-schema validation), so the mitigation is: commit with `--no-verify`, then manually run `node scripts/validate-memory-schema.js` (exit 0) + `node scripts/vocab-sync.js` (idempotent no-op) post-commit. Never skip the manual validation — it is the compensating control.
+- **Leak origin + history exposure are a permanent fact once pushed to a public remote** — `d788f68` (containing the credential) exists on the public GitHub remote; new clean commits do NOT undo that exposure. The only defenses are rotation (invalidates the password) and, if desired, `git filter-repo --path .env --invert-paths` + force-push (destructive — user decision). Document the leak origin explicitly in the plan/commit body; it is the difference between "we fixed the file" and "the credential was exposed."
+
+**Agent tuning notes:**
+- **implementer (planning)**: For a tracked-secret remediation plan, enumerate the manual user steps explicitly (rotation SQL, `.env` update, history-purge decision) and label them as non-automatable constraints (CON-01). Include a 12-item TEST matrix covering git state (`git ls-files`, `ls -la`), grep-based leak scans, TEST-05 non-vacuity, and post-commit diff checks. Call out the `--no-verify` + manual-validation compensating control when hooks auto-bump versions. Note that grep brace-glob `--include` patterns are fnmatch-broken — specify per-extension `--include` flags instead.
+- **coder (T2/.env remediation)**: Verify `.env.example` is placeholder-only BEFORE untracking `.env` (abort if real credentials). Use `git rm --cached` (NOT `git rm`) to preserve the local file. When scanning for the leaked credential, use correct globs — the plan's quoted brace glob silently matched nothing (false-negative) and hid a reference in `learned-knowledge.instructions.md:201`. Before committing, redact the raw value from ANY sibling-agent notes (memory-bank) that quoted it.
+- **coder (commit T3)**: When a security fix + large feature commit must ship together, split them (`fix(security):` first, then `feat:`) so the security signal stays visible and an auditor can see exactly when the credential stopped being tracked. Use `--no-verify` for doc-only commits and re-run the validator manually. Leave NO secret-bearing file untracked — redact + commit it or delete it.
+- **coder (redaction passes)**: After redaction, verify in this order: `grep -c` on the edited file → `git grep -F` on the working tree → `git grep HEAD` on commits → `rg` the full value repo-wide (excl. `.env` local-by-design) → rebuild/purge derived indexes (`memory_update` + `memory_rebuild` + VACUUM for the memory-bank vector index). Keep the surrounding context/sentence intact when replacing a value — a redaction that mangles the documentation is a different failure.
+- **unit-tester**: Independently re-prove negative-assertion non-vacuity with a real temp mutation (inject the forbidden pattern into a scoped file → test FAILS → `git checkout` restore → PASSES). Independently verify git state: `git log --oneline -3` order, `git ls-files .env` empty, commit-scope diffs (`--name-status`), local `.env` preserved. Grep the commit TREES for the secret (`git grep`), not just the working tree.
+- **reviewer**: For a security remediation review, verify: gitignore line present, `git ls-files` empty, local file preserved, `git grep` 0 hits in HEAD AND HEAD~1, commit scopes exact, redaction complete across all committed docs. Check for the two re-leak footguns explicitly: (1) untracked secret-bearing files, (2) uncommitted working-tree entries (memory-bank) that quote the secret in verification commands — these are the classic ways a "clean" commit still leaks. When the working tree is dirty with the secret, DO NOT append your own memory-bank entry until it is fixed (appending entrenches the leak). Check derived indexes for residue (memory.db WAL) — `memory_rebuild` alone may not purge; VACUUM may be required.
+- **tracker**: When documenting a security pipeline, use ONLY the established redacted forms (`<REDACTED>` or the short truncated prefix) — never reproduce the full leaked value, including inside quoted grep commands in docs (that is exactly how the leak re-entrenched this pipeline). Record the tracked-secret remediation pattern (git rm --cached + gitignore + redact-all-sources + commit split) as a universal pattern, and reuse the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) when re-indexing this session into the PG knowledgebase.

package/.agents/instructions/memory-schema.instructions.md

@@ -64,6 +64,28 @@ When `scripts/normalize-memory.js` runs (postinstall or manual), it:
 - Does NOT overwrite existing frontmatter fields
 - Logs all auto-applied suggestions
 
+## Maintaining the Vocabulary
+
+When adding a new tag to a memory-bank file's frontmatter:
+
+1. **Check if it already exists** in `memory-bank/.vocabulary.json`:
+   - Search `tags.*` groups (all values across `agent_roles`, `workflow`, `memory_ops`, `topic`)
+   - Search `entity_patterns` keys (component/tool names like `npm`, `vitest`, `playwright`)
+2. **If it's a tool, framework, or component:** add it to `entity_patterns` as a new key with at least one regex pattern.
+3. **If it's a concept or topic:** add it to the appropriate `tags.*` group:
+   - `topic` — general concepts, technologies, domains (default catch-all)
+   - `workflow` — processes, pipelines, ceremonies
+   - `memory_ops` — memory-bank operations
+   - `agent_roles` — agent role identifiers
+4. **Tag format rules:**
+   - Lowercase only
+   - Kebab-case (hyphens for spaces, no underscores)
+   - Maximum 5 tags per file
+   - No whitespace-only or empty tags
+5. **Rationale:** Record why the tag exists in the commit message or PR description, or in the existing `categories` description strings. Strict JSON supports no comments — do NOT add comment syntax to `.vocabulary.json` (it would corrupt the file).
+
+The pre-commit hook (`vocab-sync.js`) auto-appends genuinely new tags to the `topic` group as a safety net, but manual categorization is preferred for accuracy.
+
 ## Pre-Commit Validation
 
 The husky pre-commit hook (`scripts/validate-memory-schema.js`) rejects commits where:

package/.husky/pre-commit

@@ -1,4 +1,5 @@
 # Managed by @abarcenas/ai-workflow-template setup
 
 node scripts/bump-version.js
+node scripts/vocab-sync.js
 node scripts/validate-memory-schema.js

package/.opencode/agents/architect.agent.md

@@ -26,6 +26,7 @@ You are a system architecture specialist focused on designing robust, maintainab
 1. **Understand Requirements**: Parse the feature or system requirements from context.
 2. **Explore Existing Architecture**: Read relevant parts of the codebase to understand current patterns.
 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` with architectural decisions made, then run `memory_bank_memory_update`.
+   **Query Knowledgebase**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a task-relevant query wrapped in graceful failure. State the result in your final summary.
 4. **Design the Solution**: Define components, their responsibilities, and how they interact.
 5. **Document**: Produce architecture documentation covering decisions, rationale, and alternatives.
 

package/.opencode/agents/coder.agent.md

@@ -30,7 +30,7 @@ You are a production code implementation specialist. You write clean, maintainab
    - Read the full phase section for context — understand what sibling tasks exist and how yours fits
    - Check the Parallel Execution Summary to see which batch you belong to and whether sibling tasks are running concurrently
 2. **Explore Context**: Read existing files to understand patterns, conventions, and integration points.
-3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads.
+3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. **Query Knowledgebase**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a task-relevant query wrapped in graceful failure. State the result in your final summary.
 4. **Implement**: Write production code following established patterns.
 5. **Verify**: Check that the implementation compiles/runs correctly.
 6. **Document**: Record what was accomplished in all three locations:

package/.opencode/agents/deployer.agent.md

@@ -28,8 +28,9 @@ You are a deployment and release engineering specialist focused on reliable, rep
 
 1. **Understand Requirements**: Parse the deployment needs from the prompt.
 2. **Explore Existing Setup**: Review existing CI/CD configs, deployment scripts, and infrastructure.
-3. **Implement/Configure**: Create or modify deployment configurations.
-4. **Validate**: Verify configuration syntax and simulate deployment where possible.
+3. **Check Knowledge**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the 3-layer knowledge-retrieval protocol. Use `memory_bank_memory_search`/`memory_bank_memory_get` for project context. Skim `.agents/instructions/learned-knowledge.instructions.md` for deploy/release patterns. Call `knowledgebase_knowledgebase_search` with a deployment-relevant query wrapped in graceful failure. State the result in your final summary.
+4. **Implement/Configure**: Create or modify deployment configurations.
+5. **Validate**: Verify configuration syntax and simulate deployment where possible.
 
 ## Guidelines
 

package/.opencode/agents/designer.agent.md

@@ -32,9 +32,10 @@ You are a UI/UX design specialist focused on creating intuitive, accessible, and
 1. **Understand Requirements**: Parse the design needs from the prompt or orchestrator context.
 2. **Explore Existing Patterns**: Review existing components, styles, and design tokens in the codebase.
 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` to reflect design decisions, then run `memory_bank_memory_update`.
-4. **Check Latest API**: Use Context7 MCP to fetch current TailwindCSS v4+ and daisyUI v5+ APIs — avoids deprecated patterns and leverages newest features.
-5. **Design Specification**: Produce design specs, component blueprints, and styling guidance for the coder agent to implement.
-6. **Validate**: Check for accessibility, responsiveness, and consistency in your specifications.
+4. **Query Knowledgebase**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a design/UI-relevant query wrapped in graceful failure. State the result in your final summary.
+5. **Check Latest API**: Use Context7 MCP to fetch current TailwindCSS v4+ and daisyUI v5+ APIs — avoids deprecated patterns and leverages newest features.
+6. **Design Specification**: Produce design specs, component blueprints, and styling guidance for the coder agent to implement.
+7. **Validate**: Check for accessibility, responsiveness, and consistency in your specifications.
 
 ## Guidelines
 

package/.opencode/agents/e2e-tester.agent.md

@@ -26,10 +26,11 @@ You are a browser debugging and exploration specialist. You inspect pages, analy
 ## Approach
 
 1. **Understand What to Investigate**: Parse the debugging/exploration request from the prompt.
-2. **Open Page**: Use `chrome-devtools_navigate_page` or `chrome-devtools_new_page` to open the target URL.
-3. **Investigate**: Use Chrome DevTools tools to inspect the page — snapshot, screenshot, console messages, network requests, evaluate scripts.
-4. **Document Findings**: Write findings to a .md document describing what was discovered.
-5. **Clean Up**: Close pages when done using `chrome-devtools_close_page`.
+2. **Check Knowledge**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the 3-layer knowledge-retrieval protocol. Use `memory_bank_memory_search`/`memory_bank_memory_get` for project context. Skim `.agents/instructions/learned-knowledge.instructions.md` for browser/debugging patterns. Call `knowledgebase_knowledgebase_search` with a debugging/exploration-relevant query wrapped in graceful failure. State the result in your final summary.
+3. **Open Page**: Use `chrome-devtools_navigate_page` or `chrome-devtools_new_page` to open the target URL.
+4. **Investigate**: Use Chrome DevTools tools to inspect the page — snapshot, screenshot, console messages, network requests, evaluate scripts.
+5. **Document Findings**: Write findings to a .md document describing what was discovered.
+6. **Clean Up**: Close pages when done using `chrome-devtools_close_page`.
 
 ## Guidelines
 

package/.opencode/agents/implementer.agent.md

@@ -28,6 +28,7 @@ You are an implementation planning specialist. You translate architecture and de
 1. **Analyze Input**: Read the architecture doc, design spec, or requirements.
 2. **Explore Codebase**: Understand existing code patterns, conventions, and integration points.
 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` to reflect what was planned, then run `memory_bank_memory_update`.
+   - **Query Knowledgebase**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a planning-relevant query wrapped in graceful failure. State the result in your final summary.
 4. **Define Tasks**: Break the work into atomic, ordered tasks with:
    - Exact file paths and line numbers
    - Specific changes or additions needed