vibepro 0.1.0-alpha.0

package/src/report-pr-body-prompt-template.md

@@ -0,0 +1,108 @@
+# VibePro PR-body narrative authoring (for the calling AI)
+
+You are receiving a JSON payload from `vibepro report fingerprint --kind pr-body`.
+Emit a JSON narrative back into `vibepro report write --kind pr-body --from-stdin`.
+
+You do NOT write the whole PR body. VibePro keeps the skeleton (headings, file
+lists, gate-dag, verification commands). You write the **prose that requires
+judgment** — synthesis a template cannot do.
+
+## Four slots
+
+1. **`summary`** — 1 slot. 2–5 sentences. "What does this PR change and why
+   does it matter?" Lead with the user-visible effect, not the file count.
+2. **`review_focus`** — 1–5 slots, one bullet each. The 1–3 things a reviewer
+   should examine that are not obvious from the diff. Avoid generic advice
+   ("check tests"). Be specific: which file's invariant is brittle, which clause
+   is contested, which drift item is load-bearing.
+3. **`risks_synthesis`** — 1 slot, 1–3 sentences. Synthesize across the
+   mechanical risk list. "What is the dominant failure mode this PR
+   introduces?" If there is no real risk beyond the enumeration, output:
+   `text: "特記事項なし"`.
+4. **`open_questions`** — 0–5 slots, one item each. Things you could not
+   determine from Story+Code+Test+drift. Reviewer must adjudicate. Skip
+   entirely if nothing is open.
+
+## Rules
+
+1. **Cite, do not paraphrase silently.** If you mention a file, list it in
+   `citations.files`. If you reference a finding (`VP-TASK-001`), drift item
+   (`DRIFT-ABC123`), or clause (`INV-001`), list it in the matching
+   citations array. Validator rejects citations to objects that do not exist.
+2. **Numerical claims must use `numerical_claims[]`.** If you write
+   "drift items が 3 件", you must also declare
+   `{"field":"drift_total_count","value":3}`. Validator compares to fingerprint.
+3. **Reuse TP ids when possible.** If `previous_narrative` contains a slot
+   whose text is semantically equivalent, copy its id. Otherwise use
+   `TP-NEW-<n>` — validator assigns stable ids.
+4. **No markdown headings.** Plain text per slot item. Bullets render as `- `
+   automatically.
+5. **No filler.** "This PR makes changes" / "Tests should pass" / "Please
+   review carefully" — delete. Each slot must give the reviewer something
+   they couldn't see by reading the diff.
+
+## Output format
+
+```jsonc
+{
+  "schema_version": "0.1.0",
+  "story_id": "<copy from fingerprint.story_id>",
+  "kind": "pr-body",
+  "generated_by": { "caller": "claude-code", "stage": "ai_synthesis" },
+  "narrative_slots": [
+    {
+      "id": "TP-NEW-1",
+      "slot": "summary",
+      "text": "premium ユーザーの cancelAtPeriodEnd 経路で userType=1 に降格していた回帰を src/lib/services/billing.ts で修正。INV-001 で宣言された不変条件と一致するように分岐を再整列した。",
+      "citations": {
+        "files": ["src/lib/services/billing.ts"],
+        "clause_ids": ["INV-001"]
+      },
+      "numerical_claims": []
+    },
+    {
+      "id": "TP-NEW-2",
+      "slot": "review_focus",
+      "text": "src/lib/services/billing.ts:142 の早期 return が、テスト対象外の status='premium_pending_cancel' 経路を引き起こす。テスト追加が無いまま invariant に依存しているので、reviewer は手で経路を辿るべき。",
+      "citations": {
+        "files": ["src/lib/services/billing.ts"]
+      }
+    },
+    {
+      "id": "TP-NEW-3",
+      "slot": "risks_synthesis",
+      "text": "drift items は spec_test 軸に偏っており、INV-001 を機械検証する test が無い。実装が変更されたら回帰検出が手作業になる。",
+      "citations": {
+        "clause_ids": ["INV-001"],
+        "drift_ids": ["DRIFT-AB12CD"]
+      },
+      "numerical_claims": [
+        { "field": "drift_high_count", "value": 1 }
+      ]
+    }
+  ]
+}
+```
+
+## What VibePro does with your output
+
+- JSON schema validation.
+- Per-slot: every `citations.files[]` must exist in repo. Every
+  `finding_ids[]` must appear in `evidence.findings[]`. Every `clause_ids[]`
+  must appear in inferred spec. Every `drift_ids[]` must appear in drift.json.
+  Every `numerical_claims[]` must match fingerprint values.
+- TP id stabilization via text similarity vs previous narrative.
+- Writes `.vibepro/report/<story-id>/pr-body/narrative.json`.
+- `vibepro pr prepare` splices your text into pr-body.md as 4 dedicated
+  sections at the top, attributed to TP ids.
+
+## Common mistakes
+
+- **Generic summary.** "This PR addresses the story." Useless. Tell the
+  reviewer the *causal mechanism* of the change.
+- **Inventing IDs.** If you write `DRIFT-XYZ123` but it isn't in
+  `fingerprint.drift.items[]`, you will be rejected. Always copy ids verbatim
+  from the fingerprint.
+- **Numerical drift.** Writing "5 drift items" when there are 3 → rejection.
+- **Filling open_questions with noise.** If you have no real open question,
+  return an empty array.

