projectstore-claude 0.30.13 → 0.30.15

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.13",
+      "version": "0.30.15",
       "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.13",
+  "version": "0.30.15",
   "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/agents/planner.md

@@ -44,7 +44,10 @@ spec, say so FIRST — under spec-first the spec must exist and be `active`
 before implementation starts (suggest `/projectstore:spec`). Routing rule:
 spec contracts = durable how; the story's `## Implementation Plan` = per-story
 route (your output feeds it via `/projectstore:story plan`); `## Technical
-Notes` = incidental constraints discovered during work.
+Notes` = incidental constraints discovered during work. When the story changes
+a covering spec's contracts, name each contract it will amend and the marker's
+kind (`ADDED`, `MODIFIED` or `REMOVED`, in a `> amended YYYY-MM-DD by <ref>: …`
+block under the contract; `guide spec` has the rules).
 
 **Spec or no spec.** When the story has no covering spec, say whether it
 needs one, and why. Work whose "how" is non-trivial, or that will touch three

package/node_modules/projectstore/agents/reviewer.md

@@ -37,7 +37,10 @@ covering spec: its Acceptance items attributed to this story (`— stories:
 verify them exactly like the story's own criteria. A story closes only when
 both sets are green and every covering spec is `active`. Report a covering
 spec still in `draft` as a blocker under `spec_policy: required` (vault's
-`.projectstore.json`).
+`.projectstore.json`). When the story edited a spec's contracts, check that
+each edit carries an amendment marker (`> amended YYYY-MM-DD by <ref>: <KIND> —
+<why>` under the contract): from the vault's git history when the vault has
+one, else from the story's own account; an unmarked edit is a finding.
 
 **A declared opt-out, at close.** A story with `no_spec: "<reason>"` has no
 covering spec on purpose. Compute its files (Output 4). If it touches three

package/node_modules/projectstore/commands/doctor.md

@@ -194,6 +194,17 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
   gates that have no date, `review-by` names an ADR due for review, and
   `dry-run` heads a `--policy` report. None of them is repairable by `--fix`:
   each is a judgement, or a `configure` step its message names.
+- The amendment checks read the markers under a spec's contracts
+  (`> amended YYYY-MM-DD by <ref>: ADDED|MODIFIED|REMOVED — <why>`) in every
+  spec, under every policy: `amendment-form` (a marker that is not the grammar,
+  comes before the first contract or after a `REMOVED`; it counts for
+  nothing), `amendment-story` (an issue: the ref names no single story),
+  `amendment-link` (neither the story nor the spec lists the other) and
+  `amendment-date` (not a date, before the spec's `date:`, after tomorrow, or
+  before the previous marker under that contract). `citation-removed` is a
+  token in the project that cites a removed contract or step, with the why of
+  its marker. None of them is repairable by `--fix`: the marker and the test
+  are the author's text.
 - The guide checks read the vault's `guides/` folder, the per-kind overrides
   of the authoring guides: `guide-shape` (an override that does not parse, so
   readers fall back to the package default), `guide-unknown` (a guide for a

package/node_modules/projectstore/commands/graph.md

@@ -51,6 +51,10 @@ vault-link-graph-derived-view-and-shared-link-resolver).
   artifact's full typed neighborhood — outgoing AND incoming edges — in one
   call. Node keys are full vault-relative paths, never short names.
 - Edge kinds: wikilink, mdlink, supersedes, spec-covers, spec-implements-adr,
-  epic-contains, dead, ambiguous, out-of-scope. Nothing resolves silently.
+  epic-contains, amends, dead, ambiguous, out-of-scope. Nothing resolves
+  silently. `amends` runs from a story to a spec one of its amendment markers
+  (`> amended YYYY-MM-DD by <ref>: <KIND> — <why>` under a contract) changes:
+  one edge per pair; a marker whose ref resolves to no story is a `dead` edge
+  from the spec.
 - Hand-edits to graph.md never stick: doctor flags staleness, reconcile
   repairs. Fix the source artifact, then regenerate.

package/node_modules/projectstore/commands/story.md

@@ -118,7 +118,10 @@ the two cannot collide).
    today's date, then one bullet per question with its answer; a later plan
    run appends its own dated line to the same subsection. An answer that changes a
    contract of the covering spec says which one, and the spec is amended
-   the way it records its other amendments before the code is written.
+   before the code is written: that contract's body is rewritten to the text
+   in force, with a marker under it,
+   `> amended YYYY-MM-DD by <EPIC-ID>/<story-id>: ADDED|MODIFIED|REMOVED — <why>`
+   (see `guide spec`).
 
 3. **Fill the section content** in the returned `content` before preview:
    - `plan` — write the Implementation Plan. When the story's `specs:` names a

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

@@ -7,7 +7,9 @@ policy, revised: contract scenarios and test citations that doctor counts,
 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).
+marks, and test stories), and the ADR *An active spec is amended by a marked
+block under the contract, naming the story, the date and the kind, which
+doctor checks and the graph draws* (amendment markers).
 
 All of it is optional. A spec without scenarios, and a test without a
 citation, stay valid.
@@ -171,6 +173,52 @@ 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.
 
