projectstore-claude 0.30.9 → 0.30.10

package/node_modules/projectstore/scaffold/guides/epic.md

@@ -0,0 +1,36 @@
+---
+guide_for: epic
+guide_version: 1
+default_review: true
+---
+
+## Lens
+
+The product owner who must say, later, whether this epic worked. State the outcome in terms someone can check, then the stories that deliver it.
+
+## Must
+
+- Goal is measurable — success can be verified, not just described.
+- Context explains why this epic exists and which downstream pieces depend on it.
+- Stories table has at least 2 entries; first story description is concrete enough to start.
+- Expected Results contains testable outcomes, not aspirations.
+- Dependencies list external blockers (people, systems, decisions), not just sibling stories.
+- Open Questions are real unknowns, not rhetorical filler.
+- Priority assigned (p0 / p1 / p2), not left as default if epic is non-trivial.
+
+## Common mistakes
+
+- A Goal that describes activity (build, improve, refactor), not a result that can be verified.
+- Expected Results that are aspirations. Each one should be a check someone can run or read.
+- A Stories table that is a to-do dump: a vague first story, no order.
+- Dependencies that name only sibling stories. The blockers are people, systems and decisions outside the epic.
+- `code_refs` left empty after the first story lands, or the priority left at the default.
+
+## Do not write
+
+- Implementation detail (files, functions): it belongs in the spec and the plans.
+- A story's acceptance criteria or an ADR's text copied into the epic: link them.
+
+## Length
+
+Goal in two to four sentences; the whole epic 40 to 100 lines plus the stories table.

package/node_modules/projectstore/scaffold/guides/meeting.md

@@ -0,0 +1,11 @@
+---
+guide_for: meeting
+guide_version: 1
+default_review: false
+---
+
+## Must
+
+- Attendees listed.
+- Decisions section captures what was actually decided (not just discussed).
+- Action items have an owner.

package/node_modules/projectstore/scaffold/guides/research.md

