@abarcenas/ai-workflow-template 1.43.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

@@ -334,3 +334,76 @@
 - **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/.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

package/.opencode/agents/orchestrator/feature-pipeline.agent.md

@@ -17,7 +17,7 @@ You are a lightweight orchestration agent that runs a fixed sequential pipeline:
 
 ## Dynamic Parameters
 
-- **projectName**: The project or component being worked on (extracted from user request)
+- **projectName**: The project or component being worked on (extracted from user request (prefer package.json "name" for the canonical scoped projectId))
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
@@ -103,6 +103,7 @@ IMPORTANT:
 - Previous step context: {previous_step_summary}
 - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
 - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+- Knowledgebase: call `knowledgebase_knowledgebase_search` with a task-relevant query using the graceful-failure protocol defined in `.agents/instructions/knowledge-retrieval.instructions.md`. Report whether executed or skipped in your final summary.
 - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. 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`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
 - Return a clear summary (actions taken + files produced/modified + issues).
 ```
@@ -136,7 +137,10 @@ When the pipeline reaches the "coder" step and the latest implementer plan has p
       - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
       - Perform the necessary reads/writes under this base path.
       - Previous step context: {previous_step_summary}
-- Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. 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`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
+      - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. 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`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
+      - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+      - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
+      - Knowledgebase: call `knowledgebase_knowledgebase_search` with a task-relevant query using the graceful-failure protocol defined in `.agents/instructions/knowledge-retrieval.instructions.md`. Report whether executed or skipped in your final summary.
       - Return a clear summary (actions taken + files produced/modified + issues).
       ```
    d. **Wait for all tasks in this batch to complete** (fan-in). Capture each response summary.

package/.opencode/agents/orchestrator/orchestrator.agent.md

@@ -22,7 +22,7 @@ You are a master orchestration agent that coordinates specialized sub-agents to
 
 ## Dynamic Parameters
 
-- **projectName**: The project or component being worked on (extracted from user request)
+- **projectName**: The project or component being worked on (extracted from user request (prefer package.json "name" for the canonical scoped projectId))
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
@@ -121,6 +121,8 @@ IMPORTANT:
 - Perform the necessary reads/writes under this base path.
 - Previous step context: {previous_step_summary}
 - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. 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`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a task-relevant query (graceful failure — report whether executed or skipped). Skim `.agents/instructions/learned-knowledge.instructions.md` for role-relevant patterns. State the retrieval outcome in your final summary.
+- Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
 - Return a clear summary (actions taken + files produced/modified + issues).
 ```
 
@@ -153,6 +155,8 @@ When the pipeline reaches the "coder" step and the implementer's summary include
       - Perform the necessary reads/writes under this base path.
       - Previous step context: {previous_step_summary}
       - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. 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`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