+## Amending a contract
+
+A later story that changes a contract of an active spec rewrites the
+contract's body to the text in force and puts a marker under it: a
+blockquote after the contract and before the next one, whose first paragraph
+reads
+
+```markdown
+4. **Exports.** The export runs nightly and keeps seven copies.
+
+   > amended 2026-11-10 by example/story-keep-seven: MODIFIED — seven copies, not three.
+   >
+   > Replaced:
+   >
+   > > keeps three copies
+```
+
+- `amended`, `by`, the kind and `Removed, see below.` stay English in every
+  locale. The ref is any form a spec's `stories:` entry takes
+  (`EPIC-ID/<story-id>`, the story part a short id or the full slug; a ref
+  without `EPIC-ID/` resolves to no story). The colon may be `:` or `：`, the
+  dash `—`, `–` or `-`. A marker may wrap: its first paragraph is read with
+  its lines joined.
+- `MODIFIED`: the body holds the new text; the block quotes what it replaced
+  and why. A step keeps its number: a removed step stays as
+  `2. Removed, see below.`, a new step takes the list's next number.
+- `ADDED`: a new contract takes the highest number in the file, removed ones
+  included, plus one. A number is never reused.
+- `REMOVED`: the contract keeps its number and its heading, and its body
+  becomes `Removed, see below.` This is a tombstone. Nothing follows a
+  `REMOVED` marker; a rule that comes back is `ADDED` under a new number.
+- The story and the spec list each other: the story in the spec's
+  `stories:`, the spec in the story's `specs:`. The amending story is a
+  covered story.
+- Markers inside a fence or an HTML comment do not count, and neither does a
+  marker whose ref starts with `example/` (it is documentation, like the one
+  above). Older `> *Amended …` blocks are not read; the first marker under a
+  contract folds them into the body and quotes them inside its own block.
+
+A tombstone stays forever, so a citation keeps its meaning: a test that
+still cites `[example#4]` after contract 4 was removed is reported as
+`citation-removed`, with the marker's why, and the removed contract leaves
+the coverage count. Evidence in a closed story that names it is not
+reported. `graph.md` and `lineage` show an `amends` edge from the story to
+the spec.
+
 ## What doctor reports
 
 Doctor (`--vault`) scans the bound project with `git grep --untracked`, so a
