projectstore-claude 0.30.9 → 0.30.11

package/node_modules/projectstore/docs/extending.md

@@ -6,7 +6,8 @@ Since v0.14 the kind machinery is layout-driven: `draft.mjs` builds ANY kind
 declared in the layout, and doctor's template check follows the layout instead
 of a hardcoded list. A new kind needs **six touch points** — note that **all
 six live inside the plugin installation**, not in your vault (there is no
-vault-side layout or template override):
+vault-side layout or template override). The one exception is the guide
+(step 4): a vault may override it, file by file.
 
 1. **Layout folder entry** — `scaffold/layouts/<name>.json` → `folders`:
 
@@ -46,8 +47,31 @@ vault-side layout or template override):
    but an empty date sorts first, so the kind's rows pile up at the top of
    its index and stay there.
 
-4. **Checklist entry** — `scaffold/checklists.json`, consumed by
-   `/projectstore:review` and the `projectstore-peer-reviewer` skill. English-only by design.
+4. **Guide file** — `scaffold/guides/<kind>.md`, the kind's authoring guide:
+   frontmatter `guide_for: <kind>`, `guide_version: 1` and `default_review`
+   (bare values, no trailing comments), then `## Lens`, `## Must`,
+   `## Common mistakes`, `## Do not write` and `## Length`. Only `## Must` is
+   required; its plain bullets are the checklist the critic checks. The kind's
+   command reads the guide before the draft, `/projectstore:review` and the
+   critic check its `## Must`, and the `projectstore-peer-reviewer` skill reads
+   its `default_review`. The headings are English in every vault language; the
+   package defaults are English only. Bump `guide_version` whenever you change
+   a default's text, then record it:
+
+   ```
+   node tests/fixtures/guides.mjs --write
+   ```
+
+   A project overrides a guide in its vault, as `<vault>/guides/<kind>.md`,
+   which replaces the package file whole. To start from the default:
+
+   ```
+   npx projectstore guide eject <kind> --write
+   ```
+
+   Doctor reports a vault guide that does not parse (`guide-shape`), names an
+   unknown kind (`guide-unknown`), or was made from an older default
+   (`guide-stale`).
 
 5. **Command prompt** — `commands/<kind>.md`, a prompt (not code). It renders
    the draft with the line below, previews it, and gates every write behind
@@ -181,8 +205,23 @@ nothing checking that they agree — see the PS-I18N epic's backlog.
 
 `<vault>/.projectstore.json` (vault root — committed with the vault, survives
 clones) carries `spec_policy: required|optional`, `lifecycle_gates: on|off`,
-and `spec_policy_since` (ISO-8601). See ADR-007 in the project vault and
-`commands/doctor.md` for which checks each key activates.
+`spec_policy_since` and `gates_since` (ISO-8601). See ADR-007 and the spec
+policy ADR in the project vault, and `commands/doctor.md`, for which checks
+each key activates.
+
+- `configure` stamps `spec_policy_since` when the policy becomes `required`,
+  and `gates_since` when the lifecycle gates turn on. A done story closed
+  before the date is legacy. The lifecycle checks read `spec_policy_since`,
+  then `gates_since`.
+- A story may declare `no_spec: "<reason>"` at the plan gate instead of a
+  covering spec. Under `required`, doctor accepts it. Under any policy it
+  checks the declaration:
+  - an empty reason, or `no_spec` beside `specs:`, is an issue;
+  - three or more source files in the story's `code_refs` is a warn;
+  - when opt-outs outnumber covered stories among code stories, that is a
+    warn.
+- `doctor --vault --policy required[@<date>]` shows what `required` would
+  report, without writing anything.
 
 ## Contributing back
 

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.9",
+  "version": "0.30.11",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

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

@@ -0,0 +1,42 @@
+---
+guide_for: adr
+guide_version: 1
+default_review: true
+---
+
+## Lens
+
+The architect who will be asked in a year why this was decided. Write for a stranger who has only this file: they must be able to implement the decision, and to find what was rejected and why.
+
+## Must
+
+- Decision section is unambiguous — a stranger could implement it from this file alone, with no other context.
+- At least one named Alternative is present with an explicit rejection reason ('Rejected because: ...').
+- Consequences include at least one Negative / trade-off stated honestly. Reject sales framing.
+- All hand-wavy referents ('we', 'users', 'the system') are resolved to concrete actors or components.
+- No marketing language: 'blazingly', 'robust', 'best-in-class', 'magnificent', 'rock-solid', etc.
+- Context explains why the decision is needed NOW (vs. a year ago or in 6 months).
+- References cite at least one external doc / prior ADR / RFC if relevant.
+- Status, Date, Authors metadata filled (not template placeholders).
+- No TODOs, no '...', no empty bullets in the final body.
+
+## Common mistakes
+
+- The Decision restates the Context or lists options instead of deciding. Number each decision, so a test or a reviewer can tell whether the code does it.
+- Alternatives are straw men: no real Pros, and a "Rejected because" that fits any project. Name this project's constraint.
+- Claims about the code written from memory. Cite the file and symbol; copy counts and numbers from the source or a measurement.
+- Consequences list only the good. Negative / trade-offs is the section a critic reads first: state the cost and who pays it.
+- A rule with no enforcement point. Say which test, doctor check or command text makes it true.
+- An accepted ADR it amends or contradicts is not named, or is contradicted silently.
+- Artifacts named by session shorthand instead of their title (and, for an epic or story, its parent).
+
+## Do not write
+
+- A plan, a file list or a task list: those belong to the spec and the story.
+- The Decision restated under Rationale.
+- Marketing adjectives, or hedges (might, ideally, probably) inside a Decision.
+- The ADR's own revision history in the body: the vault history holds it.
+
+## Length
+
+One decision fits one screen; the whole ADR 100 to 250 lines. Past 300, split it into ADRs with their own lifecycles.

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

@@ -0,0 +1,10 @@
+---
+guide_for: concept
+guide_version: 1
+default_review: false
+---
+
+## Must
+
+- Definition fits in one paragraph; a stranger leaves knowing what the concept IS.
+- Examples ground the concept (at least one concrete case).

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/scaffold/guides/story.test.md

@@ -0,0 +1,34 @@
+---
+guide_for: story.test
+guide_version: 1
+default_review: false
+---
+
+## Lens
+
+The test lead who reads a contract and asks what will break it in production. The scenarios show the happy path; this story covers the cases around it.
+
+## Must
+
+- Names the spec contracts it covers by citation token.
+- Lists, for each contract, the cases that apply out of: boundary values, invalid input, state transitions, failure of a dependency, retry and concurrency, partial failure, upgrade from an older state, rollback.
+- States which cases it deliberately leaves untested, and why.
+- Requires every test it adds to cite the contract it covers.
+
+## Common mistakes
+
+- Restating the contract's scenarios as the test list. Add the cases they miss, beyond any already marked `(edge)` or `(failure)`.
+- All eight cases under every contract. Keep the ones this contract can meet, and name the ones you dropped.
+- A case with no observable outcome ("handles errors"). Name what is asserted: an exit code, a finding, a file left byte-identical.
+- A citation token for a real key in prose or an example. Use the reserved key, as in `[example#3]`.
+- Acceptance criteria that repeat the decomposition ("write the tests") instead of an outcome a reviewer can run.
+
+## Do not write
+
+- Test code or assertions: the story names the cases, the tests hold the asserts.
+- A covered contract restated in full: cite it by token.
+- A case for behaviour no covered contract promises.
+
+## Length
+
+A short description; one case list per covered contract, at most four contracts; four to ten criteria, each tied to a case; 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) });
   }