@dalzoubi/dev-agents-sync 2.0.26 → 2.0.28

package/README.md

@@ -105,7 +105,9 @@ For the `claude` target, `init` and `update` set up two extra pieces of project
 
 ### Steering scaffold (consumer-owned)
 
-The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions.md`, `glossary.md`, and `architecture.md` — on first run. These files are **consumer-owned**: they carry no managed-by marker, are never tracked in the lockfile, and are **never overwritten** once they exist. Agents read all three at session start and append to them; the toolkit only seeds the blank files once. Editing them is expected.
+The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions.md`, `glossary.md`, `architecture.md`, and `delivery-log.md` — on first run. These files are **consumer-owned**: they carry no managed-by marker, are never tracked in the lockfile, and are **never overwritten** once they exist. Agents read all four at session start and append to them; the toolkit only seeds the blank files once. Editing them is expected.
+
+`delivery-log.md` is the feedback channel between the two agent namespaces: `deliver-document` appends one dated retrospective per shipped feature, and `define` reads that history to calibrate future estimates and cycle budgets.
 
 ### Hook scripts (managed)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.0.26",
+  "version": "2.0.28",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/hooks.mjs

@@ -11,8 +11,15 @@
 
 import { DEFAULT_HOOK_SCRIPTS, mergeHookSettings } from './settings.mjs';
 