@@ -182,11 +230,16 @@ skipped. Tests outside the bound project, or in a submodule, are not seen.
 |---|---|---|
 | `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-removed` | warn | A token that cites a removed contract, or a step that reads `Removed, see below.`; the message quotes the marker's why |
 | `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 |
+| `evidence-citation` | warn | Under `lifecycle_gates: on`: a story's evidence names a token that no file in the project carries (a removed contract is skipped) |
+| `amendment-form` | warn | A blockquote under the contracts that starts `amended <date> by` but is not the grammar, comes before the first contract, or follows a `REMOVED`; it counts for nothing |
+| `amendment-story` | issue | A marker's ref names no story, or more than one |
+| `amendment-link` | warn | Neither the marker's story nor the spec lists the other (one side only is `spec-links`) |
+| `amendment-date` | warn | A marker's date is not a date, is before the spec's `date:`, after tomorrow, or before the previous marker under the same contract |
 
 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.

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.13",
+  "version": "0.30.15",
   "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/spec.md

@@ -1,6 +1,6 @@
 ---
 guide_for: spec
-guide_version: 1
+guide_version: 2
 default_review: true
 ---
 
@@ -18,6 +18,10 @@ The systems analyst who writes the contract a test can be written from before th
 - 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.
+- A change to an active spec's contract carries a marker under it, `> amended YYYY-MM-DD by <EPIC-ID>/<story-id>: ADDED|MODIFIED|REMOVED — <why>`; no new block is written in the older `> *Amended …` form.
+- No contract or step number is reused: ADDED takes the highest number in the file, removed contracts included, plus one; REMOVED keeps the number and heading with the body `Removed, see below.`, and a removed step stays as `N. Removed, see below.`
+- Under MODIFIED the body is rewritten to the text in force, and the block quotes the text it replaced; a change written only in the block, over an unchanged body, fails.
+- The first marker under a contract folds that contract's older blocks into the body without changing their meaning, and quotes them inside its own block.
 
 ## Common mistakes
 
@@ -36,4 +40,4 @@ The systems analyst who writes the contract a test can be written from before th
 
 ## 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.
+A contract is one paragraph and at most six scenario items. A spec past twelve contracts or 400 lines covers two subsystems: split it. Blocks under contracts (amendment markers and the text they quote) do not count toward this length.

package/node_modules/projectstore/scripts/doctor.mjs

@@ -52,6 +52,9 @@ import {
   storiesAttributionRe,
   citationTokenRe,
   contractNumberAscii,
+  parseAmendmentMarkers,
+  isCalendarDate,
+  TOMBSTONE_BODY,
   CITATION_EXAMPLE_KEY,
   CITATION_PREFILTER,
   slugIdentity,
@@ -2460,6 +2463,116 @@ export function checkSpecLinks(cfg, layout, artifacts) {
   return out;
 }
 
+// Amendment markers (the ADR "An active spec is amended by a marked block
+// under the contract…", decisions 1, 4 and 5; SPEC-001 contracts 5 and 6),
+// in every spec whatever its status, under every policy:
+//   amendment-form  (warn)  a candidate that is not the grammar, a marker
+//                           before the first contract or after REMOVED;
+//                           such a marker counts for nothing;
+//   amendment-story (issue) the ref resolves to no story, or to several;
+//   amendment-link  (warn)  neither the story nor the spec lists the other
+//                           (one side only is checkSpecLinks' warn);
+//   amendment-date  (warn)  not a calendar date, before the spec's `date:`,
+//                           after tomorrow, or before the previous marker
+//                           under the same contract.
+// One finding per spec and fact: two markers of one unlinked story warn once.
+export function checkAmendments(layout, artifacts, now = new Date().toISOString()) {
+  const out = [];
+  const epicFolder = folderByKind(layout, "epic");
+  const resolveSpec = buildSpecResolver(artifacts, layout);
+  const t = Date.parse(now);
+  const tomorrow = new Date((Number.isFinite(t) ? t : Date.now()) + 86400000).toISOString().slice(0, 10);
+  for (const spec of artifacts.filter((a) => a.kind === "spec")) {
+    const markers = parseAmendmentMarkers(spec.body);
+    if (!markers.length) continue;
+    const seen = new Set();
+    const once = (key, f) => {
+      if (seen.has(key)) return;
+      seen.add(key);
+      out.push(f);
+    };
+    const specDate = String(spec.fm.date || "").slice(0, 10);
+    const prevDate = new Map();
+    for (const m of markers) {
+      const where = m.contract === null ? `line ${m.line}` : `contract ${m.contract} (line ${m.line})`;
+      if (!m.valid) {
+        out.push(
+          finding(
+            "vault",
+            "warn",
+            "amendment-form",
+            `Amendment marker at ${where} counts for nothing: ${m.form}.`,
+            spec.rel,
+          ),
+        );
+        continue;
+      }
+      if (!isCalendarDate(m.date)) {
+        out.push(
+          finding(
+            "vault",
+            "warn",
+            "amendment-date",
+            `Amendment marker at ${where}: ${m.date} is not a date.`,
+            spec.rel,
+          ),
+        );
+      } else {
+        const prev = prevDate.get(m.index);
+        let why = null;
+        if (isCalendarDate(specDate) && m.date < specDate) why = `before the spec's date ${specDate}`;
+        else if (m.date > tomorrow) why = `after tomorrow (${tomorrow})`;
+        else if (prev && m.date < prev) why = `before the previous marker under the same contract (${prev})`;
+        if (why) {
+          out.push(
+            finding(
+              "vault",
+              "warn",
+              "amendment-date",
+              `Amendment marker at ${where} is dated ${m.date}, ${why}.`,
+              spec.rel,
+            ),
+          );
+        }
+        prevDate.set(m.index, m.date);
+      }
+      const r = epicFolder
+        ? resolveSpecStory(m.ref, artifacts, epicFolder.path)
+        : { error: "the layout has no epic folder" };
+      if (r.error) {
+        once(
+          `story ${m.ref}`,
+          finding(
+            "vault",
+            "issue",
+            "amendment-story",
+            `Amendment marker at ${where} names "${m.ref}", which resolves to no single story: ${r.error}.`,
+            spec.rel,
+          ),
+        );
+        continue;
+      }
+      const storyListsSpec = listOf(r.story.fm, "specs").some((ref) => resolveSpec(ref) === spec);
+      const specListsStory = listOf(spec.fm, "stories").some(
+        (e) => resolveSpecStory(e, artifacts, epicFolder.path).story === r.story,
+      );
+      if (!storyListsSpec && !specListsStory) {
+        once(
+          `link ${r.story.rel}`,
+          finding(
+            "vault",
+            "warn",
+            "amendment-link",
+            `Amendment marker at ${where} names ${r.story.rel}, but neither lists the other: add the spec to the story's \`specs:\` and the story to the spec's \`stories:\`.`,
+            spec.rel,
+          ),
+        );
+      }
+    }
+  }
+  return out;
+}
+
 // In-scope story = status beyond planned, not legacy-exempt.
 function specScopeStatus(fm) {
   const s = String(fm.status || "").toLowerCase();
@@ -2691,6 +2804,11 @@ export function checkLifecycleGates(artifacts, vaultCfg) {
 // is not a contract. Scenario items are `- WHEN|GIVEN|AND|THEN …` list items
 // under a contract; the `(verified: live|manual)` marker is looked for in the
 // contract's first paragraph, which a wrapped bold heading may span.
+//
+// Amendment markers (SPEC-001 contract 5) set `removed` on a contract whose
+// last valid marker is REMOVED (a tombstone, with that marker's `why`), and a
+// step is removed when its body, trimmed, is exactly `Removed, see below.`
+// (`removedSteps`). `why` is the latest valid marker's, whatever its kind.
 export function parseSpecContracts(spec) {
   const sec = sectionOf(spec.body || "", "spec_contracts");
   if (sec === null) return null;
@@ -2701,6 +2819,8 @@ export function parseSpecContracts(spec) {
   // 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;
+  // The step a wrapped line belongs to, for the tombstone test.
+  let stepOpen = null;
   for (const line of lines) {
     const top = line.match(/^(\d+[′″']*)\.(\s|$)/);
     if (top) {
@@ -2708,6 +2828,7 @@ export function parseSpecContracts(spec) {
         n: contractNumberAscii(top[1]),
         steps: new Set(),
         stepIndent: null,
+        stepText: new Map(),
         scenarios: [],
         marker: null,
         marks: [],
@@ -2716,22 +2837,34 @@ export function parseSpecContracts(spec) {
       contracts.push(cur);
       inFirstPara = true;
       open = null;
+      stepOpen = null;
       continue;
     }
     if (!cur) continue;
     if (/^\s*$/.test(line)) {
       inFirstPara = false;
       open = null;
+      stepOpen = null;
       continue;
     }
     if (inFirstPara) cur.first += " " + line.trim();
     const step = line.match(/^(\s+)(\d+[′″']*)\.(\s|$)/);
     if (step) {
       if (cur.stepIndent === null) cur.stepIndent = step[1].length;
-      if (step[1].length === cur.stepIndent) cur.steps.add(contractNumberAscii(step[2]));
+      if (step[1].length === cur.stepIndent) {
+        const n = contractNumberAscii(step[2]);
+        cur.steps.add(n);
+        cur.stepText.set(n, line.slice(step[0].length));
+        stepOpen = n;
+      } else stepOpen = null;
       open = null;
       continue;
     }
+    if (stepOpen !== null) {
+      if (line.match(/^\s*/)[0].length > cur.stepIndent && !/^\s*([-*+>]|\d+[′″']*\.)(\s|$)/.test(line))
+        cur.stepText.set(stepOpen, cur.stepText.get(stepOpen) + " " + line.trim());
+      else stepOpen = null;
+    }
     const sc = line.match(/^(\s*)-\s+(WHEN|GIVEN|AND|THEN)\b/);
     if (sc) {
       cur.scenarios.push(line.trim());
@@ -2742,14 +2875,20 @@ export function parseSpecContracts(spec) {
       cur.scenarios[open.i] += " " + line.trim();
     else open = null;
   }
-  for (const c of contracts) {
+  const markers = parseAmendmentMarkers(spec.body || "").filter((m) => m.valid);
+  contracts.forEach((c, i) => {
     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);
+    const last = markers.filter((m) => m.index === i).at(-1) ?? null;
+    c.removed = last?.kind === "REMOVED";
+    c.why = last?.why ?? null;
+    c.removedSteps = new Set([...c.stepText].filter(([, t]) => t.trim() === TOMBSTONE_BODY).map(([n]) => n));
     delete c.first;
     delete c.stepIndent;
-  }
+    delete c.stepText;
+  });
   return contracts;
 }
 
@@ -2826,11 +2965,12 @@ export function checkSpecAliases(artifacts) {
 
 // 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.
+// marked (edge) or (failure). Counted, not judged; no git. A removed
+// contract (contract 5) is not reported, whatever its body still holds.
 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 withScenarios = (parseSpecContracts(s) || []).filter((c) => !c.removed && c.scenarios.length);
     const bare = withScenarios.filter((c) => !c.marks.length).map((c) => c.n);
     if (!bare.length) continue;
     out.push(
@@ -2847,12 +2987,12 @@ export function checkHappyPathOnly(artifacts) {
 }
 
 // Scenario shape (Decision 3): a contract's scenario items need a WHEN (or
-// GIVEN) and a THEN.
+// GIVEN) and a THEN. Removed contracts are skipped.
 export function checkScenarioShape(artifacts) {
   const out = [];
   for (const s of artifacts.filter((a) => a.kind === "spec")) {
     for (const c of parseSpecContracts(s) || []) {
-      if (!c.scenarios.length) continue;
+      if (c.removed || !c.scenarios.length) continue;
       const when = c.scenarios.some((l) => /^-\s+(WHEN|GIVEN)\b/.test(l));
       const then = c.scenarios.some((l) => /^-\s+THEN\b/.test(l));
       if (!when || !then) {
@@ -2961,6 +3101,21 @@ export function checkContractCitations(artifacts, scan) {
     if (!contractsOf.has(spec)) contractsOf.set(spec, parseSpecContracts(spec) || []);
     const [top, step] = t.n.split("/");
     const c = contractsOf.get(spec).find((x) => x.n === top);
+    if (c && (c.removed || (step && c.removedSteps.has(step)))) {
+      // A tombstone (SPEC-001 contract 8): reported instead of unknown, with
+      // the why of the contract's latest valid marker, and no coverage.
+      const what = c.removed ? `contract ${top}` : `step ${t.n}`;
+      out.push(
+        finding(
+          "vault",
+          "warn",
+          "citation-removed",
+          `[${t.key}#${t.n}] cites ${what} of ${spec.rel}, which is removed${c.why ? `: "${c.why}"` : ""} — move the test to the rule that replaced it, or drop the token.`,
+          where,
+        ),
+      );
+      continue;
+    }
     if (!c || (step && !c.steps.has(step))) {
       out.push(
         finding("vault", "warn", "citation-unknown", `[${t.key}#${t.n}] — ${spec.rel} has no contract ${t.n}.`, where),
@@ -2992,7 +3147,8 @@ export function checkContractCitations(artifacts, scan) {
     return f;
   };
   for (const s of artifacts.filter((a) => a.kind === "spec" && String(a.fm.status || "") === "active")) {
-    const contracts = contractsOf.get(s) || parseSpecContracts(s) || [];
+    // Tombstones are not counted (SPEC-001 contract 8).
+    const contracts = (contractsOf.get(s) || parseSpecContracts(s) || []).filter((c) => !c.removed);
     if (!contracts.length) continue;
     const got = cited.get(s) || new Set();
     if (!got.size && String(s.fm.coverage || "") !== "report") {
@@ -3029,11 +3185,23 @@ export function checkContractCitations(artifacts, scan) {
 // Evidence that cites a contract (Decision 10), behind lifecycle_gates: on.
 // A token not found in the project is a warn for a story in progress or in
 // review, and for a done story that is not legacy. Free-text evidence is
-// never checked, and doctor never runs a test.
+// never checked, and doctor never runs a test. Evidence naming a removed
+// contract or step is skipped (SPEC-001 contract 8): a closed story's record
+// does not warn when a later story removes what it cited.
 export function checkEvidenceCitations(artifacts, vaultCfg, scan) {
   if (!lifecycleGatesOn(vaultCfg) || !scan || scan.status !== "ok") return [];
   const since = legacySince(vaultCfg);
   const present = new Set(scan.tokens.map((t) => `${t.key}#${t.n}`));
+  const keys = citationKeys(artifacts);
+  const contractsOf = new Map();
+  const tombstone = (key, n) => {
+    const spec = keys.get(key);
+    if (!spec) return false;
+    if (!contractsOf.has(spec)) contractsOf.set(spec, parseSpecContracts(spec) || []);
+    const [top, step] = n.split("/");
+    const c = contractsOf.get(spec).find((x) => x.n === top);
+    return Boolean(c && (c.removed || (step && c.removedSteps.has(step))));
+  };
   const evidenceRe = evidenceSuffixRe();
   const out = [];
   for (const story of artifacts.filter((a) => a.kind === "story")) {
@@ -3047,7 +3215,7 @@ export function checkEvidenceCitations(artifacts, vaultCfg, scan) {
       const at = item.text.search(evidenceRe);
       if (at === -1) continue;
       for (const t of item.text.slice(at).matchAll(citationTokenRe())) {
-        if (t[1] === CITATION_EXAMPLE_KEY || present.has(`${t[1]}#${t[2]}`)) continue;
+        if (t[1] === CITATION_EXAMPLE_KEY || present.has(`${t[1]}#${t[2]}`) || tombstone(t[1], t[2])) continue;
         out.push(
           finding(
             "vault",
@@ -3883,6 +4051,7 @@ export function runVaultChecks(
     () => checkIndexHeaders(cfg, layout),
     () => checkStoriesAndEpics(artifacts),
     () => checkSpecLinks(cfg, layout, artifacts),
+    () => checkAmendments(layout, artifacts, now),
     () => checkSpecCoverage(artifacts, vaultCfg, layout),
     () => checkSpecAcceptance(layout, artifacts, vaultCfg),
     () => checkLifecycleGates(artifacts, vaultCfg),

package/node_modules/projectstore/scripts/graph.mjs

@@ -24,6 +24,7 @@ import {
   extractLinks,
   resolveLinkTarget,
   storyMatchesEntry,
+  parseAmendmentMarkers,
   isMain,
   commandForm,
 } from "./lib.mjs";
@@ -115,6 +116,17 @@ export function buildGraph(cfg, layout, { files = null } = {}) {
         if (r.outcome === "node") addEdge(n.path, "spec-implements-adr", r.node.path);
         else addResolved(n.path, r, entry);
       }
+      // Amendment markers in the contracts section (spec contract 3, the
+      // third edge source; SPEC-001 contract 5), whatever the spec's status:
+      // a valid marker's ref resolves as a `stories:` entry does, and gives
+      // one `amends` edge story → spec per pair (dedup on the triple), or
+      // the dead or ambiguous edge its ref resolves to.
+      for (const m of parseAmendmentMarkers(n.body)) {
+        if (!m.valid) continue;
+        const r = epicsPath ? resolveStoryEntry(m.ref, index, epicsPath) : { outcome: "dead" };
+        if (r.outcome === "node") addEdge(r.node.path, "amends", n.path);
+        else addResolved(n.path, r, m.ref);
+      }
     }
     if (n.type === "story") {
       for (const entry of refsOf(n.fm, "specs")) {

package/node_modules/projectstore/scripts/lib.mjs

@@ -1885,6 +1885,112 @@ export function contractNumberAscii(n) {
   return String(n).replace(/″/g, "''").replace(/′/g, "'");
 }
 
+// Amendment markers (the ADR "An active spec is amended by a marked block
+// under the contract…", decisions 1 to 3; SPEC-001 contract 5). A marker is a
+// blockquote in the Behavioral contracts section, after a top-level contract
+// and before the next one, whose first paragraph (wrapped lines joined) reads
+//   amended YYYY-MM-DD by <ref>: <KIND> — <why>
+// `amended`, `by`, the kinds and the tombstone body are machine tokens:
+// English in every locale. The colon is `:` or `：`, the separator `—`, `–` or
+// `-`. A first paragraph that starts `amended <date> by` in any case is a
+// candidate; one that is not the grammar is an `amendment-form` warn, and so
+// is a marker before the first contract or after a REMOVED marker under the
+// same contract. A ref whose epic part is the reserved example key is
+// documentation and is skipped whole. Fences and HTML comments do not count.
+export const AMENDMENT_KINDS = Object.freeze(["ADDED", "MODIFIED", "REMOVED"]);
+export const TOMBSTONE_BODY = "Removed, see below.";
+export const AMENDMENT_GRAMMAR = "amended YYYY-MM-DD by <ref>: ADDED|MODIFIED|REMOVED — <why>";
+const AMENDMENT_CANDIDATE_RE = /^amended\s+\S+\s+by(?:\s|$)/i;
+const AMENDMENT_REF_RE = /^amended\s+\S+\s+by\s+([^\s:：]+)/i;
+const AMENDMENT_RE = /^amended (\d{4}-\d{2}-\d{2}) by ([^\s:：]+)\s*[:：]\s*(ADDED|MODIFIED|REMOVED)\s*[—–-]\s*(\S.*)$/;
+
+// The markers of one spec body, in file order. Each is
+//   { contract: "<n>" | null, index: <contract's position> | -1, line,
+//     date, ref, kind, why, form: null | "<what is wrong>", valid }
+// where `line` is 1-based in the body, and `valid` means no form warn (a date
+// or link finding does not make a marker invalid).
+export function parseAmendmentMarkers(body) {
+  const text = String(body || "");
+  const m = text.match(headingLineRe("spec_contracts"));
+  if (!m) return [];
+  const start = m.index + m[0].length;
+  const rest = text.slice(start);
+  const next = rest.search(/^## /m);
+  const sec = next === -1 ? rest : rest.slice(0, next);
+  const lineBase = text.slice(0, start).split("\n").length; // 1-based line of sec's first line
+  // Comments are blanked to their newlines, so line numbers survive.
+  const lines = sec.replace(/<!--[\s\S]*?-->/g, (c) => c.replace(/[^\n]/g, "")).split("\n");
+  const out = [];
+  let index = -1;
+  let contract = null;
+  let fenced = false;
+  let run = null;
+  const flush = () => {
+    if (!run) return;
+    const quoted = run.lines.map((l) => l.replace(/^\s*>\s?/, ""));
+    const firstPara = [];
+    for (const q of quoted) {
+      if (/^\s*$/.test(q)) break;
+      firstPara.push(q.trim());
+    }
+    const para = firstPara.join(" ").trim();
+    const at = run.line;
+    run = null;
+    if (!AMENDMENT_CANDIDATE_RE.test(para)) return;
+    const refHit = para.match(AMENDMENT_REF_RE);
+    if (refHit && refHit[1].split("/")[0] === CITATION_EXAMPLE_KEY) return;
+    const g = para.match(AMENDMENT_RE);
+    const entry = {
+      contract,
+      index,
+      line: lineBase + at,
+      date: g ? g[1] : null,
+      ref: g ? g[2] : refHit ? refHit[1] : null,
+      kind: g ? g[3] : null,
+      why: g ? g[4].trim() : null,
+      form: null,
+      valid: false,
+    };
+    if (!g) entry.form = `the first paragraph is not \`${AMENDMENT_GRAMMAR}\``;
+    else if (contract === null) entry.form = "it comes before the first contract";
+    else if (out.some((x) => x.index === index && x.valid && x.kind === "REMOVED"))
+      entry.form = `it follows a REMOVED marker under contract ${contract} (a restored rule is ADDED under a new number)`;
+    entry.valid = entry.form === null;
+    out.push(entry);
+  };
+  lines.forEach((line, i) => {
+    if (/^\s*```/.test(line)) {
+      flush();
+      fenced = !fenced;
+      return;
+    }
+    if (fenced) return;
+    const top = line.match(/^(\d+[′″']*)\.(\s|$)/);
+    if (top) {
+      flush();
+      index++;
+      contract = contractNumberAscii(top[1]);
+      return;
+    }
+    if (/^\s*>/.test(line)) {
+      if (!run) run = { line: i, lines: [] };
+      run.lines.push(line);
+      return;
+    }
+    flush();
+  });
+  flush();
+  return out;
+}
+
+// A date the calendar has (2026-02-30 is not one).
+export function isCalendarDate(s) {
+  const m = String(s || "").match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!m) return false;
+  const d = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]));
+  return d.getUTCFullYear() === +m[1] && d.getUTCMonth() === +m[2] - 1 && d.getUTCDate() === +m[3];
+}
+
 // The body footer (`*Last updated: 2026-01-01*`) is content rather than a heading,
 // but the lifecycle gates keep it in step with frontmatter `updated:`. Matching
 // accepts every registered language; the rewrite preserves the file's OWN prefix

package/node_modules/projectstore/scripts/mcp.mjs

@@ -174,11 +174,11 @@ export const TOOLS = Object.freeze({
   lineage: {
     verb: "graph",
     description:
-      "The typed ancestry and descent of one artifact: supersedes, spec-covers, spec-implements-adr, epic-contains, breadth-first to a depth (default 3).",
+      "The typed ancestry and descent of one artifact: supersedes, spec-covers, spec-implements-adr, epic-contains, amends, breadth-first to a depth (default 3).",
     inputSchema: schema(
       {
         path: str("vault-relative path of the artifact"),
-        kind: strs("only these lineage kinds (a subset of the four)"),
+        kind: strs("only these lineage kinds (a subset of the five)"),
         depth: int("how far to walk (default 3, maximum 10)"),
       },
       ["path"],

package/node_modules/projectstore/scripts/query.mjs

@@ -67,7 +67,13 @@ export const SEARCH_PER_FILE_CAP = 3;
 export const SEARCH_DEADLINE_MS = 5000;
 export const SNIPPET_CELL = 160;
 export const GRAPH_EDGE_CAP = 100;
-export const LINEAGE_KINDS = Object.freeze(["supersedes", "spec-covers", "spec-implements-adr", "epic-contains"]);
+export const LINEAGE_KINDS = Object.freeze([
+  "supersedes",
+  "spec-covers",
+  "spec-implements-adr",
+  "epic-contains",
+  "amends",
+]);
 export const LINEAGE_DEFAULT_DEPTH = 3;
 export const LINEAGE_NODE_CAP = 50;
 export const CODE_REFS_CAP = 100;
@@ -663,7 +669,7 @@ export function renderNeighbors(r) {
 }
 
 // The typed ancestry and descent of one artifact: supersedes, spec-covers,
-// spec-implements-adr and epic-contains, both directions, breadth-first,
+// spec-implements-adr, epic-contains and amends, both directions, breadth-first,
 // depth- and node-capped, cycle-safe. Body wikilinks are deliberately not
 // lineage — walking them returns most of the vault, so `kinds` is validated
 // against LINEAGE_KINDS — and containment is not walked from an epic down to

package/node_modules/projectstore/scripts/tokens.mjs

@@ -24,9 +24,10 @@
 //     false "1 call/turn" for every turn (each record holds ≤1 tool_use).
 //
 // COST is computed at current API list prices (PRICING below) with the cache
-// multipliers: read 0.1× input, 5m write 1.25×, 1h write 2× (the usage records
-// carry the 5m/1h split). Under a subscription plan these dollars are a proxy
-// for rate-limit consumption, not an invoice — the RATIOS hold either way.
+// multipliers: read 0.1× input unless the model has its own read rate, 5m
+// write 1.25×, 1h write 2× (the usage records carry the 5m/1h split). Under
+// a subscription plan these dollars are a proxy for rate-limit consumption,
+// not an invoice — the RATIOS hold either way.
 // Historical price changes are not modeled; everything is priced at today's
 // list. Unknown models are priced at 0 and reported.
 //
@@ -94,28 +95,36 @@ const STAGE_OF = {
 };
 const STAGE_ORDER = ["authoring", "critique", "planning", "code-review", "curation", "upkeep", "other"];
 
-// USD per MTok [input, output], API list prices as of 2026-08-04 (Fable 5.1 added 2026-09-02)
-// (platform.claude.com pricing docs). Cache multipliers applied on top of
-// the input rate.
+// USD per MTok [input, output, cache read?], API list prices as of 2026-11-10
+// (platform.claude.com pricing docs). The third value is the cache-read rate
+// where it is not 0.1× input (Fable 5.1 and 5.2: 0.025×; Opus 5.5 and
+// Sonnet 5.5: 0.05×); writes stay 1.25× / 2× input. The `--json` output
+// carries these arrays as they are, with two or three values.
 export const PRICING = {
-  "claude-fable-5-1": [10, 50],
+  "claude-fable-5-2": [8, 40, 0.2],
+  "claude-fable-5-1": [10, 50, 0.25],
   "claude-fable-5": [10, 50],
+  "claude-opus-5-5": [4, 20, 0.2],
   "claude-opus-5": [5, 25],
   "claude-opus-4-8": [5, 25],
   "claude-opus-4-7": [5, 25],
-  "claude-sonnet-5": [2, 10], // intro pricing through 2026-08-31; sticker is [3, 15]
+  "claude-sonnet-5-5": [2, 10, 0.1],
+  "claude-sonnet-5": [2, 10],
   "claude-sonnet-4-6": [3, 15],
+  // reads at the default 0.1× ($0.01); prompts up to 100K, beyond [0.5, 2.5] (not modeled)
+  "claude-haiku-5-5": [0.1, 0.5],
   "claude-haiku-4-5": [1, 5],
 };
 
 // Transcripts carry variant ids ("claude-haiku-4-5-20251001", "opus",
 // "claude-opus-5[1m]") — normalize before the PRICING lookup so they don't
-// silently price at $0.
+// silently price at $0. A bare alias names the newest model of its line, so
+// an old record written as "haiku" prices at today's Haiku, not the one that ran.
 const MODEL_ALIASES = {
-  fable: "claude-fable-5-1",
-  opus: "claude-opus-5",
-  sonnet: "claude-sonnet-5",
-  haiku: "claude-haiku-4-5",
+  fable: "claude-fable-5-2",
+  opus: "claude-opus-5-5",
+  sonnet: "claude-sonnet-5-5",
+  haiku: "claude-haiku-5-5",
 };
 
 export function normModel(model) {
@@ -126,9 +135,9 @@ export function normModel(model) {
 export function rowCost(row) {
   const p = PRICING[normModel(row.model)];
   if (!p) return 0;
-  const [inP, outP] = p;
+  const [inP, outP, readP = 0.1 * inP] = p;
   return (
-    (row.input * inP + row.cw5m * 1.25 * inP + row.cw1h * 2 * inP + row.cacheRead * 0.1 * inP + row.output * outP) / 1e6
+    (row.input * inP + row.cw5m * 1.25 * inP + row.cw1h * 2 * inP + row.cacheRead * readP + row.output * outP) / 1e6
   );
 }
 
@@ -359,7 +368,7 @@ const n = (v) => v.toLocaleString("en-US");
 
 // `t/turn` — avg distinct tool calls per tool-using turn (batching level; 1.0
 // means fully sequential). `cost` — USD at current list prices; cache reads
-// bill at 0.1× input, so token counts and dollars rank differently.
+// bill at a small fraction of input, so token counts and dollars rank differently.
 const usd = (v) => `$${v.toFixed(2)}`;
 
 function table(groups, label, { runs = false } = {}) {

package/node_modules/projectstore/scripts/verbs.mjs

@@ -380,7 +380,7 @@ export const VERBS = Object.freeze([
     requiresBinding: true,
     mcp: Object.freeze(["neighbors", "lineage"]),
     options: [
-      opt("kind", "<edge-kind>", "only edges of this kind (lineage: one of its four)", true),
+      opt("kind", "<edge-kind>", "only edges of this kind (lineage: one of its five)", true),
       opt("direction", DIRECTIONS.join("|"), "neighbors: which edges"),
       opt("depth", "<n>", `lineage: how far (default ${LINEAGE_DEFAULT_DEPTH})`),
       opt("limit", "<n>", `neighbors: cap per direction (at most ${GRAPH_EDGE_CAP})`),

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

@@ -42,7 +42,11 @@ Stories — eine Story ist erst fertig, wenn beides grün ist (ADR-007).
        (verified: live)   oder   (verified: manual)
      Ein Test zitiert einen Vertrag als [example#1]: id oder alias der Spec, dann
      die Vertragsnummer. Das Frontmatter kann `alias: <kurzer-schlüssel>` und
-     `coverage: report` ergänzen. Siehe docs/contracts-and-tests.md. -->
+     `coverage: report` ergänzen. Siehe docs/contracts-and-tests.md.
+     Eine spätere Änderung schreibt den Text des Vertrags neu und setzt darunter
+     eine Markierung (ADDED, MODIFIED oder REMOVED; ein entfernter Vertrag behält
+     Nummer und Überschrift, sein Text wird "Removed, see below."):
+       > amended YYYY-MM-DD by EPIC-ID/story-id: MODIFIED — <why> -->
 
 1.
 2.

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

@@ -41,7 +41,11 @@ Spec acceptance is **additive** to the covered stories' own acceptance criteria
        (verified: live)   or   (verified: manual)
      A test cites a contract as [example#1]: the spec's id or alias, then the
      contract number. Frontmatter may add `alias: <short-key>` and
-     `coverage: report`. See docs/contracts-and-tests.md. -->
+     `coverage: report`. See docs/contracts-and-tests.md.
+     A later change to a contract rewrites its body and puts a marker under it
+     (ADDED, MODIFIED or REMOVED; a removed contract keeps its number and its
+     heading, and its body becomes "Removed, see below."):
+       > amended YYYY-MM-DD by EPIC-ID/story-id: MODIFIED — <why> -->
 
 1.
 2.

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

@@ -42,7 +42,11 @@ cubiertas: una historia se cierra cuando ambos están en verde (ADR-007).
        (verified: live)   o   (verified: manual)
      Una prueba cita un contrato así: [example#1] — el id o alias de la spec y
      el número del contrato. El frontmatter puede añadir `alias: <clave-corta>`
-     y `coverage: report`. Ver docs/contracts-and-tests.md. -->
+     y `coverage: report`. Ver docs/contracts-and-tests.md.
+     Un cambio posterior reescribe el texto del contrato y pone una marca debajo
+     (ADDED, MODIFIED o REMOVED; un contrato eliminado conserva su número y su
+     título, y su texto pasa a ser "Removed, see below."):
+       > amended YYYY-MM-DD by EPIC-ID/story-id: MODIFIED — <why> -->
 
 1.
 2.

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

@@ -42,7 +42,11 @@ couvertes : une story n'est finie que si les deux sont au vert (ADR-007).
        (verified: live)   ou   (verified: manual)
      Un test cite un contrat ainsi : [example#1] — l'id ou l'alias de la spec,
      puis le numéro du contrat. Le frontmatter peut ajouter `alias: <clé-courte>`
-     et `coverage: report`. Voir docs/contracts-and-tests.md. -->
+     et `coverage: report`. Voir docs/contracts-and-tests.md.
+     Une modification ultérieure réécrit le texte du contrat et place une marque
+     dessous (ADDED, MODIFIED ou REMOVED ; un contrat supprimé garde son numéro et
+     son titre, et son texte devient "Removed, see below.") :
+       > amended YYYY-MM-DD by EPIC-ID/story-id: MODIFIED — <why> -->
 
 1.
 2.

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

@@ -41,7 +41,11 @@ reviewed_at: null
        (verified: live)   или   (verified: manual)
      Тест ссылается на контракт так: [example#1] — id или alias спеки и номер
      контракта. Во frontmatter можно добавить `alias: <короткий-ключ>` и
-     `coverage: report`. Подробнее: docs/contracts-and-tests.md. -->
+     `coverage: report`. Подробнее: docs/contracts-and-tests.md.
+     Поздняя правка контракта переписывает его текст и ставит под ним метку
+     (ADDED, MODIFIED или REMOVED; удалённый контракт сохраняет номер и
+     заголовок, а текст становится "Removed, see below."):
+       > amended YYYY-MM-DD by EPIC-ID/story-id: MODIFIED — <why> -->
 
 1.
 2.

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

@@ -41,7 +41,11 @@ story 才算完成（ADR-007）。
        (verified: live)   或   (verified: manual)
      测试这样引用契约：[example#1]，即 spec 的 id 或 alias，加上契约编号。
      frontmatter 可以加 `alias: <短键>` 和 `coverage: report`。
-     详见 docs/contracts-and-tests.md。 -->
+     详见 docs/contracts-and-tests.md。
+     之后修改契约时，重写契约正文，并在其下方加一条标记
+     （ADDED、MODIFIED 或 REMOVED；被删除的契约保留编号和标题，
+     正文改为 "Removed, see below."）：
+       > amended YYYY-MM-DD by EPIC-ID/story-id: MODIFIED — <why> -->
 
 1.
 2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.13",
+  "version": "0.30.15",
   "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.13"
+    "projectstore": "=0.30.15"
   },
   "bundleDependencies": [
     "projectstore"