+      - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a task-relevant query (graceful failure — report whether executed or skipped). Skim `.agents/instructions/learned-knowledge.instructions.md` for role-relevant patterns. State the retrieval outcome in your final summary.
+      - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
       - Return a clear summary (actions taken + files produced/modified + issues).
       ```
    d. **Wait for all tasks in this batch to complete** (fan-in). Capture each response summary.

package/.opencode/agents/orchestrator/tdd-orchestrator.agent.md

@@ -17,7 +17,7 @@ You are a Test-Driven Development orchestration agent that enforces a strict RED
 
 ## Dynamic Parameters
 
-- **projectName**: The project or component being worked on (extracted from user request)
+- **projectName**: The project or component being worked on (extracted from user request (prefer package.json "name" for the canonical scoped projectId))
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
@@ -132,6 +132,7 @@ IMPORTANT:
 - The batches within each table must respect dependency order (Batch A has no deps, Batch B depends on Batch A completing, etc.).
 - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
 - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads.
 - After completing the plan, update `memory-bank/activeContext.md` and `memory-bank/progress.md`, then run `memory_bank_memory_update`.
 - Return a clear summary including: plan file path, number of test tasks, number of implementation tasks, batch breakdown per table.
@@ -158,6 +159,7 @@ IMPORTANT:
    IMPORTANT:
    - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
    - TDD CONTEXT: This is the RED phase. You are writing tests that define expected behavior BEFORE any implementation code exists. These tests SHOULD fail when run — that is correct and expected in TDD.
+   - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
    - Work on "Write tests for task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
    - Read the plan file to understand the full spec, interfaces, and expected behaviors.
    - Write comprehensive tests covering: happy path, error cases, edge cases, boundary values.
@@ -201,6 +203,7 @@ IMPORTANT:
    IMPORTANT:
    - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
    - TDD CONTEXT: This is the GREEN phase. Write the MINIMAL production code necessary to pass all existing tests. Do NOT add features beyond what the tests specify. The tests were written first and define the contract you must fulfill.
+   - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
    - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
    - Read the plan file for full context and the corresponding test file(s) for the exact expected behavior.
    - Write production code that makes ALL related tests pass.
@@ -243,6 +246,7 @@ IMPORTANT:
   - Passed: {count}
   - Failed: {count} (with details for each failure)
   - Code coverage percentage (statement, branch, function, line — whichever the project's coverage tool reports)
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - The minimum coverage threshold is {minCoverage}%. Report whether this threshold is met.
 - If any tests FAIL: provide the failure details (file, line, error message, expected vs actual).
 - If coverage is BELOW {minCoverage}%: identify which files/modules have the lowest coverage and suggest additional test cases.
@@ -283,6 +287,7 @@ IMPORTANT:
   - Test and implementation code follow project conventions.
   - No security vulnerabilities were introduced.
   - Error handling is adequate and tested.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - Base path: "{basePath}".
 - Read the plan file for context on what was supposed to be built.
 - Previous step context: All tests passed with {coverage}% coverage (threshold: {minCoverage}%).
@@ -307,6 +312,7 @@ IMPORTANT:
 - Base path: "{basePath}".
 - Read the orchestrator log at "docs/.orchestrator-log.md" for the full pipeline record.
 - Read any artifact files referenced in the log.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - Append documentation entries to "docs/tracker-log.md".
 
 Pipeline summary:

package/.opencode/agents/researcher.agent.md

@@ -72,7 +72,15 @@ You are a read-only research agent. You do NOT write code, edit source files, or
 
 ## Research Process
 
-### 0. Investigation Planning
+### 0a. 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 relevant research patterns and ecosystem findings
+- Call `knowledgebase_knowledgebase_search` with queries relevant to the spike's technology domains, past patterns, and known gotchas
+- State the result in your final summary
+
+### 0b. Investigation Planning
 
 - Create comprehensive todo list using #todos with all known research areas
 - Parse spike document completely using #codebase

package/.opencode/agents/reviewer.agent.md

@@ -25,6 +25,7 @@ You are a code review specialist. You never write code — you read, analyze, an
 
 ## Approach
 
+0. **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 and known issues. Skim `.agents/instructions/learned-knowledge.instructions.md` for review patterns, known bug classes, and security gotchas. Call `knowledgebase_knowledgebase_search` with review-relevant queries (common vulnerability patterns, recurring code-quality issues). State the result in your final summary.
 1. **Understand Scope**: Determine what code needs review (files, diff, or full module).
 2. **Read Thoroughly**: Read all relevant files completely before forming opinions.
 3. **Analyze Systematically**: Check in order: correctness → security → performance → style → test quality.

package/.opencode/agents/tracker.agent.md

@@ -22,15 +22,17 @@ You are a documentation specialist. You never write code — you read agent outp
 - Extract what was accomplished, what files were produced, and key decisions
 - Append a structured entry to `docs/tracker-log.md`
 - Append a summary entry to `memory-bank/progress.md` with the same structured information, then run `memory_bank_memory_update`
-- Append a new `## Session:` entry to `.agents/instructions/learned-knowledge.instructions.md` after every pipeline, recording discoveries, patterns, gotchas, and agent tuning notes for future cross-project reference
+- Append a new `## Session:` entry to `.agents/instructions/learned-knowledge.instructions.md` after every pipeline, recording discoveries, patterns, gotchas, and agent tuning notes for future cross-project reference — BEFORE appending, read the existing file first (see step 1 "Check Knowledge") to review existing sessions and avoid duplicate or contradictory entries
 
 ## Approach
 