-/** True for a FileMap key that is a managed hook script (claude/hooks/*.sh). */
-function isHookKey(relKey) {
+/**
+ * True for a FileMap key that is a managed hook script (claude/hooks/*.sh).
+ *
+ * Exported so the content repo's hook-delivery contract test can assert against
+ * THIS predicate rather than a copy of the regex. The build and the CLI once
+ * held separate, silently divergent hook-path assumptions; binding the test to
+ * the real predicate is what keeps them from drifting apart again.
+ */
+export function isManagedHookKey(relKey) {
   const norm = relKey.replace(/\\/g, '/');
   return /^claude\/hooks\/.+\.sh$/.test(norm);
 }
@@ -32,7 +39,7 @@ function toConsumerHookPath(relKey) {
  * given FileMap keys. Used to record installed hooks in the lockfile.
  */
 export function collectHookPaths(relKeys) {
-  const paths = relKeys.filter(isHookKey).map(toConsumerHookPath);
+  const paths = relKeys.filter(isManagedHookKey).map(toConsumerHookPath);
   return [...new Set(paths)].sort();
 }
 

package/src/steering.mjs

@@ -1,10 +1,15 @@
 /**
  * Steering scaffold seeding.
  *
- * Steering files (`steering/decisions.md`, `glossary.md`, `architecture.md`) are
- * a persistent, CONSUMER-OWNED memory layer. Agents read all three at session
- * start and append to them; the toolkit seeds blank scaffolds ONCE and then never
- * rewrites them.
+ * Steering files (`steering/decisions.md`, `glossary.md`, `architecture.md`,
+ * `delivery-log.md`) are a persistent, CONSUMER-OWNED memory layer. Agents read
+ * all four at session start and append to them; the toolkit seeds blank
+ * scaffolds ONCE and then never rewrites them.
+ *
+ * This list must stay in step with `.agents/steering/` in the content repo. It
+ * is inlined rather than derived, so adding a canonical steering file without
+ * adding it here leaves consumers un-seeded — which is how `delivery-log.md`
+ * shipped to the agents but not to the CLI.
  *
  * Invariants enforced here:
  *   - Seed-if-absent: a file is written only when it does not already exist. An
@@ -26,7 +31,7 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 
-/** The three steering scaffold files and their blank/minimal seed bodies. */
+/** The four steering scaffold files and their blank/minimal seed bodies. */
 export const STEERING_SCAFFOLDS = {
   'decisions.md':
     '# Decisions\n\n' +
@@ -40,6 +45,13 @@ export const STEERING_SCAFFOLDS = {
     '# Architecture\n\n' +
     '<!-- What goes here: load-bearing architecture notes, core patterns, and constraints ' +
     'agents should respect. Consumer-owned; keep it current. -->\n',
+  'delivery-log.md':
+    '# Delivery log\n\n' +
+    '<!-- What goes here: one dated, append-only retrospective entry per shipped feature, ' +
+    'appended by deliver-document at end-of-feature finalization. Records estimated vs actual ' +
+    'effort, pauses, recurring findings, and deferred Minor/Low findings so Define can calibrate ' +
+    'future estimates and cycle budgets against history. Consumer-owned; agents append, never ' +
+    'rewrite. -->\n',
 };
 
 class SteeringWriteError extends Error {

package/tests/steering-seed.test.mjs

@@ -5,8 +5,8 @@
  *
  * What these tests prove (one named test per criterion — §7):
  *
- *  B1. init writes three blank steering scaffold files when .claude/steering/ is absent.
- *  B2. update writes three blank steering scaffold files when .claude/steering/ is absent.
+ *  B1. init writes four blank steering scaffold files when .claude/steering/ is absent.
+ *  B2. update writes four blank steering scaffold files when .claude/steering/ is absent.
  *  B3. update leaves an already-edited steering/decisions.md byte-identical (seed-if-absent).
  *  B4. update leaves an already-edited steering/glossary.md byte-identical (seed-if-absent).
  *  B5. update leaves an already-edited steering/architecture.md byte-identical (seed-if-absent).
@@ -118,8 +118,8 @@ async function setupInitializedRepo(consumerDir, opts = {}) {
   writeFileSync(path.join(agentsDir, 'define.md'), fixtureContent, 'utf8');
 }
 
-/** The three steering file names the spec requires. */
-const STEERING_FILES = ['decisions.md', 'glossary.md', 'architecture.md'];
+/** The four steering file names the spec requires. */
+const STEERING_FILES = ['decisions.md', 'glossary.md', 'architecture.md', 'delivery-log.md'];
 
 // ---------------------------------------------------------------------------
 // B1 — init seeds steering when absent
@@ -136,8 +136,8 @@ describe('S1 steering seed — init', () => {
     rmSync(consumerDir, { recursive: true, force: true });
   });
 
-  it('B1: init creates .claude/steering/ with three scaffold files when absent', async () => {
-    // No steering/ pre-exists. init must create all three.
+  it('B1: init creates .claude/steering/ with four scaffold files when absent', async () => {
+    // No steering/ pre-exists. init must create all four.
     await runInit(consumerDir, {
       targets: ['claude'],
       fetcher: makeFixtureFetcher(),
@@ -175,7 +175,7 @@ describe('S1 steering seed — update', () => {
     rmSync(consumerDir, { recursive: true, force: true });
   });
 
-  it('B2: update creates .claude/steering/ with three scaffold files when absent', async () => {
+  it('B2: update creates .claude/steering/ with four scaffold files when absent', async () => {
     await setupInitializedRepo(consumerDir);
     // The lockfile resolvedVersion is 1.0.0, but we supply 1.2.0 as the latest
     // tag so update will run (not short-circuit as up-to-date).
@@ -529,7 +529,7 @@ describe('S1 steering seed — build.mjs emits steering to mirror without marker
     );
   });
 
-  it('B8b: build emits all three steering files to .claude/steering/', () => {
+  it('B8b: build emits all four steering files to .claude/steering/', () => {
     const agentsDir = path.join(tmpRoot, '.agents');
     const mirrorRoot = path.join(tmpRoot, 'mirror');
     mkdirSync(mirrorRoot, { recursive: true });
@@ -540,6 +540,7 @@ describe('S1 steering seed — build.mjs emits steering to mirror without marker
         'decisions.md': '# Decisions\n',
         'glossary.md': '# Glossary\n',
         'architecture.md': '# Architecture\n',
+        'delivery-log.md': '# Delivery log\n',
       },
       mirrorRoot,
     );
@@ -550,7 +551,7 @@ describe('S1 steering seed — build.mjs emits steering to mirror without marker
       const dest = path.join(mirrorRoot, '.claude', 'steering', file);
       assert.ok(
         existsSync(dest),
-        `build must emit .claude/steering/${file} (all three steering files)`,
+        `build must emit .claude/steering/${file} (all four steering files)`,
       );
     }
   });