@abarcenas/ai-workflow-template 1.43.0 → 1.45.0

package/.agents/instructions/agent.instructions.md

@@ -12,7 +12,7 @@ Instructions for creating effective and maintainable custom agent files that pro
 - Target audience: Developers creating custom agents for opencode
 - File format: Markdown with YAML frontmatter
 - File naming convention: lowercase with hyphens (e.g., `test-specialist.agent.md`)
-- Location: `.agents/agents/` directory (repository-level) or `.opencode/agents/` directory
+- Location: `.opencode/agents/` directory (repository-level)
 - Purpose: Define specialized agents with tailored expertise, tools, and instructions for specific tasks
 - Official documentation: [opencode.ai](https://opencode.ai)
 
@@ -191,7 +191,7 @@ Structure each step invocation with:
 ```text
 Step 1: Transform raw input data
 Agent: data-processor
-Spec: .agents/agents/data-processor.agent.md
+Spec: .opencode/agents/data-processor.agent.md
 Context: projectName, basePath
 Input: basePath/raw/
 Output: basePath/processed/
@@ -199,7 +199,7 @@ Expected: write basePath/processed/summary.md
 
 Step 2: Analyze processed data (depends on Step 1 output)
 Agent: data-analyst
-Spec: .agents/agents/data-analyst.agent.md
+Spec: .opencode/agents/data-analyst.agent.md
 Context: projectName, basePath
 Input: basePath/processed/
 Output: basePath/analysis/
@@ -363,7 +363,7 @@ When invoking a sub-agent, pass all context through descriptive instructions in
 Example (prompt template):
 
 ```text
-This phase must be performed as the agent "documentation-writer" defined in ".agents/agents/documentation-writer.agent.md".
+This phase must be performed as the agent "documentation-writer" defined in ".opencode/agents/documentation-writer.agent.md".
 
 IMPORTANT:
 - Read and apply the entire .agent.md spec.
@@ -394,19 +394,19 @@ Example of a simple orchestrator that validates code through multiple specialize
 ```text
 Step 1: Security Review
 Agent: security-reviewer
-Spec: .agents/agents/security-reviewer.agent.md
+Spec: .opencode/agents/security-reviewer.agent.md
 Context: repository name, PR number, base path
 Output: security-review.md
 
 Step 2: Test Coverage
 Agent: test-coverage
-Spec: .agents/agents/test-coverage.agent.md
+Spec: .opencode/agents/test-coverage.agent.md
 Context: repository name, PR number, base path
 Output: coverage-report.md
 
 Step 3: Aggregate
 Agent: review-aggregator
-Spec: .agents/agents/review-aggregator.agent.md
+Spec: .opencode/agents/review-aggregator.agent.md
 Context: repository name, PR number, base path
 Output: final-review.md
 ```
@@ -456,7 +456,7 @@ Use consistent variable naming conventions:
 
 ### Repository-Level Agents
 
-- Location: `.agents/agents/` or `.opencode/agents/`
+- Location: `.opencode/agents/`
 - Scope: Available only in the specific repository
 - Access: Uses repository-configured MCP servers from `opencode.json`
 
@@ -491,7 +491,7 @@ Use consistent variable naming conventions:
 ### File Structure
 
 - [ ] Filename follows lowercase-with-hyphens convention
-- [ ] File placed in correct directory (`.agents/agents/` or `.opencode/agents/`)
+- [ ] File placed in correct directory (`.opencode/agents/`)
 - [ ] Filename uses only allowed characters
 - [ ] File extension is `.agent.md`
 
@@ -564,7 +564,7 @@ Use consistent variable naming conventions:
 ### Organizational Issues
 
 - ❌ Filename doesn't reflect agent purpose
-- ❌ Wrong directory (using `.github/agents/` instead of `.agents/agents/`)
+- ❌ Wrong directory (using `.github/agents/` instead of `.opencode/agents/`)
 - ❌ Using spaces or special characters in filename
 - ❌ Duplicate agent names causing conflicts
 

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,136 @@
 - **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.
+
+## Session: 2026-09-14 — Stale Path Reference Cleanup + Env-Var Fail-Fast (vendor-neutral defaults)
+
+**Pipeline:** coder (2 tasks) → reviewer (✅ APPROVED) → tracker
+**Coverage:** N/A (documentation + Python helper scripts only; Vitest suite 15 files / 285 tests unaffected)
+**TDD Iterations:** 0 (quick-fix pipeline, not TDD)
+
+**New knowledge:**
+- **A ported instruction file can carry a mechanically-renamed but non-existent path for months** — `.agents/instructions/agent.instructions.md` referenced `.agents/agents/` in 10 places because the original Copilot→opencode port mechanically substituted `.github/agents/` → `.agents/agents/` (logged at `docs/tracker-log.md` line 109 of the 2026-06-25 standalone entry) without verifying the directory exists. All real agent specs live in `.opencode/agents/`. **Universal pattern:** after any bulk find-and-replace/rebase of path references, verify EACH new path exists on disk — a plausible-looking rename (`.github/agents/` → `.agents/agents/`, both in the `.agents/` family) is exactly the kind of change that silently produces a dead path.
+- **Freeze historical audit-trail docs; fix only live docs** — `docs/tracker-log.md`, `docs/.orchestrator-log.md`, `memory-bank` history, and `learned-knowledge.instructions.md` deliberately keep the literal `.agents/agents` string as an accurate record of past state; editing them would falsify the audit trail. This is the third pipeline to apply the "historical documentation freeze" precedent (MCP Config Rename, README trim). **Universal pattern:** when correcting a stale reference, classify hits into live vs historical and only edit live docs.
+- **Vendor-neutral defaults: fail fast on an unset env var instead of hardcoding a model** — replacing `os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5")` with `os.environ.get("CAVEMAN_MODEL")` + an explicit `RuntimeError` when unset removes a vendor lock-in default and converts a silent misconfiguration into an actionable failure. **Universal pattern:** a template/distributed tool should not hardcode a vendor-specific model/endpoint default; require the env var and fail with a message that NAMES the variable and shows the format (`export CAVEMAN_MODEL="<model-id>"`).
+- **Fail-fast exceptions must not be swallowed by sibling `except` clauses** — the `RuntimeError` is raised INSIDE the `try:` whose sibling handler is `except ImportError: pass` (which falls through to the `claude --print` CLI fallback). Because `RuntimeError` is not an `ImportError`, it correctly propagates. The reviewer explicitly verified this propagation path (the narrow except must not be broadened to a bare `except:`). **Universal pattern:** when adding a fail-fast raise inside an existing try/except, confirm the exception type is not caught by any handler in scope.
+- **Byte-identical duplicate files must be edited in lockstep and verified with `cmp`** — `.agents/skills/compress/` and `.agents/skills/caveman-compress/` hold duplicate `compress.py` copies; the fix was applied to both and the reviewer confirmed byte-identity via `cmp`. **Universal pattern:** duplicated files drift silently — edit all copies together and make `cmp`/`diff` a verification step, not just a claim.
+- **`CAVEMAN_MODEL` is required but undocumented** — after making the env var mandatory, the skill docs (`.agents/skills/compress/SKILL.md`, `.agents/skills/caveman-compress/SKILL.md`, `.agents/skills/caveman-compress/README.md`, `.agents/skills/caveman-compress/SECURITY.md`) still mention only `ANTHROPIC_API_KEY` and the CLI fallback. **Universal pattern:** whenever a code change makes a new env var/flag REQUIRED, grep the docs for the sibling env vars (here `ANTHROPIC_API_KEY`) and add the new one to the same sections — a required config knob that is undocumented is a support trap.
+
+**Agent tuning notes:**
+- **coder**: For a stale-path task, enumerate ALL hits first and split "live docs" from "historical audit trail"; remap a non-existent referenced filename to the REAL equivalent you verify on disk (here `implementation-plan.agent.md` → `implementer.agent.md`) rather than inventing a file. For env-var defaults, grep for sibling copies of the script and keep them byte-identical.
+- **reviewer**: Independently verify (a) each relinked target exists, (b) 0 stale refs remain in live docs only, (c) the fail-fast exception actually propagates past narrower `except` clauses, and (d) duplicated files are byte-identical. Flag doc/`.gitignore` gaps (an undocumented required env var; untracked `__pycache__`) as NON-blocking recommendations rather than blockers when core behavior is correct.
+- **tracker**: Record the "bulk path rename must be existence-verified" and "vendor-neutral fail-fast default" patterns as universal — both recurred here (a long-ago ported instruction file; a vendor default copied into two duplicate scripts). When a pipeline touches only docs + non-test helper scripts, state explicitly that the Vitest suite is unaffected.
+
+## Session: 2026-09-14 — Pipeline 11 Follow-ups (required-env-var docs + multi-commit auto-bump side effect)
+
+**Pipeline:** coder (3 tasks) → reviewer (✅ APPROVED) → deployer (5 atomic commits) → tracker
+**Coverage:** N/A (documentation + `.gitignore` + agent frontmatter only; Vitest suite unaffected)
+**TDD Iterations:** 0 (quick-fix follow-up pipeline, not TDD)
+
+**New knowledge:**
+- **Required-env-var documentation must describe EACH auth/branch path, not just the var's existence** — the `CAVEMAN_MODEL` docs added in this pipeline are deliberately conditional: "When `ANTHROPIC_API_KEY` is set, the script calls the Anthropic API directly and REQUIRES `CAVEMAN_MODEL` … it fails fast with a clear error if unset. When relying on the `claude` CLI fallback, no model variable is needed." Writing a bare "`CAVEMAN_MODEL` is required" would be wrong — it only applies to one of the two branches. **Universal pattern:** when a required config knob applies to only one code path, document the conditional (which path requires it, which does not) — an unconditional claim misleads users of the other path. This extends the prior session's "required env var must be documented alongside sibling env vars" with *which branch* precision.
+- **A partial auth-behavior doc is still incomplete — enumerate every branch** — the reviewer flagged (non-blocking) that the "`anthropic` SDK not installed" edge is undocumented. The actual control flow has three states: (1) API key set + SDK importable → direct API + requires `CAVEMAN_MODEL`; (2) API key set + SDK missing (`except ImportError: pass`) → falls through to the `claude` CLI (no model var); (3) API key unset → `claude` CLI. Documenting only the SDK-present and no-key paths leaves the middle state implied. **Universal pattern:** when documenting a try/except-fallback flow, count the branches and describe each — a two-path description of a three-path flow is a latent support trap.
+- **Precisely inventory a large PRE-EXISTING diff before committing — never blind `git add`** — the pipeline committed a 14-file working-tree diff it did not author (the `model:` frontmatter removals, mtime 2026-09-13). The coder characterized it exactly first: 14 files, exactly **one deletion each** (0 insertions/1 deletion per file, 1-deletion hunk, no other changes), two distinct values (`deepseek/deepseek-v4-pro` ×7 / `deepseek/deepseek-v4-flash` ×7), and `git grep '^model:' HEAD -- .opencode/agents` returning the same 14 files. That inventory made a scoped, atomic `chore(agents): remove hardcoded model bindings from agent definitions` commit safe and reviewable. **Universal pattern:** a pre-existing diff must be inventoried (`git diff --stat` + per-file hunk inspection) and committed with a scope-accurate message; blind staging can mix unrelated hunks or ship unexpected deletions.
+- **Committing a PRIOR pipeline's uncommitted docs is a valid close-the-loop move** — the deployer's `docs:` commit (`4f84947`) shipped the previous Pipeline 11 tracker record (tracker-log entry + index rows + learned-knowledge session + memory-bank updates) that had been written but never committed. Previously this work was left in the working tree (Pipeline 11's own note: "No commit made by this pipeline — the orchestrator handles staging/commit"). Committing it as its own `docs:` commit closed the loop and left a clean tree. **Universal pattern:** when a pipeline leaves documentation uncommitted, a later deployer step should commit it as a correctly-scoped `docs:` commit rather than letting it accumulate indefinitely.
+- **The Husky pre-commit `bump-version.js` hook auto-bumps the MINOR version on EVERY commit and has no `SKIP_BUMP` guard** — across this pipeline's 5 sequential commits, `package.json` moved **1.44.0 → 1.49.0** (+0.1.0 × 5) with no intended release. The deployer deliberately did **not** use `--no-verify` (contrast Pipeline 10, where `--no-verify` + manual validator re-run was the compensating control). This is the second time the auto-bump has bitten (first documented 2026-08-02). **Universal pattern:** with an unconditional bump-on-commit hook, an N-commit pipeline produces N minor bumps — before cutting a release, either settle/revert the version or add a `SKIP_BUMP` env guard; and when `--no-verify` IS used, always re-run `validate-memory-schema.js` + `vocab-sync.js` manually.
+- **Docs + `.gitignore` + YAML-frontmatter changes leave the test suite bit-identical** — no test-relevant surface changed, so the Vitest suite was explicitly declared unaffected. **Universal pattern:** state this invariant explicitly when a pipeline touches no test/`scripts/` surface, so the missing coverage delta is not mistaken for a regression signal.
+
+**Agent tuning notes:**
+- **coder**: For doc follow-ups, describe every branch of the code path being documented (primary + fallback + edge like SDK-missing) and prefer a complete-sentence section (e.g. `## Configuration`) when the rule is conditional; a terse one-liner invites ambiguity. When a pre-existing diff is to be committed, inventory it first (`git diff --stat`, per-file hunk check) and never stage blindly.
+- **reviewer**: For doc-only changes, verify wording precision against the ACTUAL code branches — flag terse/ambiguous lines (e.g. `README.md:84`) and missing branches (the "SDK not installed" edge) as non-blocking minors. Confirm the documented fail-fast still matches the code's exception type and propagation.
+- **deployer**: Before a multi-commit pipeline, check the pre-commit hook for an unconditional version bump and count the expected bumps (N commits → N minor bumps here); plan to settle the version or add a `SKIP_BUMP` guard before release. Commit pre-existing diffs with a scope-accurate message derived from the inventory. Commit any lingering prior-pipeline docs as a separate `docs:` commit.
+- **tracker**: Record the auto-bump as an explicit side effect with the exact version delta (`1.44.0 → 1.49.0`) whenever a multi-commit pipeline runs; note when a deployer has committed a prior pipeline's provisional record. Reuse the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) when re-indexing this session.
+
+## Session: 2026-09-14 — Pipeline 11 Final Polish (doc nits + version settle + `SKIP_BUMP` opt-out)
+
+**Pipeline:** coder (4 tasks) → reviewer (✅ APPROVED) → deployer (4 commits) → tracker
+**Coverage:** N/A (docs + a comment-only script change + a version constant; Vitest suite unaffected)
+**TDD Iterations:** 0 (quick-fix follow-up pipeline, not TDD)
+
+**New knowledge:**
+- **The long-recommended `SKIP_BUMP` opt-out is now implemented as an additive pre-write guard — and it was exercised on the very commits that introduced it.** `scripts/bump-version.js` now checks `if (process.env.SKIP_BUMP) { log + process.exit(0) }` at lines 9–15, BEFORE reading or writing `package.json`; the default (unset) path is unchanged. The deployer ran all 4 commits with `SKIP_BUMP=1`, and the hook logged "SKIP_BUMP set — version bump skipped" each time, leaving the settled `1.45.0` stable. **Universal pattern:** when you add an opt-out flag for a hook that fires on every commit, use that flag on the commits that introduce it — self-dogfooding is both the proof the guard works and the way to keep the batch's own version stable. This also closes the recommendation first recorded 2026-08-02 and repeated 2026-09-14 (Pipeline 11 Follow-ups). Prefer this opt-out over `--no-verify`, which skips ALL hooks (including memory-schema validation).
+- **Settling an N-commit auto-bump batch: target = pre-batch base parent's version + exactly one bump, not a guessed number.** `package.json` had drifted `1.44.0 → 1.49.0` over the 5-commit follow-up batch (the hook bumps minor on EVERY commit). The correct settled value was derived from `git show 267da69^:package.json` → base `1.44.0`, and one logical change set ⇒ one bump ⇒ `1.45.0` (reverting the four spurious bumps `1.46.0`–`1.49.0`). **Universal pattern:** to undo spurious bump-on-commit drift, compute the target from the base commit's PARENT (`<base_commit>^`) plus a single bump — the post-batch current value tells you how far it drifted but not where it should settle.
+- **JS truthy-string footgun for env-var flags: `SKIP_BUMP=0` and `SKIP_BUMP=false` are non-empty strings and therefore TRUTHY — they also skip the bump.** The documented contract is "set `SKIP_BUMP=1`", but the guard as written accepts ANY non-empty value. Flagged as non-blocking M-1; a strict parse (`value === '1' || value === 'true'`) would close it. **Universal pattern:** an `if (process.env.X)` guard treats `"0"`/`"false"`/`"no"` as enabled — if the flag is meant to be numeric/boolean, parse it explicitly rather than relying on string truthiness.
+- **A stale lockfile is a separate concern from the manifest version — do not "fix" it inside a version-settle commit.** `package-lock.json` exists but is stale at `1.34.0` (last touched `d788f68`) and does NOT mirror `package.json`; the repo's `bump-version.js` convention never syncs it. Keeping it out of scope avoided a large, unrelated lockfile churn; `npm ci --dry-run` passes, so it is not a build blocker. **Universal pattern:** when the task is "settle the manifest version," leave lockfile drift alone and flag it as pre-existing; classify pre-existing drift separately from pipeline findings.
+- **Comment-only edits to byte-identical duplicate files still require byte-identity verification.** The `except ImportError:` clarification was applied to BOTH `compress.py` copies (`.agents/skills/compress/scripts/`, `.agents/skills/caveman-compress/scripts/`) and the reviewer confirmed `cmp`/`diff` byte-identity. Runtime behavior is unchanged, so the Vitest suite is unaffected — consistent with the established "duplicated files drift silently; edit in lockstep + `cmp`" rule.
+- **A three-path try/except-fallback flow must be documented as three paths, and this pipeline actually did it.** The auth behavior now reads: (1) `ANTHROPIC_API_KEY` set + SDK installed → direct API + `CAVEMAN_MODEL` required; (2) key set but SDK missing (`except ImportError: pass`) → `claude` CLI, no model var; (3) key unset → `claude` CLI. This implements the "count the branches, describe each" rule from the prior session instead of leaving the middle state implied. **Universal pattern:** a two-path description of a three-path flow is a latent support trap — enumerate every branch.
+- **A version-settle commit does not need a CHANGELOG.** None exists in this repo; the settle is documented in the commit message + tracker record, not fabricated into a changelog file. **Universal pattern:** do not invent release-notes artifacts to justify a version change — record the rationale where the repo already keeps history.
+
+**Agent tuning notes:**
+- **coder**: For a version settle, derive the target from `<base_commit>^` + one bump and leave any stale lockfile untouched (flag it as drift). For comment-only edits to duplicated scripts, apply to every copy and verify byte-identity. When you implement a hook opt-out, verify the default path is byte-unchanged and exercise the flag (`SKIP_BUMP=1 node scripts/bump-version.js` → exit 0, manifest untouched). When documenting a try/except fallback, enumerate all three states.
+- **reviewer**: Verify the opt-out guard is placed BEFORE any read/write (additive, default unchanged) and probe the truthy-string edge — `SKIP_BUMP=0`/`false` also skip (M-1). Confirm comment-only changes leave duplicate files byte-identical and runtime unchanged. Distinguish pre-existing drift (`package-lock.json` at `1.34.0`; missing `architecture-context` vocab entity) from issues introduced by the change; a historical tracker entry referencing the pre-settle version is a frozen-record artifact, not a defect.
+- **deployer**: Use the newly added `SKIP_BUMP=1` on the commits that introduce it, rather than `--no-verify` — the guard is the targeted mitigation and keeps the other hooks (memory-schema validation, vocab-sync) running. After a version settle, verify the manifest version at HEAD and that it was committed exactly once (no re-bump), and confirm the hook logged the skip.
+- **tracker**: Record the `SKIP_BUMP` guard as IMPLEMENTED (closing the 2026-08-02 / 2026-09-14 recommendation) with the exact settle delta (`1.49.0 → 1.45.0`), and carry the non-blocking minors forward (M-1 truthy string, M-2 missing SDK qualifier in README, M-3 lockfile drift, M-4 vocab entity gap, M-5 stale historical "1.49.0" narrative). Reuse the canonical `projectId` from `require('./package.json').name` (`@abarcenas/ai-workflow-template`) when re-indexing this session.

package/.agents/skills/caveman-compress/README.md

@@ -81,6 +81,8 @@ caveman-compress/
 
 **Requires:** Python 3.10+
 
+**Model config:** When `ANTHROPIC_API_KEY` is set, `CAVEMAN_MODEL` must also be exported (e.g. `export CAVEMAN_MODEL=<model-id>`) — the script fails fast if it is unset. When using the `claude` CLI fallback, no model variable is needed.
+
 ## Usage
 
 ```

package/.agents/skills/caveman-compress/SECURITY.md

@@ -20,7 +20,9 @@
 
 ### Auth behavior
 
-If `ANTHROPIC_API_KEY` is set, the skill uses the Anthropic Python SDK directly (no subprocess). If not set, it falls back to the `claude` CLI, which uses the user's existing Claude desktop authentication.
+If `ANTHROPIC_API_KEY` is set and the Anthropic Python SDK is installed, the skill uses the SDK directly (no subprocess). If the key is not set — or the SDK is not installed — it falls back to the `claude` CLI, which uses the user's existing Claude desktop authentication.
+
+When using the Anthropic API directly (i.e. the SDK is installed), `CAVEMAN_MODEL` MUST also be exported with the model identifier (e.g. `export CAVEMAN_MODEL=<model-id>`) — the skill fails fast with a clear error if it is unset. The `claude` CLI fallback requires no model variable.
 
 ### File size limit
 

package/.agents/skills/caveman-compress/SKILL.md

@@ -35,6 +35,10 @@ cd caveman-compress && python3 -m scripts <absolute_filepath>
 
 4. Return result to user
 
+## Configuration
+
+When `ANTHROPIC_API_KEY` is set, the script calls the Anthropic API directly (when the Anthropic SDK is installed) and REQUIRES `CAVEMAN_MODEL` to be exported with the model identifier (e.g. `export CAVEMAN_MODEL=<model-id>`); it fails fast with a clear error if unset. If the Anthropic SDK is not installed, it falls back to the `claude` CLI, which requires no model variable.
+
 ## Compression Rules
 
 ### Remove

package/.agents/skills/caveman-compress/scripts/compress.py

@@ -78,15 +78,22 @@ def call_claude(prompt: str) -> str:
         try:
             import anthropic
 
+            model = os.environ.get("CAVEMAN_MODEL")
+            if not model:
+                raise RuntimeError(
+                    "CAVEMAN_MODEL environment variable is not set. "
+                    "Set it to the model identifier to use for compression "
+                    '(e.g. export CAVEMAN_MODEL="<model-id>").'
+                )
             client = anthropic.Anthropic(api_key=api_key)
             msg = client.messages.create(
-                model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
+                model=model,
                 max_tokens=8192,
                 messages=[{"role": "user", "content": prompt}],
             )
             return strip_llm_wrapper(msg.content[0].text.strip())
         except ImportError:
-            pass  # anthropic not installed, fall back to CLI
+            pass  # anthropic SDK not installed → fall back to CLI (no CAVEMAN_MODEL needed)
     # Fallback: use claude CLI (handles desktop auth)
     try:
         result = subprocess.run(

package/.agents/skills/compress/SKILL.md

@@ -35,6 +35,10 @@ cd <directory_containing_this_SKILL.md> && python3 -m scripts <absolute_filepath
 
 4. Return result to user
 
+## Configuration
+
+When `ANTHROPIC_API_KEY` is set, the script calls the Anthropic API directly (when the Anthropic SDK is installed) and REQUIRES `CAVEMAN_MODEL` to be exported with the model identifier (e.g. `export CAVEMAN_MODEL=<model-id>`); it fails fast with a clear error if unset. If the Anthropic SDK is not installed, it falls back to the `claude` CLI, which requires no model variable.
+
 ## Compression Rules
 
 ### Remove

package/.agents/skills/compress/scripts/compress.py

@@ -78,15 +78,22 @@ def call_claude(prompt: str) -> str:
         try:
             import anthropic
 
+            model = os.environ.get("CAVEMAN_MODEL")
+            if not model:
+                raise RuntimeError(
+                    "CAVEMAN_MODEL environment variable is not set. "
+                    "Set it to the model identifier to use for compression "
+                    '(e.g. export CAVEMAN_MODEL="<model-id>").'
+                )
             client = anthropic.Anthropic(api_key=api_key)
             msg = client.messages.create(
-                model=os.environ.get("CAVEMAN_MODEL", "claude-sonnet-4-5"),
+                model=model,
                 max_tokens=8192,
                 messages=[{"role": "user", "content": prompt}],
             )
             return strip_llm_wrapper(msg.content[0].text.strip())
         except ImportError:
-            pass  # anthropic not installed, fall back to CLI
+            pass  # anthropic SDK not installed → fall back to CLI (no CAVEMAN_MODEL needed)
     # Fallback: use claude CLI (handles desktop auth)
     try:
         result = subprocess.run(

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

@@ -6,7 +6,6 @@ permission:
   search: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Architect - System Design
@@ -26,6 +25,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

@@ -8,7 +8,6 @@ permission:
   execute: "allow"
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Coder - Implementation
@@ -30,7 +29,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

@@ -9,7 +9,6 @@ permission:
   "github/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Deployer - Release Engineering
@@ -28,8 +27,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

@@ -6,7 +6,6 @@ permission:
   search: "allow"
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Designer - UI/UX
@@ -32,9 +31,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

@@ -7,7 +7,6 @@ permission:
   "chrome-devtools/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # E2E Tester - Browser Automation
@@ -26,10 +25,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

@@ -8,7 +8,6 @@ permission:
    execute: allow
    "memory-bank/*": allow
    "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Implementer - Implementation Planning
@@ -28,6 +27,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

@@ -8,7 +8,6 @@ permission:
   todo: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Feature Pipeline
@@ -17,7 +16,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 +102,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 +136,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

@@ -13,7 +13,6 @@ permission:
   "chrome-devtools/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Orchestrator - Multi-Agent Workflow
@@ -22,7 +21,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 +120,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 +154,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

@@ -8,7 +8,6 @@ permission:
   todo: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # TDD Orchestrator - Test-Driven Development
@@ -17,7 +16,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 +131,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 +158,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 +202,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 +245,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 +286,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 +311,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/plan.agent.md

@@ -9,7 +9,6 @@ permission:
   question: allow
   webfetch: allow
   websearch: allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Plan Mode - Strategic Planning & Architecture Assistant

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

@@ -9,7 +9,6 @@ permission:
   "context7/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-pro
 ---
 
 # Technical spike research mode
@@ -72,7 +71,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

@@ -8,7 +8,6 @@ permission:
   "github/*": allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Reviewer - Code Quality
@@ -25,6 +24,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

@@ -9,7 +9,6 @@ permission:
   write: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Tracker - Documentation Recorder
@@ -22,15 +21,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

@@ -8,7 +8,6 @@ permission:
   execute: allow
   "memory-bank/*": allow
   "knowledgebase/*": allow
-model: deepseek/deepseek-v4-flash
 ---
 
 # Unit Tester - Test Coverage
@@ -25,11 +24,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/AGENTS.md

@@ -6,13 +6,13 @@ This project includes AI-assisted development configuration distributed through
 
 - `.agents/instructions/` — Language, framework, and workflow instructions
 - `.agents/skills/` — Reusable skill definitions for task-based workflows
-- `.agents/agents/` — Specialized agent definitions for planning, research, and implementation
+- `.opencode/agents/` — Specialized agent definitions for planning, research, and implementation
 - `.agents/prompts/` — Reusable prompt templates
 
 ## Core Workflow
 
 1. **Understand before acting** — Read relevant instructions from `.agents/instructions/` before working with specific technologies
-2. **Plan before implementing** — Use `.agents/agents/plan.agent.md` or `.agents/agents/implementation-plan.agent.md` patterns for structured work
+2. **Plan before implementing** — Use `.opencode/agents/plan.agent.md` or `.opencode/agents/implementer.agent.md` patterns for structured work
 3. **Track progress** — Update `memory-bank/activeContext.md` and `memory-bank/progress.md` after each task (see `.agents/instructions/task-implementation.instructions.md`)
 4. **Maintain context** — Keep memory bank files updated (see `.agents/instructions/memory-bank.instructions.md`)
 
@@ -81,7 +81,7 @@ Prompts in `.agents/prompts/` can be invoked directly:
 
 ## Available Agent Workflows
 
-These agent workflows (from `.agents/agents/`) define specialized modes of operation. Invoke the relevant workflow at the start of a task by stating which mode you want to activate.
+These agent workflows (from `.opencode/agents/`) define specialized modes of operation. Invoke the relevant workflow at the start of a task by stating which mode you want to activate.
 
 ### Plan Mode — Strategic Planning & Architecture
 

package/README.md

@@ -229,7 +229,7 @@ All memory-bank files use YAML frontmatter (`id`, `title`, `updated`, `tags`, `e
 
 ## Versioning
 
-Husky auto-bumps versions on every commit: minor by default (`1.2.0 → 1.3.0`), patch resets to 0 on each bump, and major changes reset to `<major>.0.0`. No manual version management required.
+Husky auto-bumps versions on every commit: minor by default (`1.2.0 → 1.3.0`), patch resets to 0 on each bump, and major changes reset to `<major>.0.0`. No manual version management required. Set `SKIP_BUMP=1` (e.g. `SKIP_BUMP=1 git commit ...`) to skip the bump for that commit — useful for doc-only changes.
 
 ## Publish Flow
 

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.45.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": {

package/scripts/bump-version.js

@@ -6,6 +6,13 @@ import { fileURLToPath } from 'url'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const pkgPath = resolve(__dirname, '../package.json')
 
+// Opt-out: SKIP_BUMP=1 keeps the current version (e.g. when a batch of commits
+// is one logical change set and should yield a single bump).
+if (process.env.SKIP_BUMP) {
+  console.log('SKIP_BUMP set — version bump skipped')
+  process.exit(0)
+}
+
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
 const current = pkg.version
 const [curMajor, curMinor] = current.split('.').map(Number)