projectstore-claude 0.30.8 → 0.30.10

package/node_modules/projectstore/docs/contracts-and-tests.md

@@ -0,0 +1,107 @@
+# Contracts and tests
+
+A spec's behavioral contracts are numbered and testable. This page shows how
+to write a contract so a test follows from it, how a test cites the contract
+it covers, and what doctor reports. It describes Part A of the ADR *Spec
+policy, revised: contract scenarios and test citations that doctor counts,
+and a declared per-story opt-out from a spec*.
+
+All of it is optional. A spec without scenarios, and a test without a
+citation, stay valid.
+
+Every example on this page uses the key `example`. It is reserved: no spec
+may use it as an id or alias, so a token written with it never resolves and
+never counts as coverage. A real token in a doc would count, so docs use only
+`example`.
+
+## Scenarios under a contract
+
+A contract may carry list items that start with `WHEN`, `GIVEN`, `AND` or
+`THEN`:
+
+```markdown
+3. **A stale index is reported.** Doctor compares each folder index with the
+   artifacts on disk and reports a row that no longer matches.
+   - GIVEN an index row whose status differs from the artifact's frontmatter
+   - WHEN doctor runs with --vault
+   - THEN it reports an index finding that names the folder
+```
+
+The items are a list, so Markdown keeps one step per line. The keywords stay
+in English in every language, like `— stories:`: a tool matches them
+literally.
+
+Doctor reads scenarios for one thing only. If a contract's scenario has no
+`WHEN` (or `GIVEN`), or no `THEN`, it reports an info.
+
+## A contract no test can cover
+
+Some contracts are checked on a real host after install, or by a person.
+Mark them in the contract's first paragraph:
+
+```markdown
+7. **The band draws in a live session.** (verified: live)
+```
+
+Use `(verified: live)` or `(verified: manual)`. Doctor does not count a
+marked contract as uncovered.
+
+## Citing a contract from a test
+
+A test cites a contract with a bracketed token, `[<key>#<n>]`, in its name or
+in a comment beside it:
+
+```js
+// [example#3]
+test("doctor reports a stale index row", () => {
+  // … assert the finding names the folder
+});
+```
+
+- `<key>` is the spec's frontmatter `id`, or its `alias`. Matching is
+  case-sensitive.
+- `<n>` is the contract number in ASCII: `0`, `4`, `4'` for `4′`, `4''` for
+  `4″`. A step nested under contract 4 is `4/1''`. A cited step does not
+  cover its parent.
+- The closing bracket ends the token, so `[example#4]` never matches
+  contract `4'` or `40`. A token followed by `(` is a Markdown link, and a
+  `[[…]]` is a wikilink. Neither is a citation.
+
+A slug id runs to about 60 characters, so give a spec a short alias in its
+frontmatter:
+
+```yaml
+alias: billing
+```
+
+Its tests then cite its contracts with `billing` as the key. (This page
+writes that out in words rather than as a token, because a token in a doc
+is scanned like one in a test.)
+
+An alias is frozen like a slug, because renaming it breaks every citation.
+Two specs may not share an alias, and an alias may not be another spec's id.
+
+A citation is a claim: the reviewer checks that a cited test asserts the
+contract's outcome. An empty test with a token is a review finding.
+
+## What doctor reports
+
+Doctor (`--vault`) scans the bound project with `git grep --untracked`, so a
+test you have not added yet is found too. `.gitignore`d files, a vault
+inside the project, `node_modules/` and the other generated paths are
+skipped. Tests outside the bound project, or in a submodule, are not seen.
+
+| Finding | Level | When |
+|---|---|---|
+| `contract-coverage` | info | One line per active spec. With no citation: "N contracts, 0 cited". Once a spec has a citation, or sets `coverage: report` in its frontmatter: the contracts no test cites |
+| `citation-unknown` | warn | A token whose key is no spec's id or alias, or whose number is not a contract of that spec |
+| `citation-superseded` | info | A token that cites a superseded spec |
+| `scenario-shape` | info | A scenario without a WHEN/GIVEN or a THEN |
+| `spec-alias` | issue | A duplicate alias, an alias equal to another spec's id, or the reserved `example` |
+| `evidence-citation` | warn | Under `lifecycle_gates: on`: a story's evidence names a token that no file in the project carries |
+
+Each report names the checkout it read. A worktree on an old branch, or a
+second project bound to the same vault, can see different coverage.
+
+Doctor never runs a test. CI and `npm test` do that. Doctor checks the
+record: which contracts are cited, and whether a cited token still exists.

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/harnesses/claude-code.json

@@ -311,9 +311,9 @@
       "dir": ".",
       "file": ".mcp.json",
       "entry": "scripts/mcp-server.mjs",
-      "entry_reason": "The script .mcp.json runs, under the plugin root, with --project and the host's project directory as its only arguments. It lives under scripts/, never bin/ (a plugin's top-level bin/ is on the host's Bash PATH), and imports nothing from cli.mjs, so the server's imports reach no install verb (PS-DIRECTORY, the story \"The MCP server's entry reaches no install verb through a read-verb runner that shares the CLI's verb table…\"; the MCP ADR's decision 1 as amended). The CLI's `mcp` verb serves the same way, for a host without a plugin channel.",
+      "entry_reason": "The script .mcp.json runs, under the plugin root, with no other argument: the project comes from CLAUDE_PROJECT_DIR, which the host exports to the server (launch.project_dir_in_env), since 0.30.9 (PS-DIRECTORY, the story \"The MCP server's entry names no variable but ${CLAUDE_PLUGIN_ROOT}…\"). It lives under scripts/, never bin/ (a plugin's top-level bin/ is on the host's Bash PATH), and imports nothing from cli.mjs, so the server's imports reach no install verb (PS-DIRECTORY, the story \"The MCP server's entry reaches no install verb through a read-verb runner that shares the CLI's verb table…\"; the MCP ADR's decision 1 as amended). The CLI's `mcp` verb serves the same way, for a host without a plugin channel.",
       "scope": "plugin",