-1. **Read Context**: Read the orchestrator log at `docs/.orchestrator-log.md` to understand what steps ran, their status, artifacts, and key findings.
-2. **Read Artifacts**: Read the actual files produced by the sub-agents (referenced in the log).
-3. **Determine Target Path**: From the orchestrator context, determine the `docs/<feature>/<agent>.md` path for this entry.
-4. **Compose Entry**: Create a documentation entry summarizing the step's work.
-5. **Append**: Append the entry to the target path determined in step 3.
+1. **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. **Critically**: read `.agents/instructions/learned-knowledge.instructions.md` BEFORE appending a new Session entry — review existing sessions for related patterns to avoid duplicate or contradictory entries. Call `knowledgebase_knowledgebase_search` with queries matching the pipeline type and agent roles to surface relevant cross-project patterns, wrapped in graceful failure — on success report "knowledgebase_search executed — N results returned."; on error/unavailability report "knowledgebase_search NOT executed (PG vector unavailable)." and continue (never block or fail). State the result in your final summary.
+   **projectId derivation for `knowledgebase_knowledgebase_index`**: when indexing the Session entry, the `projectId` parameter SHALL be read from `package.json` `name` (`require('./package.json').name` — the canonical scoped name, e.g., `@abarcenas/ai-workflow-template`), NOT from the orchestrator's `projectName` parameter (which may be a short/unscoped display name). The `package.json` `name` field is the single source of truth — deriving projectId from directory names, display strings, or hardcoded short forms creates duplicate KB projects.
+2. **Read Context**: Read the orchestrator log at `docs/.orchestrator-log.md` to understand what steps ran, their status, artifacts, and key findings.
+3. **Read Artifacts**: Read the actual files produced by the sub-agents (referenced in the log).
+4. **Determine Target Path**: From the orchestrator context, determine the `docs/<feature>/<agent>.md` path for this entry.
+5. **Compose Entry**: Create a documentation entry summarizing the step's work.
+6. **Append**: Append the entry to the target path determined in step 4.
 
 ## Documentation Entry Format
 

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

@@ -25,11 +25,12 @@ You are a testing specialist focused on unit and integration tests.
 
 ## Approach
 
-1. **Understand the Code**: Read the implementation files to understand what needs testing.
-2. **Review Existing Tests**: Look at existing test files for patterns and conventions.
-3. **Write Tests**: Create comprehensive tests following project testing conventions.
-4. **Run Tests**: Execute the test suite to verify all tests pass.
-5. **Fix Issues**: Address any test failures or flaky tests.
+1. **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 test patterns, mock conventions, and testing gotchas. Call `knowledgebase_knowledgebase_search` with testing-relevant queries (test patterns, mock strategies, coverage approaches). State the result in your final summary.
+2. **Understand the Code**: Read the implementation files to understand what needs testing.
+3. **Review Existing Tests**: Look at existing test files for patterns and conventions.
+4. **Write Tests**: Create comprehensive tests following project testing conventions.
+5. **Run Tests**: Execute the test suite to verify all tests pass.
+6. **Fix Issues**: Address any test failures or flaky tests.
 
 ## Guidelines
 

package/memory-bank/.vocabulary.json

@@ -49,19 +49,29 @@
     ],
     "topic": [
       "agent-exercise",
+      "agents",
       "chunk-parser",
+      "commit",
+      "credential",
       "dotenv",
       "embeddings",
+      "env-remediation",
       "feature-vocab-sync",
       "fix-kb-registerproject",
       "float32array",
+      "git",
+      "graceful-failure",
+      "knowledge-vector-gaps",
       "knowledgebase",
       "learned-knowledge",
       "mcp",
       "package-structure",
       "pgvector",
+      "pipeline-follow-up",
       "pre-commit",
       "readme",
+      "security",
+      "test-hardening",
       "vocabulary"
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.43.0",
+  "version": "1.44.0",
   "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
   "main": "index.js",
   "bin": {