@abarcenas/ai-workflow-template 1.33.0 → 1.34.0

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

@@ -66,3 +66,30 @@
 - **coder**: When fixing child process output capture, consider both stdout and stderr channels independently — they serve different purposes (results vs diagnostics). `stdio: 'inherit'` is clean for real-time streaming but means stdout is no longer capturable programmatically
 - **unit-tester**: When testing child process spawn behavior, mock `child_process` spawn module rather than using real subprocesses — this avoids side effects and keeps tests fast. Use `vi.mock` with factory functions to control `stdio` arg and `env` values
 - **tracker**: Record dead-code discoveries alongside implementation details — the "existing but unused infrastructure" finding is a recurring pattern worth tracking across sessions
+
+## Session: 2026-07-24 — Fix Hook Script References for Consumer Projects
+
+**Pipeline:** researcher → implementer → coder (5 parallel tasks T1–T5) → tracker
+**Coverage:** 7/7 unit tests passing (2 existing + 5 new), 52/52 integration assertions, 13/13 MCP references verified
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **Hash-based manifest namespace pattern** — `__scripts__/<relPath>` extends the proven `.agents/` (bare path) and `__opencode__/` namespace pattern. The 3-case sync logic (new → copy, untouched → overwrite, locally modified → skip with warning) applies identically across all sync sections. No manifest version schema change needed for adding new namespace keys.
+- **Co-location constraint for imported dependencies** — `memory-cli.js` imports `'./memory-index.js'` and `mcp-memory-server.js` also imports `'./memory-index.js'`. Both the consumer-facing script AND its co-located dependency must be in the same sync array. This is an architectural constraint: if you sync one, you must sync all of its relative-import dependencies.
+- **`ensureParentDirectory()` handles nested paths automatically** — `mcp/playwright-mcp-launcher.js` lives in a subdirectory, and the existing `ensureParentDirectory()` helper (which calls `mkdirSync(dirname(filePath), { recursive: true })`) creates it without any special handling.
+- **`spawnSync` for testing modules with `process.exit()`** — `sync.js` calls `process.exit()` and cannot be imported as a module. The proven pattern: use `child_process.spawnSync` to invoke it as a child process, with `INIT_CWD` pointing to an isolated temp directory (created via `mkdtempSync`), and clean up in `afterAll`. This is the same pattern used by `sync-phase.js` in production.
+- **Two Playwright MCP patterns coexist by design** — The template's own root `opencode.json` uses `npx @playwright/mcp@latest` (modern, no file dependency), while `opencode.mcp.example.json` uses the launcher script wrapper with env var configuration (`HEADLESS`, `SLOW_MO`, `VIEWPORT`). Both serve different audiences: the template itself vs. consumer projects that may need launcher configuration.
+- **Marker comment for managed-file detection** — The `HOOK_MARKER` (`# Managed by @abarcenas/ai-workflow-template setup`) is the first line of hook files. This enables `discover.js` `isManaged` detection by reading the first line. The marker must be on line 1 for detection to work — the shebang (`#!/bin/sh`) moves to line 2, which is safe because husky sources hook files rather than executing them directly.
+- **Relative paths in hooks become valid after script sync — no hook content changes needed** — The key architectural insight: `constants.js` `TEMPLATE_HOOKS` content uses `node scripts/memory-cli.js update` which resolves correctly from the consumer root once `scripts/` exists there. Zero modifications to `constants.js`, `hooks.js`, `.husky/post-merge`, or `.husky/pre-commit` are needed.
+- **Content integrity via SHA-256 manifest tracking** — Every synced file is hashed with SHA-256. The manifest tracks `__scripts__/<relPath>` → hash. This enables idempotent re-runs (hash match → no warning), local modification detection (on-disk hash ≠ manifest hash → skip with warning), and force overwrite (`--force` ignores local modifications).
+- **Cross-file MCP reference auditing is essential** — 13 reference points across 7 files needed verification (`opencode.mcp.example.json`, `opencode.mcp.json`, `opencode.json` root, `scripts/mcp-memory-server.js`, `scripts/sync.js`, `scripts/sync.test.js`, `.agents-sync-manifest.json`, `docs/playwright-mcp-configuration.md`). Every reference from MCP configs, sync arrays, test assertions, manifest entries, and documentation must be cross-checked to ensure path resolution after sync changes — this is easy to miss.
+- **`--force` flag consistency across all sync sections** — The `--force` flag semantics are identical for `.agents/`, `.opencode/`, `__scripts__/`, and root files: it bypasses local modification protection and overwrites. This consistency should be preserved for any future sync sections.
+
+**Agent tuning notes:**
+- **researcher**: Must conduct a 6-tier script inventory with dependency chain analysis when determining sync scope. The co-location constraint (`memory-cli.js` imports `'./memory-index.js'`) was discovered by tracing `import` chains — always follow relative imports to find all files that must be co-located. Also check MCP config files (`opencode.mcp.json`, `opencode.json`) for script path references that create additional sync requirements.
+- **implementer (planning)**: When parallel batches share a dependency (Phase 2 and 3 both depend on Phase 1), verify that batch-independent tasks truly have no shared-file dependencies. T2 (test code), T3 (integration verification), T4 (audit), and T5 (documentation) all depended on T1 but were fully independent of each other — this enabled parallel execution without conflicts. The plan's explicit dependency table with "Can run in parallel?" and "Depends on" columns is essential for coder batch scheduling.
+- **coder (T1 — sync.js core logic)**: When adding a new sync section that mirrors an existing one (`.opencode/` block), copy-paste with careful variable renaming is correct and efficient. The 3-case hash logic is proven and consistent. Only 3 things need to change: (1) the tracked key namespace (`__scripts__/` instead of `__opencode__/`), (2) source/target directory paths, (3) the log prefix in verbose messages. The accumulator pattern (`scriptsCopied`/`scriptsSkipped` feeding into global `copied`/`skipped`) should also be mirrored.
+- **coder (T2 — unit tests)**: Test infrastructure for `process.exit()` modules is reusable across all sync test files — create a `createTempDir()` helper with `mkdtempSync`, a `runSync(tempDir, args)` helper using `spawnSync`, and cleanup in `afterAll`. Assertion patterns to reuse: file existence (`expect(existsSync(path)).toBe(true)`), content match (`readFileSync(path) === sourceContent`), mtime invariance for skip tests, manifest key presence, and SHA-256 hash format validation (`/^[a-f0-9]{64}$/`).
+- **coder (T3 — integration verification)**: Integration verification in a simulated consumer project requires a comprehensive test harness. The pattern: create temp consumer dir with minimal `package.json`, run sync with `INIT_CWD`, then assert on filesystem state and script execution. Content integrity via SHA-256 comparison is more reliable than byte-by-byte comparison. Test groups should cover: first-run sync, idempotent re-run, locally modified preservation, `--force` overwrite, `--dry-run`, hook path resolution, post-merge hook path, syntax validation for all synced scripts, and script execution from consumer root.
+- **coder (T4 — MCP audit)**: MCP reference auditing requires structured cross-referencing. Create a table with columns: File, Lines, Reference text, and Status. Track every reference point across ALL files, not just obvious ones (documentation references are the ones most often missed). Note architectural nuances like the two Playwright patterns (npx vs launcher script) — these are design decisions worth documenting, not bugs.
+- **tracker**: The feature-specific documentation (`docs/hook-script-references/tracker.md`) should include a "Total Results" summary section at the end with unit tests, integration assertions, MCP references, and files modified. This gives readers an executive-summary view without reading the full multi-step pipeline.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.33.0",
+  "version": "1.34.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/sync.js

