@abarcenas/ai-workflow-template 1.38.0 → 1.40.0

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

@@ -164,3 +164,23 @@
 - **coder**: When executing a config rename, use the 3-name-context mental model (template name, consumer target name, documentation name) to ensure all changes are internally consistent. Verify each context independently — a change that's correct in one context may be wrong in another. The `.gitignore` entry should future-proof against related file spillover (e.g., `opencode.mcp` covers `opencode.mcp.json`, `opencode.mcp.bak`, etc.).
 - **reviewer**: Pre-existing test coverage gaps should be noted separately from issues introduced by the change. A change that is correct but reveals an existing gap is still APPROVED — the gap is a pre-existing concern, not a regression. Use the "pre-existing" label to distinguish.
 - **tracker**: The "Three naming contexts" pattern (repo template, consumer provisioning, documentation) is a reusable architectural insight for ANY config rename pipeline. It should be recorded in learned knowledge as a universal pattern, not a one-time fix. Also note the user correction acceptance loop as a pattern — researcher recommends, user validates, implementer incorporates — this validates the confirmation gate architecture.
+
+## Session: 2026-08-01 — Float32Array Test Miss Investigation
+
+**Pipeline:** Research spike → knowledgebase sync (root-cause investigation of a test failure missed by the previous pipeline)
+**Coverage:** N/A (investigation — no new production code; findings persisted to knowledgebase)
+**TDD Iterations:** 0 (spike, not a pipeline run)
+
+**New knowledge:**
+- **A failing test can ship through a 3-layer defense failure** — The `Float32Array` test bug (test expects `toBeInstanceOf(Float32Array)`, source returns plain `Array` via `Array.from(result.data)`) was missed by ALL three defenses simultaneously: (1) **Design level**: parallel coder batches (source T6/Batch A vs test T15/Batch E) wrote contradictory contracts with no cross-batch validation — source and test were even created in the SAME commit (`d788f68`) yet contradicted each other; (2) **Verification level**: the orchestrator's AI unit-tester reported "158 tests, 0 failures" when the actual vitest run was failing (`AssertionError: expected [0.1, …(383)] to be an instance of Float32Array`) — an AI analytical error, not a real test run; (3) **CI level**: GitHub Actions only triggers on `pull_request` targeting `main`, PR #23 merged in ~4 minutes (before CI could gate), and the fix commit `d93cdd3` was pushed directly to `feat/update-setup` with no PR trigger — so `main` never got external validation.
+- **pgvector 0.3.0 `toSql()` REJECTS typed arrays — verified empirically** — `toSql()` in `node_modules/pgvector/src/index.js` does `Array.isArray(value)` (line 27) and throws `'expected array or sparse vector'` otherwise. `Array.isArray(new Float32Array(384))` is `false`, so a `Float32Array` passed to `_toSql()` ALWAYS throws. The spike's Section 7 conclusion ("pgvector accepts typed arrays; `Array.from` was an unnecessary conversion") is **FALSE** for the installed version. Verified three ways: source read, `node --input-type=module` repro (`toSql(Float32Array)` → throws; `toSql(Array.from(...))` → `[0.1,…]`), and live `kb:sync` run (7/7 chunks → "Embedding failed for chunk, inserting without vector: expected array or sparse vector").
+- **The d93cdd3 "fix" (Float32Array) breaks pgvector serialization while fixing the test** — Neither extreme is correct alone: `Array.from()` in `embed()` makes the TEST fail but pgvector WORK; `new Float32Array()` makes the TEST pass but pgvector THROW, silently degrading the knowledgebase to a text store (null embeddings). The correct contract is: `embed()` returns `Float32Array` (matches the API contract AND the test), and the conversion to plain `Array` (`Array.from(vec)`) must happen at the pgvector boundary — i.e., callers do `_toSql(Array.from(vec))` before passing to pgvector. `main` (at `641240f`) currently has the working `Array.from()` version; `feat/update-setup` (`d93cdd3`) has the broken Float32Array version.
+- **Silent degradation hides library-boundary errors** — The `try/catch` in `upsertChunks()` (lines 402-405) catches the pgvector throw, logs a warning, and inserts the chunk with `null` embedding. The CLI still exits 0 and reports "Indexed X new, updated Y". Without checking vector storage (e.g., `kb:search` returning meaningful results), a broken embedding pipeline is invisible. The earlier 2026-07-30 session already documented this exact failure mode — it regressed because the "fix" was based on an unverified library assumption.
+- **Same-author same-commit contradictions** — The buggy source AND the test that would catch it were written in the same commit by the same author 44 minutes apart. Cross-file contract verification matters even within a single commit, not just across parallel batches.
+
+**Agent tuning notes:**
+- **orchestrator**: Add cross-batch contract verification to the pipeline — before declaring a batch complete, verify that exported function signatures/return types match what tests and dependent batches expect. Source contract (T6) and test contract (T15) were never compared.
+- **unit-tester**: MUST run real `npx vitest run` and parse actual output instead of relying on AI analysis alone. The reported "158 tests, 0 failures" was a hallucination/analytical error — the actual vitest run was failing. If a real test run is not possible, explicitly label the result as "AI-analyzed, not executed" so downstream agents know its confidence level.
+- **orchestrator/CI**: Make CI a required check on `main` (branch protection) so a 4-minute PR merge window cannot bypass it. Any fix must go through a PR that runs CI, not be pushed directly to a branch.
+- **researcher/coder**: Verify contested library behavior claims against the INSTALLED source before persisting them. The spike endorsed "pgvector accepts typed arrays" based on an unverified note in a fix commit; the installed `pgvector@0.3.0` source and an empirical repro prove the opposite. When a knowledgebase contains contradictory sessions about library behavior (2026-07-30 says Float32Array fails, 2026-08-01 spike says it works), run a minimal repro to settle it — never trust the newer claim by default.
+- **coder**: When fixing a type mismatch, check BOTH consumers of the value. `embed()`'s result feeds both the test assertion AND pgvector's `toSql()`. A fix that satisfies the test but breaks the DB boundary (or vice versa) is not a fix — convert at the boundary instead of changing the function's contract.