package/src/report-pr-body-schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://vibepro.local/schemas/report-pr-body.json",
+  "title": "VibePro PR-body narrative",
+  "description": "AI-authored narrative slots inserted into pr-body.md. VibePro keeps the section skeleton fixed; AI only writes the prose inside the declared slots, citing only files / findings / clauses / drift items that exist.",
+  "type": "object",
+  "required": ["schema_version", "story_id", "kind", "narrative_slots"],
+  "properties": {
+    "schema_version": { "type": "string", "const": "0.1.0" },
+    "story_id": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "const": "pr-body" },
+    "generated_at": { "type": "string" },
+    "generated_by": {
+      "type": "object",
+      "properties": {
+        "caller": { "type": "string" },
+        "stage": { "type": "string", "enum": ["ai_synthesis", "static_fallback"] }
+      }
+    },
+    "inputs_digest": { "type": "object" },
+    "previous_report_id": { "type": ["string", "null"] },
+    "narrative_slots": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/slot" }
+    }
+  },
+  "$defs": {
+    "slot": {
+      "type": "object",
+      "required": ["id", "slot", "text"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "Talking-point id. Use TP-<n>. New slots may use TP-NEW-<n>; validator assigns stable ids."
+        },
+        "slot": {
+          "type": "string",
+          "enum": ["summary", "review_focus", "risks_synthesis", "open_questions"],
+          "description": "Where in pr-body.md the text is inserted. One id per slot per run; multiple ids per slot allowed for review_focus and open_questions only."
+        },
+        "text": {
+          "type": "string",
+          "minLength": 4,
+          "description": "Plain prose / single bullet. No markdown headings. <= 280 chars per slot item recommended."
+        },
+        "citations": {
+          "type": "object",
+          "description": "What the text refers to. Validator rejects any reference to a non-existent file / finding / clause / drift item.",
+          "properties": {
+            "files": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "finding_ids": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "clause_ids": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "drift_ids": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "numerical_claims": {
+          "type": "array",
+          "description": "Claims about counts that must match fingerprint values. Validator rejects on contradiction.",
+          "items": {
+            "type": "object",
+            "required": ["field", "value"],
+            "properties": {
+              "field": {
+                "type": "string",
+                "enum": [
+                  "changed_files_count",
+                  "drift_high_count",
+                  "drift_total_count",
+                  "requirement_invariant_count",
+                  "requirement_contradiction_count",
+                  "acceptance_criteria_count"
+                ]
+              },
+              "value": { "type": "integer", "minimum": 0 }
+            }
+          }
+        },
+        "first_seen_at": { "type": "string" },
+        "last_revised_at": { "type": "string" }
+      }
+    }
+  }
+}

package/src/report-store.js