@@ -171,6 +171,61 @@ if (existsSync(sourceOpenCodeDir)) {
   }
 }
 
+/* ──  Sync scripts/ directory ──────────────────────────────── */
+
+const scriptsToSync = [
+  'memory-cli.js',
+  'memory-index.js',
+  'bump-version.js',
+  'validate-memory-schema.js',
+  'mcp-memory-server.js',
+  'mcp/playwright-mcp-launcher.js',
+]
+
+const sourceScriptsDir = resolve(packageRoot, 'scripts')
+const targetScriptsDir = resolve(consumerRoot, 'scripts')
+let scriptsCopied = 0
+let scriptsSkipped = 0
+
+for (const scriptRelPath of scriptsToSync) {
+  const sourceFile = resolve(sourceScriptsDir, scriptRelPath)
+  const targetFile = resolve(targetScriptsDir, scriptRelPath)
+
+  if (!existsSync(sourceFile)) {
+    continue
+  }
+
+  const sourceHash = hashFile(sourceFile)
+  const existingHash = existsSync(targetFile) ? hashFile(targetFile) : null
+  const trackedKey = `__scripts__/${scriptRelPath}`
+  const recordedHash = manifest.files[trackedKey] ?? null
+
+  if (!existsSync(targetFile)) {
+    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    scriptsCopied += 1
+    copied += 1
+    added += 1
+    continue
+  }
+
+  const isUntouched = recordedHash !== null && existingHash === recordedHash
+
+  if (forceOverwrite || isUntouched) {
+    if (isVerbose) console.error(`  … syncing: scripts/${scriptRelPath}`)
+    syncFile(sourceFile, targetFile)
+    manifest.files[trackedKey] = sourceHash
+    scriptsCopied += 1
+    copied += 1
+    continue
+  }
+
+  scriptsSkipped += 1
+  skipped += 1
+  console.warn(`[ai-workflow-template] Skipped locally modified script file: scripts/${scriptRelPath}`)
+}
+
 for (const rootFile of rootFiles) {
   const sourceFile = resolve(packageRoot, rootFile)
   if (!existsSync(sourceFile)) {

package/scripts/sync.test.js

@@ -1,4 +1,40 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, afterAll } from 'vitest'
+import { spawnSync } from 'child_process'
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  mkdtempSync,
+  statSync,
+} from 'fs'
+import { join, dirname } from 'path'
+import { tmpdir } from 'os'
+
+const projectRoot = process.cwd()
+const tempDirs = []
+
+function createTempDir() {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sync-test-'))
+  tempDirs.push(tmpDir)
+  return tmpDir
+}
+
+function runSync(tempDir, args = []) {
+  return spawnSync('node', ['scripts/sync.js', ...args], {
+    cwd: projectRoot,
+    env: { ...process.env, INIT_CWD: tempDir },
+    encoding: 'utf8',
+  })
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
 
 describe('sync utility functions', () => {
   it('should validate basic assertions work', () => {
@@ -10,3 +46,143 @@ describe('sync utility functions', () => {
     expect(result).toBe('ai workflow template')
   })
 })
+
+describe('__scripts__ sync behavior', () => {
+  const scriptsToSync = [
+    'memory-cli.js',
+    'memory-index.js',
+    'bump-version.js',
+    'validate-memory-schema.js',
+    'mcp-memory-server.js',
+    'mcp/playwright-mcp-launcher.js',
+  ]
+
+  it('should copy scripts when they do not exist in consumer project', () => {
+    const tempDir = createTempDir()
+
+    // Create a manifest with __scripts__ entries (initial tracking)
+    const manifest = {
+      version: 1,
+      files: Object.fromEntries(
+        scriptsToSync.map((s) => [`__scripts__/${s}`, null]),
+      ),
+    }
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify(manifest, null, 2),
+    )
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Verify all 6 script files were created in the consumer's scripts/ dir
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      expect(
+        existsSync(targetFile),
+        `Expected scripts/${script} to exist`,
+      ).toBe(true)
+    }
+  })
+
+  it('should skip scripts that exist in target without manifest tracking', () => {
+    const tempDir = createTempDir()
+    const sourceScriptsDir = join(projectRoot, 'scripts')
+
+    // Pre-populate target with files matching source content (same hash)
+    // but create a manifest that has NO __scripts__ entries
+    for (const script of scriptsToSync) {
+      const sourceFile = join(sourceScriptsDir, script)
+      const targetFile = join(tempDir, 'scripts', script)
+      mkdirSync(dirname(targetFile), { recursive: true })
+      copyFileSync(sourceFile, targetFile)
+    }
+
+    // Empty manifest — no __scripts__ keys → isUntouched = false for all
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify({ version: 1, files: {} }),
+    )
+
+    // Record mtimes before sync
+    const mtimesBefore = {}
+    for (const script of scriptsToSync) {
+      mtimesBefore[script] = statSync(
+        join(tempDir, 'scripts', script),
+      ).mtimeMs
+    }
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Verify mtimes are unchanged (files were NOT overwritten)
+    for (const script of scriptsToSync) {
+      expect(statSync(join(tempDir, 'scripts', script)).mtimeMs).toBe(
+        mtimesBefore[script],
+      )
+    }
+  })
+
+  it('should force overwrite all scripts with --force', () => {
+    const tempDir = createTempDir()
+    const sourceScriptsDir = join(projectRoot, 'scripts')
+
+    // Pre-populate target with dummy content (different from source)
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      mkdirSync(dirname(targetFile), { recursive: true })
+      writeFileSync(targetFile, `// modified ${script}`)
+    }
+
+    const result = runSync(tempDir, ['--force'])
+    expect(result.status).toBe(0)
+
+    // Verify all 6 files were overwritten with source content
+    for (const script of scriptsToSync) {
+      const targetFile = join(tempDir, 'scripts', script)
+      const sourceFile = join(sourceScriptsDir, script)
+      expect(existsSync(targetFile)).toBe(true)
+      expect(readFileSync(targetFile, 'utf8')).toBe(
+        readFileSync(sourceFile, 'utf8'),
+      )
+    }
+  })
+
+  it('should show scripts in --dry-run output but not write files', () => {
+    const tempDir = createTempDir()
+
+    const result = runSync(tempDir, ['--dry-run'])
+    expect(result.status).toBe(0)
+    expect(result.stdout).toContain('dry-run')
+
+    // Verify no script files were written to disk
+    for (const script of scriptsToSync) {
+      expect(existsSync(join(tempDir, 'scripts', script))).toBe(false)
+    }
+  })
+
+  it('should track new manifest entries after sync', () => {
+    const tempDir = createTempDir()
+
+    // Create empty manifest
+    writeFileSync(
+      join(tempDir, '.agents-sync-manifest.json'),
+      JSON.stringify({ version: 1, files: {} }),
+    )
+
+    const result = runSync(tempDir)
+    expect(result.status).toBe(0)
+
+    // Read back the updated manifest
+    const updatedManifest = JSON.parse(
+      readFileSync(join(tempDir, '.agents-sync-manifest.json'), 'utf8'),
+    )
+
+    // Verify all 6 __scripts__ entries are tracked with valid SHA-256 hashes
+    for (const script of scriptsToSync) {
+      const key = `__scripts__/${script}`
+      expect(updatedManifest.files[key]).toBeDefined()
+      expect(updatedManifest.files[key]).toMatch(/^[a-f0-9]{64}$/)
+    }
+  })
+})