package/bin/setup.js

@@ -13,6 +13,9 @@
 //   2 — Fatal error (discovery failure or unexpected exception)
 // ═════════════════════════════════════════════════════════════════════════════
 
+// Load consumer's .env into process.env before any phase runs
+import 'dotenv/config'
+
 try {
   const { main } = await import('../scripts/setup/index.js')
   const exitCode = await main(process.argv.slice(2))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.38.0",
+  "version": "1.40.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": {
@@ -57,14 +57,14 @@
   "devDependencies": {
     "@playwright/test": "^1.59.1",
     "@vitest/coverage-v8": "^4.1.8",
-    "dotenv": "^17.4.2",
     "husky": "^9.0.0",
     "vitest": "^4.1.8"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^12.11.0",
-    "sqlite-vec": "^0.1.9"
+    "sqlite-vec": "^0.1.9",
+    "dotenv": "^17.4.2"
   },
   "optionalDependencies": {
     "@xenova/transformers": "^2.17.0",

package/scripts/knowledgebase-index.js

@@ -290,8 +290,11 @@ async function getEmbedder() {
  *
  * Uses the local @xenova/transformers pipeline with all-MiniLM-L6-v2 (384d).
  * Returns a Float32Array of 384 floats using mean pooling + L2 normalization.
- * pgvector's `toSql()` accepts both Float32Array and plain arrays, so callers
- * can rely on receiving a Float32Array.
+ *
+ * NOTE: pgvector@0.3.0's `toSql()` rejects typed arrays (`Array.isArray()`
+ * returns false for Float32Array and it throws 'expected array or sparse
+ * vector'). Callers MUST convert to a plain Array (`Array.from(vec)`) at the
+ * pgvector boundary before passing to `_toSql()`.
  *
  * @param {string} text - Text to embed
  * @returns {Promise<Float32Array>} Float32Array of 384 floats
@@ -398,7 +401,9 @@ async function upsertChunks(chunks) {
           (chunk.pipeline ? ` — Pipeline: ${chunk.pipeline}` : '') +
           `\n${chunk.content}`;
         const vec = await embed(contextText);
-        embeddingSql = _toSql(vec);
+        // pgvector toSql() requires a plain Array (Array.isArray() === true);
+        // Float32Array would throw 'expected array or sparse vector'.
+        embeddingSql = _toSql(Array.from(vec));
       } catch (embedErr) {
         console.warn('[knowledgebase] Embedding failed for chunk, ' +
           'inserting without vector:', embedErr.message);
@@ -502,7 +507,8 @@ async function search(query, options = {}) {
       WHERE embedding IS NOT NULL
         AND 1 - (embedding <=> $1) >= $2
     `;
-    const params = [_toSql(queryEmbedding), threshold];
+    // pgvector toSql() requires a plain Array (see embed() note)
+    const params = [_toSql(Array.from(queryEmbedding)), threshold];
 
     if (project_id) {
       sql += ` AND project_id = $${params.length + 1}`;

package/scripts/setup/constants.js

@@ -139,6 +139,7 @@ export const SUPPORTED_FLAGS = {
   '--skip-prepare': 'skipPrepare',
   '--skip-sync': 'skipSync',
   '--skip-knowledgebase': 'skipKnowledgebase',
+  '--knowledgebase': 'knowledgebase',
   '--help': 'help',
   '-h': 'help',
   '--version': 'version',

package/scripts/setup/index.js

@@ -141,6 +141,14 @@ export async function main(argv) {
     return EXIT_CODES.SUCCESS
   }
 
+  // When --knowledgebase is passed, run ONLY the knowledgebase phase
+  if (flags.knowledgebase) {
+    flags.skipHooks = true
+    flags.skipPrepare = true
+    flags.skipSync = true
+    flags.skipKnowledgebase = false
+  }
+
   // ── 3. Display header banner ────────────────────────────────────────────
   if (!flags.quiet) {
     header()

package/scripts/setup/index.test.js

@@ -116,6 +116,7 @@ const defaultFlags = {
   skipPrepare: false,
   skipSync: false,
   skipKnowledgebase: false,
+  knowledgebase: false,
   help: false,
   version: false,
   quiet: false,
@@ -549,6 +550,48 @@ describe('main() — setup orchestrator', () => {
     expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
   })
 
+  // ── 16b. --knowledgebase flag (T6: run ONLY the knowledgebase phase) ─────
+
+  it('--knowledgebase: runs only discovery + knowledgebase phases, exits 0', async () => {
+    parseCliArgs.mockReturnValue({ ...defaultFlags, knowledgebase: true })
+
+    const code = await main(['--knowledgebase'])
+
+    expect(code).toBe(EXIT_CODES.SUCCESS)
+    expect(parseCliArgs).toHaveBeenCalledWith(['--knowledgebase'])
+    // Discovery always runs
+    expect(discover).toHaveBeenCalledTimes(1)
+    // All other phases are skipped by the --knowledgebase shortcut
+    expect(installHooks).not.toHaveBeenCalled()
+    expect(handlePrepare).not.toHaveBeenCalled()
+    expect(initHusky).not.toHaveBeenCalled()
+    expect(runSyncPhase).not.toHaveBeenCalled()
+    // Knowledgebase phase runs
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
+    // Header and summary shown (not quiet)
+    expect(header).toHaveBeenCalledTimes(1)
+    expect(summary).toHaveBeenCalledTimes(1)
+  })
+
+  it('--knowledgebase: still runs knowledgebase phase when skipKnowledgebase was also passed', async () => {
+    // --knowledgebase forces skipKnowledgebase back to false so the phase runs
+    parseCliArgs.mockReturnValue({
+      ...defaultFlags,
+      knowledgebase: true,
+      skipKnowledgebase: true,
+    })
+
+    const code = await main(['--knowledgebase', '--skip-knowledgebase'])
+
+    expect(code).toBe(EXIT_CODES.SUCCESS)
+    expect(discover).toHaveBeenCalledTimes(1)
+    expect(installHooks).not.toHaveBeenCalled()
+    expect(handlePrepare).not.toHaveBeenCalled()
+    expect(initHusky).not.toHaveBeenCalled()
+    expect(runSyncPhase).not.toHaveBeenCalled()
+    expect(registerKnowledgebase).toHaveBeenCalledTimes(1)
+  })
+
   // ── 17. Verify parseCliArgs receives the argv ───────────────────────────
 
   it('passes argv array to parseCliArgs unchanged', async () => {

package/scripts/setup/knowledgebase.js

@@ -63,8 +63,8 @@ export async function registerKnowledgebase(context) {
   // ── DATABASE_URL check ───────────────────────────────────────────────
   if (!process.env.DATABASE_URL) {
     const message =
-      'DATABASE_URL not configured. Set up later with: ' +
-      'npx ai-workflow-template setup --knowledgebase'
+      'DATABASE_URL not configured. Set DATABASE_URL in your .env file, ' +
+      'then re-run: npx @abarcenas/ai-workflow-template --knowledgebase'
     logWarn(
       `[knowledgebase] Skipping Phase 6 \u2014 ${message}`,
     )

package/scripts/setup/knowledgebase.test.js

@@ -161,8 +161,12 @@ describe('registerKnowledgebase', () => {
 
     expect(result).toEqual({
       action: 'skipped',
-      message: expect.stringContaining('DATABASE_URL'),
+      message: expect.stringContaining('DATABASE_URL not configured'),
     })
+    // The warning must guide the consumer to set DATABASE_URL and re-run
+    // with the scoped package name and the --knowledgebase flag.
+    expect(result.message).toContain('@abarcenas/ai-workflow-template')
+    expect(result.message).toContain('--knowledgebase')
     expect(spawn).not.toHaveBeenCalled()
   })
 

package/scripts/setup/ui.js

@@ -422,6 +422,8 @@ export function help() {
     skipHooks: 'Skip git hook installation phase',
     skipPrepare: 'Skip prepare script modification phase',
     skipSync: 'Skip file sync phase',
+    skipKnowledgebase: 'Skip knowledgebase registration phase',
+    knowledgebase: 'Run ONLY the knowledgebase registration phase',
     help: 'Show this help message and exit',
     version: 'Show the version number and exit',
     quiet: 'Suppress non-error output (quiet mode)',
@@ -435,6 +437,8 @@ export function help() {
     'skipHooks',
     'skipPrepare',
     'skipSync',
+    'skipKnowledgebase',
+    'knowledgebase',
     'help',
     'version',
     'quiet',
@@ -446,7 +450,7 @@ export function help() {
   write(`${BLD}${PACKAGE_NAME}${RST} ${GRN}v${version}${RST}`)
   write()
   write(`  ${BLD}Usage:${RST}`)
-  write(`    npx ${PACKAGE_NAME} setup [options]`)
+  write(`    npx ${PACKAGE_NAME} [options]`)
   write(`    ${BIN_NAME} [options]`)
   write()
   write(`  ${BLD}Description:${RST}`)
@@ -468,9 +472,10 @@ export function help() {
 
   write()
   write(`  ${BLD}Examples:${RST}`)
-  write(`    npx ${PACKAGE_NAME} setup`)
-  write(`    npx ${PACKAGE_NAME} setup --dry-run --verbose`)
-  write(`    npx ${PACKAGE_NAME} setup --force --skip-hooks`)
+  write(`    npx ${PACKAGE_NAME}`)
+  write(`    npx ${PACKAGE_NAME} --dry-run --verbose`)
+  write(`    npx ${PACKAGE_NAME} --knowledgebase`)
+  write(`    npx ${PACKAGE_NAME} --force --skip-hooks`)
   write(`    ${BIN_NAME} --help`)
   write()
 }