@dalzoubi/dev-agents-sync 1.0.12 → 1.0.13

package/package.json

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

package/tests/define-estimate-flow.test.mjs

@@ -0,0 +1,197 @@
+/**
+ * tests/define-estimate-flow.test.mjs
+ *
+ * Slice: rewrite-define-estimate-flow
+ *
+ * Asserts that prompts/agents/define.md has been updated to replace the
+ * per-slice estimate Q&A flow (asking the user one question per slice) with a
+ * model-generated estimate flow that:
+ *   - generates estimates from slice scope and success criteria
+ *   - presents them with one-line rationales inline
+ *   - accepts per-line user overrides validated against ^\d+(\.5)?$
+ *   - refuses to finalize on low confidence and asks one targeted clarification
+ *
+ * These tests FAIL before the implementation change and PASS after.
+ *
+ * Path under test: prompts/agents/define.md (relative to repo root)
+ * Test runner: node --test (Node built-in, >= 20)
+ */
+
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Resolve the file under test relative to this file's location.
+// This repo layout: packages/dev-agents-sync/tests/ -> repo root is 3 levels up.
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+const DEFINE_MD = path.join(REPO_ROOT, 'prompts', 'agents', 'define.md');
+
+let content;
+
+before(() => {
+  content = readFileSync(DEFINE_MD, 'utf8');
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 1 — the OLD per-slice Q&A pattern must be gone
+// ---------------------------------------------------------------------------
+
+describe('define.md — per-slice estimate Q&A removed', () => {
+  it('does NOT instruct the agent to ask the user for estimates one at a time', () => {
+    // The old phrasing asked "one question per slice — one at a time" for estimates.
+    // After the rewrite, that pattern must not appear.
+    const oldPattern = /ask one question per slice[^.]*one at a time/i;
+    assert.ok(
+      !oldPattern.test(content),
+      'define.md must not contain "ask one question per slice … one at a time" for estimates',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 2 — model GENERATES estimates from scope and success criteria
+// ---------------------------------------------------------------------------
+
+describe('define.md — model-generated estimates', () => {
+  it('instructs the agent to generate estimates from slice scope and success criteria', () => {
+    // We expect explicit instruction that estimates are derived from scope/success criteria,
+    // not solicited from the user via Q&A.
+    const generatesFromScope =
+      /generat\w*\s+estimate/i.test(content) ||
+      /estimate\w*\s+(?:from|based on|using)\s+(?:the\s+)?(?:slice\s+)?scope/i.test(content) ||
+      /estimate\w*\s+(?:from|based on|using)\s+(?:the\s+)?success\s+criteri/i.test(content) ||
+      /(?:scope|success\s+criteri)\w*.*\bto\s+(?:derive|compute|produce|generate)\s+estimate/i.test(content);
+
+    assert.ok(
+      generatesFromScope,
+      'define.md must instruct the agent to generate estimates from slice scope and/or success criteria',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 3 — exact calibration anchor sentence
+// ---------------------------------------------------------------------------
+
+describe('define.md — calibration anchor', () => {
+  it('contains the exact calibration anchor sentence', () => {
+    const anchor = '1 day = one focused engineer-day of implementation work, excluding review and deploy';
+    assert.ok(
+      content.includes(anchor),
+      `define.md must contain the exact calibration anchor: "${anchor}"`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 4 — estimates presented with one-line rationales inline
+// ---------------------------------------------------------------------------
+
+describe('define.md — inline rationales', () => {
+  it('instructs the agent to present estimates with one-line rationales inline', () => {
+    // Must contain explicit instruction about rationale alongside each estimate.
+    const rationaleInstruction =
+      /one[- ]line\s+rationale/i.test(content) ||
+      /rationale\s+(?:for\s+)?(?:each|every|per)[- ](?:slice\s+)?estimate/i.test(content) ||
+      /(?:present|show|display|include)\s+estimates?\s+with\s+(?:a\s+)?(?:one[- ]line\s+)?rationale/i.test(content);
+
+    assert.ok(
+      rationaleInstruction,
+      'define.md must instruct the agent to present estimates with one-line rationales inline',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 5 — per-line overrides validated against ^\d+(\.5)?$
+// ---------------------------------------------------------------------------
+
+describe('define.md — per-line overrides', () => {
+  it('instructs the agent to accept per-line overrides', () => {
+    const overrideInstruction =
+      /per[- ]line\s+override/i.test(content) ||
+      /override\w*\s+(?:per|each|any)\s+(?:line|slice|estimate)/i.test(content) ||
+      /(?:accept|allow)\s+(?:per[- ]line|inline)\s+override/i.test(content);
+
+    assert.ok(
+      overrideInstruction,
+      'define.md must instruct the agent to accept per-line overrides on the generated estimates',
+    );
+  });
+
+  it('still validates overrides against ^\\d+(\\.5)?$', () => {
+    // The regex must remain in the file — it was there before and must survive the rewrite.
+    assert.ok(
+      content.includes('^\\d+(\\.5)?$'),
+      'define.md must still validate estimates against ^\\d+(\\.5)?$',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 6 — refuse to finalize on low confidence; ask one targeted question
+// ---------------------------------------------------------------------------
+
+describe('define.md — low-confidence refusal', () => {
+  it('instructs the agent to refuse to finalize on low confidence', () => {
+    const lowConfidenceRefusal =
+      /low\s+confidence/i.test(content) ||
+      /(?:refuse|do\s+not|don'?t)\s+(?:finalize|proceed|write)\s+(?:the\s+spec\s+)?(?:on|when|if)\s+(?:low|insufficient)\s+confidence/i.test(content) ||
+      /(?:insufficient|low)\s+(?:confidence|information).*(?:refuse|do\s+not|don'?t)\s+finalize/i.test(content);
+
+    assert.ok(
+      lowConfidenceRefusal,
+      'define.md must instruct the agent to refuse to finalize when confidence is low',
+    );
+  });
+
+  it('instructs the agent to ask one targeted clarification question on low confidence', () => {
+    const oneTargetedQuestion =
+      /one\s+targeted\s+clarification/i.test(content) ||
+      /ask\s+(?:a\s+|one\s+)?(?:single\s+)?targeted\s+(?:clarification\s+)?question/i.test(content) ||
+      /one\s+(?:clarification|follow[- ]up)\s+question/i.test(content);
+
+    assert.ok(
+      oneTargetedQuestion,
+      'define.md must instruct the agent to ask exactly one targeted clarification question when confidence is low',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 7 — half-day regex ^\d+(\.5)?$ still present (regression guard)
+// ---------------------------------------------------------------------------
+
+describe('define.md — half-day regex preserved', () => {
+  it('still contains the half-day granularity regex ^\\d+(\\.5)?$', () => {
+    assert.ok(
+      content.includes('^\\d+(\\.5)?$'),
+      'define.md must still contain the half-day regex ^\\d+(\\.5)?$',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 8 — "refuse to write without all estimates" rule still present
+// ---------------------------------------------------------------------------
+
+describe('define.md — refuse to finalize without all estimates preserved', () => {
+  it('still contains the rule to refuse writing the spec when any slice lacks an estimate', () => {
+    // The existing rule says something equivalent to "never write the spec while any slice is missing its estimate"
+    const refuseRule =
+      /(?:refuse|never\s+write|do\s+not\s+write)\s+(?:the\s+)?spec\s+(?:while|if|when)\s+any\s+slice\s+(?:is\s+)?(?:missing|lacks?)\s+(?:its\s+)?estimate/i.test(content) ||
+      /(?:missing|lacks?)\s+(?:its\s+)?estimate.*(?:never\s+write|refuse)/i.test(content) ||
+      /never\s+write\s+the\s+spec\s+while\s+any\s+slice\s+is\s+missing\s+its\s+estimate/i.test(content);
+
+    assert.ok(
+      refuseRule,
+      'define.md must still instruct the agent to refuse to write the spec when any slice is missing its estimate',
+    );
+  });
+});

package/tests/supervise-estimate-provenance.test.mjs

@@ -0,0 +1,98 @@
+/**
+ * tests/supervise-estimate-provenance.test.mjs
+ *
+ * Slice: note-supervise-estimate-source
+ *
+ * Asserts that prompts/agents/supervise.md contains a provenance note
+ * clarifying that per-slice estimates are model-generated by the Define agent
+ * (with optional user overrides) and are read at runtime as-is.
+ *
+ * These tests FAIL before the implementation change and PASS after.
+ *
+ * Path under test: prompts/agents/supervise.md (relative to repo root)
+ * Test runner: node --test (Node built-in, >= 20)
+ */
+
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Resolve the file under test relative to this file's location.
+// Repo layout: packages/dev-agents-sync/tests/ -> repo root is 3 levels up.
+// ---------------------------------------------------------------------------
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+const SUPERVISE_MD = path.join(REPO_ROOT, 'prompts', 'agents', 'supervise.md');
+
+let content;
+
+before(() => {
+  content = readFileSync(SUPERVISE_MD, 'utf8');
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 1 — estimates are acknowledged as model-generated
+// ---------------------------------------------------------------------------
+
+describe('supervise.md — estimate provenance: model-generated', () => {
+  it('contains language acknowledging that per-slice estimates are model-generated', () => {
+    // The note must use "model-generated" (hyphenated or spaced) in the context
+    // of estimates. We check for the phrase itself anywhere in the file because
+    // the spec parsing section is the only place estimates are discussed.
+    const modelGeneratedPattern = /model[- ]generated/i;
+
+    assert.ok(
+      modelGeneratedPattern.test(content),
+      'supervise.md must contain "model-generated" to acknowledge that per-slice estimates are produced by the Define agent, not user-supplied',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 2 — the Define agent is named as the source
+// ---------------------------------------------------------------------------
+
+describe('supervise.md — estimate provenance: Define agent as source', () => {
+  it('names the Define agent as the source of per-slice estimates', () => {
+    // We require the explicit phrase "Define agent" (the agent name) to appear
+    // in proximity to "estimate" or "model-generated", so that the vague
+    // co-occurrence of "Define" (as the /define in-place recovery command) and
+    // "estimate" in the parsing section does not produce a false positive.
+    // The patterns below require "Define agent" as a two-word phrase, which
+    // only the provenance note will introduce.
+    const defineAgentNearEstimate =
+      /Define\s+agent[^]{0,400}estimate/i.test(content) ||
+      /estimate[^]{0,400}Define\s+agent/i.test(content) ||
+      /Define\s+agent[^]{0,400}model[- ]generated/i.test(content) ||
+      /model[- ]generated[^]{0,400}Define\s+agent/i.test(content);
+
+    assert.ok(
+      defineAgentNearEstimate,
+      'supervise.md must name the Define agent as the source of per-slice estimates (requires "Define agent" near "estimate" or "model-generated")',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Criterion 3 — optional user overrides are acknowledged
+// ---------------------------------------------------------------------------
+
+describe('supervise.md — estimate provenance: optional user overrides', () => {
+  it('acknowledges that users may override model-generated estimates', () => {
+    // The note must mention that the user can (optionally) override the
+    // model-generated estimate. "optional" + "override" is the minimal signal.
+    const optionalOverridePattern =
+      /optional\w*\s+(?:user\s+)?override/i.test(content) ||
+      /(?:user\s+)?override\w*\s+(?:are\s+)?optional/i.test(content) ||
+      /with\s+optional\s+(?:user\s+)?override/i.test(content);
+
+    assert.ok(
+      optionalOverridePattern,
+      'supervise.md must acknowledge that user overrides of model-generated estimates are optional',
+    );
+  });
+});