@@ -0,0 +1,16 @@
+---
+guide_for: research
+guide_version: 1
+default_review: true
+---
+
+## Must
+
+- Question is sharp — answerable by yes/no/comparison, not 'tell me about X'.
+- TL;DR is a single paragraph that gives the conclusion before the body.
+- Method describes how findings were gathered (docs read, benchmarks run, experts asked) — not just 'I researched'.
+- Comparison table has populated Pros AND Cons cells; empty cells flagged.
+- Conclusion explicitly ties back to the original Question. Recommendation is actionable.
+- References are linkable (URL / file path), not 'see [some doc]'.
+- No unstated benchmarks ('it's faster' without numbers).
+- Findings are evidence-based, not opinion. Where opinion appears, it's labelled.

package/node_modules/projectstore/scaffold/guides/runbook.md

@@ -0,0 +1,12 @@
+---
+guide_for: runbook
+guide_version: 1
+default_review: false
+---
+
+## Must
+
+- Purpose states WHEN to run this runbook (trigger conditions).
+- Prerequisites are listable checks, not prose.
+- Verification step exists and is testable.
+- Rollback step exists for any irreversible action.

package/node_modules/projectstore/scaffold/guides/spec.md

@@ -0,0 +1,39 @@
+---
+guide_for: spec
+guide_version: 1
+default_review: true
+---
+
+## Lens
+
+The systems analyst who writes the contract a test can be written from before the code exists. Each contract states an observable outcome and the scenario that would prove it.
+
+## Must
+
+- How we solve references at least one ADR by id; the references resolve.
+- Behavioral contracts are numbered and individually testable — each states an observable outcome, not an implementation step.
+- Acceptance items are checkboxes; acceptance is explicitly ADDITIVE to the covered stories' own criteria, not a replacement.
+- Acceptance items that belong to specific stories carry a '— stories: <id>' attribution; items meant for all covered stories are unattributed on purpose.
+- frontmatter stories: uses <epic-id>/<story-id> path form, inline flow list.
+- Mandatory sections present (How we solve / Behavioral contracts / Acceptance); Modules-on-disk and Testing may be omitted only for research spikes.
+- For a spike spec: contracts read as questions-to-answer plus exit criteria.
+- No TODOs, no '...', no empty bullets in the final body.
+
+## Common mistakes
+
+- A contract that describes an implementation step (calls X, stores Y) instead of what a caller observes.
+- Scenarios that show only the happy path. Add the boundary, the invalid input and the failed dependency a production run will hit.
+- Acceptance that restates the covered stories' own criteria. It is additive: each item adds something only the spec promises.
+- Numbers, tables and contract references copied from memory. Open the ADR and the sibling spec and copy from them.
+- Frontmatter lists in block form (the parser reads inline flow), or an `adr:` id that does not resolve.
+- A citation token for a real key written in prose or an example. Use the reserved key, as in `[example#1]`.
+
+## Do not write
+
+- The argument for the decision, or its alternatives: link the ADR.
+- A plan or a task list: that is the story's Implementation Plan.
+- Files the spec does not govern, or code beyond a three-line illustration.
+
+## Length
+
+A contract is one paragraph and at most six scenario items. A spec past twelve contracts or 400 lines covers two subsystems: split it.

package/node_modules/projectstore/scaffold/guides/story.md

@@ -0,0 +1,34 @@
+---
+guide_for: story
+guide_version: 1
+default_review: false
+---
+
+## Lens
+
+The engineer who picks this up in a fresh session, with none of this conversation. Say who benefits and what changes, in steps small enough to finish one at a time, and criteria a test can be written from.
+
+## Must
+
+- Description states the user/actor and the value of the change.
+- Decomposition checklist has items granular enough to finish in a session each.
+- Acceptance Criteria are testable (someone could write tests from these).
+- Technical Notes flag any non-obvious risks or constraints.
+
+## Common mistakes
+
+- Acceptance criteria that repeat decomposition tasks (implement X) instead of an outcome someone can observe.
+- A decomposition item the size of the story (Tests, Docs) with no named cases.
+- Contract numbers and tables quoted from memory. Open the covering spec or ADR and copy them.
+- A non-trivial "how" with neither a `specs:` entry nor a `no_spec` reason.
+- Technical Notes left empty while the risks are known. Put the trap there, not only in the chat.
+
+## Do not write
+
+- The Implementation Plan or the Final Summary at creation: the gates write them.
+- A spec's contracts restated in full: cite them by number.
+- A criterion that cannot fail.
+
+## Length
+
+Description one to three short paragraphs; five to nine decomposition items; four to ten criteria; the plan a thin route of at most 40 lines.

package/node_modules/projectstore/scripts/cli.mjs

@@ -68,7 +68,8 @@ import {
   SUBCOMMANDS as BAND_SUBCOMMANDS,
 } from "./band.mjs";
 import { dispatch, envelope, usageFail, ownEnv, nearest, notBoundText, PACKAGE_ROOT } from "./verbs.mjs";
-import { READ_HANDLERS } from "./read-verbs.mjs";
+import { READ_HANDLERS, guideVault } from "./read-verbs.mjs";
+import { checkGuideName, planEject, applyEject } from "./guides.mjs";
 
 // What this module exported before the table moved, from where it lives now.
 export {
@@ -640,8 +641,61 @@ async function runInstallVerb({ row, values, project, env, cwd, stdin, stdout, a
 // Every verb's handler, keyed by verb: the read half from read-verbs.mjs,
 // the rest here. Exported so a test can wrap one (setup's sandboxed home) in
 // a table of its own.
+// guide — the read is the read runner's; `guide eject <kind>` is the one
+// write (the authoring-guides ADR, decision 5): it copies the package guide
+// into <vault>/guides/ with based_on, create-only, and confirms as scaffold
+// does — a terminal asks, --write without one is the confirmation.
+async function runGuideVerb(ctx) {
+  const { row, values, positionals, cfg, project, env, stdin, stdout, stderr, ask } = ctx;
+  if (positionals[0] !== "eject") return READ_HANDLERS.guide(ctx);
+  const usage = (m) => usageFail(Object.assign(new Error(m), { code: "USAGE" }), { verb: row.verb, ...ctx });
+  const name = positionals[1];
+  if (!name) return usage("guide eject takes a kind, such as `guide eject spec`");
+  if (values.section || values.source) return usage("--section and --source belong to the read, not to eject");
+  try {
+    checkGuideName(name);
+  } catch (e) {
+    return usageFail(e, { verb: row.verb, ...ctx });
+  }
+  const emit = (ok, result, text, code) => {
+    if (values.json) stdout.write(JSON.stringify(envelope(row.verb, project, ok, result), null, 2) + "\n");
+    else (ok ? stdout : stderr).write(text);
+    return code;
+  };
+  const plan = planEject(name, { vault: guideVault(cfg, project), root: PACKAGE_ROOT });
+  const result = (written) => ({ name, target: plan.target, based_on: plan.based_on ?? null, written });
+  if (!plan.ok) return emit(false, { ...result(false), error: plan.refusal }, `guide eject: ${plan.refusal}\n`, 1);
+  const preview = [
+    `guide eject ${name} — creates ${plan.target} (based_on: ${plan.based_on}):`,
+    "",
+    plan.content.replace(/\n*$/, ""),
+    "",
+  ].join("\n");
+  if (!values.write)
+    return emit(
+      true,
+      result(false),
+      `${preview}\nNothing written. To create it, ${fromTerminalIn(project)}:\n${packageCommand([], "guide", { args: `eject ${name} --write` })}\n`,
+      0,
+    );
+  const interactive =
+    !values.json &&
+    (ask ? true : (await import("./install-harness.mjs")).isInteractive({ stdin, stdout, env, json: false }));
+  if (interactive) {
+    stdout.write(preview + "\n");
+    if (!(await term.askApply(1, { stdin, stdout, ask, caps: term.caps(stdout, env) }))) {
+      stdout.write("Nothing written.\n");
+      return 1;
+    }
+  }
+  const done = applyEject(plan);
+  if (!done.written) return emit(false, { ...result(false), error: done.refusal }, `guide eject: ${done.refusal}\n`, 1);
+  return emit(true, result(true), `Created ${plan.target}.\n`, 0);
+}
+
 export const HANDLERS = Object.freeze({
   ...READ_HANDLERS,
+  guide: runGuideVerb,
   setup: runSetupVerb,
   configure: runConfigureVerb,
   reconcile: runReconcile,

package/node_modules/projectstore/scripts/configure-menu.mjs

@@ -104,7 +104,8 @@ const KEY = Object.freeze({
   lifecycle_gates: {
     text: () => "Whether doctor checks a story's plan and close sections.",
     values: {
-      on: () => "doctor checks a story's plan when it starts, and its final summary and evidence when it closes.",
+      on: () =>
+        "doctor checks a story's plan when it starts, and its final summary and evidence when it closes. Stories closed after now are checked.",
       off: () => "The plan and close sections are still written; doctor does not check them.",
     },
   },

package/node_modules/projectstore/scripts/configure.mjs

@@ -53,6 +53,7 @@ const CLEAR = "-";
 const LANGUAGE_NOTE =
   "new artifacts, the derived views on their next reconcile, the plan and close sections of stories still in flight, the session header and the status line take the new language; existing artifacts and the vault's READMEs are untouched";
 const STAMP_NOTE = "stories closed before now are exempt from the spec and lifecycle gates";
+const GATES_NOTE = "stories closed after now are checked by the lifecycle gates";
 
 const parseBool = (v) => {
   const s = String(v).trim().toLowerCase();
@@ -466,7 +467,11 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
     const patch = Object.fromEntries(policy.map((c) => [c.key, c.value]));
     const next = nextVaultConfig(strict.cfg, patch, new Date().toISOString());
     const inEffect = (k) => strict.cfg[k] ?? (k === "spec_policy" ? "optional" : undefined);
-    const changed = policy.filter((c) => inEffect(c.key) !== c.value);
+    // `lifecycle_gates=on` on a vault already on but with no gates_since is a
+    // change: it stamps the date the gates count from (the configure spec,
+    // contract 7 as amended 2026-11-08).
+    const stampsGates = (c) => c.key === "lifecycle_gates" && c.value === "on" && !strict.cfg.gates_since;
+    const changed = policy.filter((c) => inEffect(c.key) !== c.value || stampsGates(c));
     for (const c of changed)
       items.push({
         key: c.key,
@@ -474,7 +479,12 @@ export function planChanges(f, changes, { env = process.env, home = homedir(), r
         before: shown(strict.cfg[c.key] ?? (c.key === "spec_policy" ? "optional" : "not set")),
         after: shown(c.value),
         team: true,
-        note: c.key === "spec_policy" && next.spec_policy_since !== strict.cfg.spec_policy_since ? STAMP_NOTE : null,
+        note:
+          c.key === "spec_policy" && next.spec_policy_since !== strict.cfg.spec_policy_since
+            ? STAMP_NOTE
+            : c.key === "lifecycle_gates" && next.gates_since !== strict.cfg.gates_since
+              ? GATES_NOTE
+              : null,
       });
     if (changed.length) steps.push({ writer: "vault", patch, keys: changed.map((c) => c.key) });
   }