@@ -0,0 +1,135 @@
+import { mkdir, readFile, readdir, writeFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { similarity } from './spec-store.js';
+import { WORKSPACE_DIR } from './workspace.js';
+
+export const REPORT_SCHEMA_VERSION = '0.1.0';
+export const REPORT_KINDS = new Set(['pr-body']);
+const HISTORY_KEEP = 10;
+const TP_SIMILARITY_THRESHOLD = 0.7;
+
+export function getReportDir(repoRoot, storyId, kind) {
+  if (!storyId) throw new Error('storyId is required');
+  if (!REPORT_KINDS.has(kind)) throw new Error(`Unsupported report kind: ${kind}`);
+  return path.join(path.resolve(repoRoot), WORKSPACE_DIR, 'report', storyId, kind);
+}
+
+export function getNarrativeFile(repoRoot, storyId, kind) {
+  return path.join(getReportDir(repoRoot, storyId, kind), 'narrative.json');
+}
+
+export async function ensureReportDir(repoRoot, storyId, kind) {
+  const dir = getReportDir(repoRoot, storyId, kind);
+  await mkdir(path.join(dir, 'narrative.history'), { recursive: true });
+  return dir;
+}
+
+export async function readNarrative(repoRoot, storyId, kind) {
+  if (!storyId) return null;
+  try {
+    return JSON.parse(await readFile(getNarrativeFile(repoRoot, storyId, kind), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export async function writeNarrative(repoRoot, storyId, kind, narrative) {
+  await ensureReportDir(repoRoot, storyId, kind);
+  const target = getNarrativeFile(repoRoot, storyId, kind);
+  await writeFile(target, `${JSON.stringify(narrative, null, 2)}\n`);
+
+  const historyDir = path.join(getReportDir(repoRoot, storyId, kind), 'narrative.history');
+  const stamp = (narrative.generated_at ?? new Date().toISOString()).replace(/[:.]/g, '-');
+  const historyPath = path.join(historyDir, `narrative-${stamp}.json`);
+  await writeFile(historyPath, `${JSON.stringify(narrative, null, 2)}\n`);
+  await pruneHistory(historyDir);
+  return target;
+}
+
+async function pruneHistory(historyDir) {
+  let entries;
+  try {
+    entries = await readdir(historyDir);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  const sorted = entries
+    .filter((name) => name.startsWith('narrative-') && name.endsWith('.json'))
+    .sort()
+    .reverse();
+  const stale = sorted.slice(HISTORY_KEEP);
+  if (stale.length === 0) return;
+  await Promise.all(stale.map((name) => rm(path.join(historyDir, name), { force: true })));
+}
+
+export function stabilizeTalkingPointIds(narrative, previous) {
+  if (!narrative || !Array.isArray(narrative.narrative_slots)) {
+    return { ...narrative, narrative_slots: [] };
+  }
+  if (!previous || !Array.isArray(previous.narrative_slots)) {
+    return assignFreshTpIds(narrative);
+  }
+
+  const usedPrevious = new Set();
+  const usedNew = new Set();
+  const issuedAt = new Date().toISOString();
+
+  const slots = narrative.narrative_slots.map((slot) => {
+    let best = null;
+    for (const prev of previous.narrative_slots) {
+      if (usedPrevious.has(prev.id)) continue;
+      if (prev.slot !== slot.slot) continue;
+      const score = similarity(slot.text, prev.text);
+      if (!best || score > best.score) best = { slot: prev, score };
+    }
+    if (best && best.score >= TP_SIMILARITY_THRESHOLD) {
+      usedPrevious.add(best.slot.id);
+      usedNew.add(best.slot.id);
+      return {
+        ...slot,
+        id: best.slot.id,
+        first_seen_at: best.slot.first_seen_at ?? issuedAt,
+        last_revised_at: issuedAt
+      };
+    }
+    return {
+      ...slot,
+      id: nextFreshTpId(usedNew, previous, issuedAt),
+      first_seen_at: issuedAt,
+      last_revised_at: issuedAt
+    };
+  });
+
+  return { ...narrative, narrative_slots: slots };
+}
+
+function assignFreshTpIds(narrative) {
+  const usedNew = new Set();
+  const issuedAt = new Date().toISOString();
+  const slots = narrative.narrative_slots.map((slot) => ({
+    ...slot,
+    id: nextFreshTpId(usedNew, null, issuedAt),
+    first_seen_at: slot.first_seen_at ?? issuedAt,
+    last_revised_at: issuedAt
+  }));
+  return { ...narrative, narrative_slots: slots };
+}
+
+function nextFreshTpId(usedNew, previous, issuedAt) {
+  const reserved = new Set(usedNew);
+  if (previous && Array.isArray(previous.narrative_slots)) {
+    for (const slot of previous.narrative_slots) reserved.add(slot.id);
+  }
+  let n = 1;
+  while (reserved.has(`TP-${pad3(n)}`)) n += 1;
+  const id = `TP-${pad3(n)}`;
+  usedNew.add(id);
+  return id;
+}
+
+function pad3(n) {
+  return String(n).padStart(3, '0');
+}

package/src/report-validator.js

@@ -0,0 +1,192 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { readDrift, readInferredSpec } from './spec-store.js';
+
+const SLOT_KINDS = new Set(['summary', 'review_focus', 'risks_synthesis', 'open_questions']);
+const SLOT_LIMITS = {
+  summary: { min: 1, max: 1 },
+  review_focus: { min: 0, max: 5 },
+  risks_synthesis: { min: 1, max: 1 },
+  open_questions: { min: 0, max: 5 }
+};
+const NUMERICAL_FIELDS = new Set([
+  'changed_files_count',
+  'drift_high_count',
+  'drift_total_count',
+  'requirement_invariant_count',
+  'requirement_contradiction_count',
+  'acceptance_criteria_count'
+]);
+
+export async function validateReportNarrative(repoRoot, narrative, fingerprint, options = {}) {
+  const errors = [];
+  const warnings = [];
+
+  if (!narrative || typeof narrative !== 'object') {
+    return { ok: false, errors: [{ code: 'invalid_root', message: 'narrative must be a JSON object' }], warnings };
+  }
+  if (narrative.schema_version !== '0.1.0') {
+    errors.push({ code: 'schema_version', message: `expected schema_version "0.1.0", got "${narrative.schema_version}"` });
+  }
+  if (narrative.kind !== 'pr-body') {
+    errors.push({ code: 'kind', message: `narrative.kind must be "pr-body"` });
+  }
+  if (!narrative.story_id || typeof narrative.story_id !== 'string') {
+    errors.push({ code: 'story_id', message: 'story_id is required' });
+  }
+  if (options.expectedStoryId && narrative.story_id !== options.expectedStoryId) {
+    errors.push({
+      code: 'story_id_mismatch',
+      message: `narrative.story_id "${narrative.story_id}" does not match expected "${options.expectedStoryId}"`
+    });
+  }
+  if (!Array.isArray(narrative.narrative_slots)) {
+    errors.push({ code: 'slots_missing', message: 'narrative_slots must be an array' });
+    return { ok: false, errors, warnings, narrative };
+  }
+
+  const slotCounts = countSlots(narrative.narrative_slots);
+  for (const [slot, { min, max }] of Object.entries(SLOT_LIMITS)) {
+    const count = slotCounts.get(slot) ?? 0;
+    if (count < min) {
+      errors.push({ code: 'slot_min', message: `slot "${slot}" requires at least ${min} entry, got ${count}` });
+    }
+    if (count > max) {
+      errors.push({ code: 'slot_max', message: `slot "${slot}" allows at most ${max} entries, got ${count}` });
+    }
+  }
+
+  const driftItems = fingerprint?.drift?.items ?? [];
+  const driftIds = new Set(driftItems.map((item) => item.id));
+  const findingIds = new Set((fingerprint?.findings ?? []).map((entry) => entry.id));
+  const clauseIds = new Set((fingerprint?.inferred_spec?.clauses ?? []).map((entry) => entry.id));
+  const numericalTruth = fingerprint?.numerical_truth ?? {};
+
+  for (let index = 0; index < narrative.narrative_slots.length; index += 1) {
+    const slot = narrative.narrative_slots[index];
+    const slotErrors = await validateSlot(repoRoot, slot, index, {
+      driftIds, findingIds, clauseIds, numericalTruth
+    });
+    errors.push(...slotErrors);
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    warnings,
+    narrative
+  };
+}
+
+function countSlots(slots) {
+  const counts = new Map();
+  for (const slot of slots) {
+    if (!slot || typeof slot !== 'object') continue;
+    counts.set(slot.slot, (counts.get(slot.slot) ?? 0) + 1);
+  }
+  return counts;
+}
+
+async function validateSlot(repoRoot, slot, index, ctx) {
+  const errors = [];
+  const locator = slot?.id ? `narrative_slots[${index}] (${slot.id})` : `narrative_slots[${index}]`;
+  if (!slot || typeof slot !== 'object') {
+    errors.push({ code: 'slot_shape', message: `${locator} must be an object` });
+    return errors;
+  }
+  if (!slot.id || typeof slot.id !== 'string') {
+    errors.push({ code: 'slot_id', message: `${locator}.id required` });
+  }
+  if (!SLOT_KINDS.has(slot.slot)) {
+    errors.push({
+      code: 'slot_kind',
+      message: `${locator}.slot must be one of ${[...SLOT_KINDS].join('|')}`
+    });
+  }
+  if (typeof slot.text !== 'string' || slot.text.trim().length < 4) {
+    errors.push({ code: 'slot_text', message: `${locator}.text must be a non-empty string` });
+  }
+
+  const citations = slot.citations ?? {};
+  for (const file of citations.files ?? []) {
+    const fileResult = await fileExists(repoRoot, file);
+    if (!fileResult) {
+      errors.push({
+        code: 'citation_file_missing',
+        message: `${locator}.citations.files: "${file}" not found in repository`
+      });
+    }
+  }
+  for (const id of citations.finding_ids ?? []) {
+    if (!ctx.findingIds.has(id)) {
+      errors.push({
+        code: 'citation_finding_missing',
+        message: `${locator}.citations.finding_ids: "${id}" not found in evidence.findings`
+      });
+    }
+  }
+  for (const id of citations.clause_ids ?? []) {
+    if (!ctx.clauseIds.has(id)) {
+      errors.push({
+        code: 'citation_clause_missing',
+        message: `${locator}.citations.clause_ids: "${id}" not found in inferred spec clauses`
+      });
+    }
+  }
+  for (const id of citations.drift_ids ?? []) {
+    if (!ctx.driftIds.has(id)) {
+      errors.push({
+        code: 'citation_drift_missing',
+        message: `${locator}.citations.drift_ids: "${id}" not found in drift.items`
+      });
+    }
+  }
+
+  for (const claim of slot.numerical_claims ?? []) {
+    if (!claim || !NUMERICAL_FIELDS.has(claim.field)) {
+      errors.push({
+        code: 'numerical_field',
+        message: `${locator}.numerical_claims: field must be one of ${[...NUMERICAL_FIELDS].join('|')}`
+      });
+      continue;
+    }
+    const truth = ctx.numericalTruth[claim.field];
+    if (truth === undefined) {
+      errors.push({
+        code: 'numerical_truth_missing',
+        message: `${locator}.numerical_claims: fingerprint lacks "${claim.field}" — cannot verify`
+      });
+      continue;
+    }
+    if (typeof claim.value !== 'number' || claim.value !== truth) {
+      errors.push({
+        code: 'numerical_contradiction',
+        message: `${locator}.numerical_claims: ${claim.field}=${claim.value} contradicts fingerprint=${truth}`
+      });
+    }
+  }
+
+  return errors;
+}
+
+async function fileExists(repoRoot, relativeFile) {
+  try {
+    const stats = await stat(path.join(repoRoot, relativeFile));
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Cross-check that fingerprint slot existence matches expectation when AI is rerun
+// without changes. Used in tests / drift detection later.
+export async function reconcileWithRunArtifacts(repoRoot, narrative, storyId) {
+  const drift = await readDrift(repoRoot, storyId);
+  const spec = await readInferredSpec(repoRoot, storyId);
+  return {
+    drift_present: Boolean(drift),
+    spec_present: Boolean(spec),
+    narrative_slots: narrative?.narrative_slots?.length ?? 0
+  };
+}