projectstore-claude 0.30.10 → 0.30.11

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "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 an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.30.10",
+      "version": "0.30.11",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.30.10",
+  "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.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/commands/story.md

@@ -1,6 +1,6 @@
 ---
 description: Create a new story inside an existing epic, or run its lifecycle gates (plan / close).
-argument-hint: <epic-id> <title> [--spec SPEC-ID] | plan <story> | close <story>
+argument-hint: <epic-id> <title> [--spec SPEC-ID] [--variant test] | plan <story> | close <story>
 ---
 
 You are managing a story: creating one, or running its lifecycle gates.
@@ -18,12 +18,21 @@ the two cannot collide).
 
 2. **Validate args**: epic-id (positional 1) + title (rest). If only one word, ask for the title. An optional `--spec SPEC-ID` names the covering spec — put it into the rendered draft's `specs:` list (inline flow: `specs: ["SPEC-001"]`). Under `spec_policy: required` (vault's `.projectstore.json`), remind that a story needs a covering spec before implementation starts, or a `no_spec` reason declared at the plan gate.
 
+   An optional `--variant test` makes a **test story**: one that plans the
+   tests for a spec's contracts, written to the `story.test` guide. Only
+   `test` is defined: refuse another value and name `test`. Remove `--variant test` and `--spec SPEC-ID` with its
+   value from the arguments before any `draft.mjs` call, in step 3 and in the
+   re-run of step 6: the script reads every remaining word as the title, so a
+   flag left in would end up in the title and the slug.
+
 2a. **Read the guide** for this kind before writing anything:
 
    ```bash
    node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" guide story --project "${CLAUDE_PROJECT_DIR}"
    ```
 
+   For a test story read `guide story.test` instead, in the same form.
+
    Write the draft to its `## Must`, `## Common mistakes`, `## Do not write`
    and `## Length`: the critic checks the same `## Must` items. Exit 1 means
    this kind has no guide; say so and go on.
@@ -31,10 +40,15 @@ the two cannot collide).
 3. **Render draft**:
 
    ```bash
-   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" story "$ARGUMENTS"
+   node "${CLAUDE_PLUGIN_ROOT}/scripts/draft.mjs" story <epic-id> "<title>"
    ```
 
-   The script fails if the epic folder does not exist. Surface the error and suggest `/projectstore:epic <id> "<title>"` first.
+   The epic id and the title only, with the flags of step 2 removed. The
+   script fails if the epic folder does not exist. Surface the error and suggest `/projectstore:epic <id> "<title>"` first.
+
+3a. **For a test story**, replace the draft's commented `# variant: test …`
+   line with `variant: test` before the preview, the way `--spec` fills
+   `specs:`. The critic then reviews the story against `story.test`.
 
 4. **Preview**: path + first ~25 lines.
 
@@ -42,9 +56,10 @@ the two cannot collide).
 
    When prompting "Edit", note that the story template has a `Decomposition` checklist — if the user wants to seed it with concrete tasks from the current conversation, regenerate with those tasks pre-filled in place of the empty checkboxes.
 
-6. **Post-approval race re-check** (Layer 1): re-run `draft.mjs story "$ARGUMENTS"` and re-read its `collision` field — an exact-name `test -e` cannot see normalized cross-era collisions (`story-006-foo.md` vs `story-foo.md`). If `collision` is non-null, surface it as a topic collision (`"<identity>" already exists as <with>`), and ask: extend the existing story, pick a different slug (`-2` is a deliberate distinct identity), or cancel. Render `warnings` entries as `⚠️` lines in the preview too.
+6. **Post-approval race re-check** (Layer 1): re-run `draft.mjs story <epic-id> "<title>"` (the same stripped arguments as step 3) and re-read its `collision` field — an exact-name `test -e` cannot see normalized cross-era collisions (`story-006-foo.md` vs `story-foo.md`). If `collision` is non-null, surface it as a topic collision (`"<identity>" already exists as <with>`), and ask: extend the existing story, pick a different slug (`-2` is a deliberate distinct identity), or cancel. Render `warnings` entries as `⚠️` lines in the preview too.
 
-7. **On Yes** (path free): Write file.
+7. **On Yes** (path free): Write the file you previewed, with the step-2 and
+   step-3a edits (`specs:`, `variant: test`), not the re-run's raw draft.
 
 8. **Suggest next**: "Now decompose the work in the `Decomposition` section, or run `/projectstore:kanban` to refresh the board. Before implementation: `/projectstore:story plan <story>`."
 

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

@@ -4,7 +4,10 @@ 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*.
+and a declared per-story opt-out from a spec*, and decisions 6 and 7 of the
+ADR *One authoring guide per artifact kind, read by the author before the
+draft and by the critic after, overridable from the vault* (edge and failure
+marks, and test stories).
 
 All of it is optional. A spec without scenarios, and a test without a
 citation, stay valid.