-      "scope_reason": "Claude Code loads a plugin's .mcp.json from the plugin installation itself and expands ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} in it per session, so the one shipped file binds each server to one project (MCP ADR decision 6, amended 2026-09-05); nothing is installed and nothing is derived — the host kind install-harness skips, which the install spec's contract 0 does not yet name.",
+      "scope_reason": "Claude Code loads a plugin's .mcp.json from the plugin installation itself and expands ${CLAUDE_PLUGIN_ROOT} in it and exports CLAUDE_PROJECT_DIR to the server per session, so the one shipped file binds each server to one project (MCP ADR decision 6, amended 2026-09-05); nothing is installed and nothing is derived — the host kind install-harness skips, which the install spec's contract 0 does not yet name.",
       "launch": {
         "cwd": "project",
         "project_dir_in_env": true,
@@ -326,7 +326,7 @@
         ],
         "default_syntax": "${VAR:-default}",
         "unset_placeholder_in_env": "literal",
-        "unset_placeholder_in_args": "inferred literal — the server refuses a --project still carrying a dollar-brace placeholder",
+        "unset_placeholder_in_args": "inferred literal — measured through the 0.30.8 form, which the server refused as a placeholder",
         "entrypoint": "sdk-cli (headless -p), plugin loaded with --plugin-dir; the marketplace install and an interactive session are A9's",
         "protocol_era": "initialize",
         "protocol_version_seen": "2025-11-25",

package/node_modules/projectstore/harnesses/codex.json

@@ -240,7 +240,7 @@
       "kind": "host",
       "scope": "project",
       "scope_reason": "Codex auto-discovers a plugin-root .mcp.json even when the manifest does not declare mcpServers — measured.",
-      "why_unsupported": "Our .mcp.json is in Claude Code's dialect: its argv carries ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR}, which nothing substitutes there, so the server failed its handshake and printed a red error in every session. Ships only once the Codex dialect is rendered and the spike's criterion (h) says what cwd and environment the server receives."
+      "why_unsupported": "Our .mcp.json is in Claude Code's dialect: its argv needs ${CLAUDE_PLUGIN_ROOT} expanded, which nothing substitutes there, and the server needs CLAUDE_PROJECT_DIR in its environment, which Codex does not export. With its earlier argv, which named the project variable too, the server failed its handshake and printed a red error in every session. Ships only once the Codex dialect is rendered and the spike's criterion (h) says what cwd and environment the server receives."
     },
     "skills": {
       "supported": true,

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.8",
+  "version": "0.30.10",
   "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/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) });
   }

package/node_modules/projectstore/scripts/diff-refs.mjs

@@ -64,6 +64,45 @@ export function lastCommitMs(cwd = projectRoot()) {
   return Number.isFinite(t) ? t : null;
 }
 
+// The citation scan (the spec policy ADR, Decision 7): every line in the
+// project, untracked files included, that looks like a contract citation.
+// `.gitignore` is honoured, `exclude` paths (the vault, when it sits inside
+// the project) are skipped, and SOURCE_IGNORE paths are dropped. Unlike gitIn
+// this tells "no match" (status ok, no lines) from "not a repository"
+// (no-git) and from every other failure — no git binary, a timeout, an exit
+// git explains on stderr (unknown, with that reason): only the first is an
+// answer.
+export function grepProjectLines(cwd, pattern, { exclude = [], timeout = 10000, ignore = IGNORE } = {}) {
+  const args = [
+    "grep",
+    "--untracked",
+    "-n",
+    "-I",
+    "-E",
+    "-e",
+    pattern,
+    "--",
+    ".",
+    ...exclude.map((p) => `:(exclude)${p}`),
+  ];
+  const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout, maxBuffer: 64 * 1024 * 1024 });
+  if (r.error?.code === "ENOENT") return { status: "unknown", reason: "git is not installed", lines: [] };
+  if (r.error || r.signal) return { status: "unknown", reason: "the scan timed out", lines: [] };
+  if (r.status === 1) return { status: "ok", lines: [] };
+  if (/not a git repository/i.test(r.stderr || "")) return { status: "no-git", lines: [] };
+  if (r.status !== 0) {
+    const why = (r.stderr || "").trim().split("\n")[0] || `git exited ${r.status}`;
+    return { status: "unknown", reason: why, lines: [] };
+  }
+  const lines = [];
+  for (const raw of r.stdout.split("\n")) {
+    const m = raw.match(/^(.*?):(\d+):(.*)$/);
+    if (!m || ignore.some((rx) => rx.test(m[1]))) continue;
+    lines.push({ file: m[1], line: Number(m[2]), text: m[3] });
+  }
+  return { status: "ok", lines };
+}
+
 function filterFiles(list) {
   return [...new Set(list)]
     .map((f) => f.trim())