@@ -31,8 +34,75 @@ 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.
+Doctor reads scenarios for two things. If a contract's scenario has no
+`WHEN` (or `GIVEN`), or no `THEN`, it reports an info. And it counts the
+scenarios marked as an edge or a failure case, below.
+
+An item may wrap: a line indented deeper than its dash, before a blank line,
+belongs to the item above it.
+
+## Marking an edge or a failure case
+
+A scenario's `WHEN` or `GIVEN` item may end with `(edge)` or `(failure)`:
+
+```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
+   - GIVEN a folder whose README is missing (edge)
+   - WHEN doctor runs with --vault
+   - THEN it reports the missing index, and nothing else in that folder
+```
+
+`(edge)` is for a case that comes from the input or the state: boundary
+values, invalid input, a state transition, an upgrade from an older state.
+`(failure)` is for a case where something else fails: a dependency, a retry
+or a concurrent run, a partial failure, a rollback. A happy-path scenario
+has no mark.
+
+The mark is lowercase English in ASCII parentheses, at the very end of the
+item (on its last line when the item wraps). A mark on an `AND` or `THEN`
+item, in the contract's prose, inside backticks, or followed by more text
+does not count.
+
+For each active spec, doctor lists the contracts that carry scenarios and
+have none marked: their scenarios show only the happy path. It counts the
+marks and does not judge them. Whether a marked scenario is a real edge case
+is the critic's question.
+
+## Writing a test story
+
+A test story plans the tests for one or more contracts. Create it with the
+variant flag, and its draft is written to the test lead's guide, `story.test`:
+
+```
+/projectstore:story PS-X "Tests for the stale-index contract" --variant test
+```
+
+The guide asks the story to name the contracts it covers by token, to list
+the cases that apply to each (boundary values, invalid input, state
+transitions, failure of a dependency, retry and concurrency, partial failure,
+upgrade from an older state, rollback), to say which cases it leaves untested
+and why, and to require a citation on every test it adds. For example:
+
+```markdown
+## Description
+
+Covers [example#3]. The scenario shows the happy path; the cases below are
+the ones a production vault hits.
+
+## Decomposition
+
+- [ ] Boundary: an index with no rows, and one with a row per artifact.
+- [ ] Invalid input: a row whose link points at no file.
+- [ ] Partial failure: one folder's README unreadable, the others fine.
+- [ ] Not tested: concurrency. Doctor is read-only, so two runs cannot race.
+```
+
+The story has `variant: test` in its frontmatter and follows every other
+story rule: the plan and close gates, evidence, the board.
 
 ## A contract no test can cover
 
@@ -97,6 +167,7 @@ skipped. Tests outside the bound project, or in a submodule, are not seen.
 | `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 |
+| `contract-happy-path-only` | info | One line per active spec: the contracts that carry scenarios and have none marked `(edge)` or `(failure)` |
 | `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 |
 

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.10",
+  "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/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/doctor.mjs

@@ -2698,6 +2698,9 @@ export function parseSpecContracts(spec) {
   const contracts = [];
   let cur = null;
   let inFirstPara = false;
+  // The scenario item a continuation line belongs to (SPEC-001 contract 13):
+  // a line indented deeper than its dash, not a bullet, before a blank line.
+  let open = null;
   for (const line of lines) {
     const top = line.match(/^(\d+[′″']*)\.(\s|$)/);
     if (top) {
@@ -2707,15 +2710,18 @@ export function parseSpecContracts(spec) {
         stepIndent: null,
         scenarios: [],
         marker: null,
+        marks: [],
         first: line,
       };
       contracts.push(cur);
       inFirstPara = true;
+      open = null;
       continue;
     }
     if (!cur) continue;
     if (/^\s*$/.test(line)) {
       inFirstPara = false;
+      open = null;
       continue;
     }
     if (inFirstPara) cur.first += " " + line.trim();
@@ -2723,14 +2729,24 @@ export function parseSpecContracts(spec) {
     if (step) {
       if (cur.stepIndent === null) cur.stepIndent = step[1].length;
       if (step[1].length === cur.stepIndent) cur.steps.add(contractNumberAscii(step[2]));
+      open = null;
       continue;
     }
-    const sc = line.match(/^\s*-\s+(WHEN|GIVEN|AND|THEN)\b/);
-    if (sc) cur.scenarios.push(line.trim());
+    const sc = line.match(/^(\s*)-\s+(WHEN|GIVEN|AND|THEN)\b/);
+    if (sc) {
+      cur.scenarios.push(line.trim());
+      open = { i: cur.scenarios.length - 1, indent: sc[1].length };
+      continue;
+    }
+    if (open && line.match(/^\s*/)[0].length > open.indent && !/^\s*[-*+]\s/.test(line))
+      cur.scenarios[open.i] += " " + line.trim();
+    else open = null;
   }
   for (const c of contracts) {
     const mk = c.first.match(/\(verified\s*[:：]\s*(live|manual)\)/);
     c.marker = mk ? mk[1] : null;
+    // An (edge) or (failure) mark closes a WHEN or GIVEN item; nowhere else counts.
+    c.marks = c.scenarios.map((l) => /^-\s+(WHEN|GIVEN)\b.*\((edge|failure)\)\s*$/.exec(l)?.[2]).filter(Boolean);
     delete c.first;
     delete c.stepIndent;
   }
@@ -2808,8 +2824,30 @@ export function checkSpecAliases(artifacts) {
   return out;
 }
 
+// Happy path only (SPEC-001 contract 13; the authoring-guides ADR, decision
+// 7): the contracts of an active spec that carry scenarios and have none
+// marked (edge) or (failure). Counted, not judged; no git.
+export function checkHappyPathOnly(artifacts) {
+  const out = [];
+  for (const s of artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active")) {
+    const withScenarios = (parseSpecContracts(s) || []).filter((c) => c.scenarios.length);
+    const bare = withScenarios.filter((c) => !c.marks.length).map((c) => c.n);
+    if (!bare.length) continue;
+    out.push(
+      finding(
+        "vault",
+        "info",
+        "contract-happy-path-only",
+        `${bare.length} of ${withScenarios.length} contracts with scenarios have no scenario marked (edge) or (failure): ${bare.join(", ")}.`,
+        s.rel,
+      ),
+    );
+  }
+  return out;
+}
+
 // Scenario shape (Decision 3): a contract's scenario items need a WHEN (or
-// GIVEN) and a THEN. That is the only reading of scenarios.
+// GIVEN) and a THEN.
 export function checkScenarioShape(artifacts) {
   const out = [];
   for (const s of artifacts.filter((a) => a.kind === "spec")) {
@@ -3850,6 +3888,7 @@ export function runVaultChecks(
     () => checkLifecycleGates(artifacts, vaultCfg),
     () => checkSpecAliases(artifacts),
     () => checkScenarioShape(artifacts),
+    () => checkHappyPathOnly(artifacts),
     () => {
       const scan = scanCitations(cfg, artifacts, proj, grep);
       return [...checkContractCitations(artifacts, scan), ...checkEvidenceCitations(artifacts, vaultCfg, scan)];

package/node_modules/projectstore/templates/de/story.md.tmpl

@@ -13,6 +13,7 @@ tags: {{tags}}
 code_refs: []
 specs: []
 # no_spec: "<warum diese Story keine Spec braucht>"  (wird am Plan-Gate geschrieben)
+# variant: test  (eine Test-Story; ihr Guide ist story.test)
 started_at: null
 closed_at: null
 plan_updated_at: null

package/node_modules/projectstore/templates/en/story.md.tmpl

@@ -13,6 +13,7 @@ tags: {{tags}}
 code_refs: []
 specs: []
 # no_spec: "<why this story needs no spec>"  (written at the plan gate)
+# variant: test  (a test story; its guide is story.test)
 started_at: null
 closed_at: null
 plan_updated_at: null

package/node_modules/projectstore/templates/es/story.md.tmpl

@@ -13,6 +13,7 @@ tags: {{tags}}
 code_refs: []
 specs: []
 # no_spec: "<por qué esta historia no necesita spec>"  (se escribe en el plan gate)
+# variant: test  (una historia de pruebas; su guía es story.test)
 started_at: null
 closed_at: null
 plan_updated_at: null

package/node_modules/projectstore/templates/fr/story.md.tmpl

@@ -13,6 +13,7 @@ tags: {{tags}}
 code_refs: []
 specs: []
 # no_spec: "<pourquoi cette story n'a pas besoin de spec>"  (écrit au plan gate)
+# variant: test  (une story de test ; son guide est story.test)
 started_at: null
 closed_at: null
 plan_updated_at: null

package/node_modules/projectstore/templates/ru/story.md.tmpl

@@ -13,6 +13,7 @@ tags: {{tags}}
 code_refs: []
 specs: []
 # no_spec: "<почему этой стори не нужна спека>"  (пишется на plan gate)
+# variant: test  (тестовая стори; её гайд — story.test)
 started_at: null
 closed_at: null
 plan_updated_at: null

package/node_modules/projectstore/templates/zh/story.md.tmpl

@@ -13,6 +13,7 @@ tags: {{tags}}
 code_refs: []
 specs: []
 # no_spec: "<为什么这个故事不需要 spec>"  （在 plan gate 写入）
+# variant: test  （测试故事；其 guide 为 story.test）
 started_at: null
 closed_at: null
 plan_updated_at: null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.10",
+  "version": "0.30.11",
   "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.30.10"
+    "projectstore": "=0.30.11"
   },
   "bundleDependencies": [
     "projectstore"