@specpin/cli 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specpin/cli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Specpin sidecar CLI: init + serve the .specs/ knowledge layer for the Specpin browser extension. Installs the matching prebuilt Go binary.",
   "keywords": [
     "specpin",

package/skill/SKILL.md

@@ -61,11 +61,16 @@ c. **Write `<area>.spec.json`** (one file per page or feature). It has a `group`
      e.g. `{ "en": "Log in button" }`. `description` must be non-empty.
    - `businessRules` (optional): array of locale-keyed objects, one rule each.
    - `tags` (optional): plain string array (not localized).
+   - `links`, `verifiedBy`, `status` (all optional provenance): `links` are
+     ticket/doc/PR refs (`{label,url}`, http/https); `verifiedBy` are repo-relative
+     test paths that **declare** the spec (checked to exist, never run — only list
+     real files); `status` is `draft` | `approved` | `deprecated` (omit = neutral).
    - `preferredDisplayMode` (optional): `tooltip` | `sidebar` | `modal`
      (`overlay` and `inline-badge` are reserved and fall back to `tooltip`).
    - `fingerprint`: the element link (required). See the fingerprint reference.
    - `meta`: set `"source": "ai-generated"` for specs you author, plus
-     `createdBy`, `createdAt`, `updatedAt` (RFC3339).
+     `createdBy`, `createdAt`, `updatedAt` (RFC3339). Do NOT author
+     `reviewedAt`/`reviewedBy` — a human stamps those via Mark-reviewed.
 
    `description` and each `businessRules` item may use a small, safe Markdown
    subset (bold, italic, `[label](url)` links, and lists in `description`).

package/skill/references/cli-commands.md

@@ -40,16 +40,26 @@ Validate the corpus against the embedded schema, offline. CI-friendly.
 ```bash
 specpin validate                 # checks ./.specs
 specpin validate --dir path/to/.specs
+specpin validate --repo-root .   # root that verifiedBy paths resolve against
 specpin validate --strict-manifest
 ```
 
 - `--dir` (default `.specs`), `--strict-manifest` (turn drift warnings into failures).
+- `--repo-root` (default: the parent of `--dir`): the root each `verifiedBy` path
+  is resolved against. Set it when `.specs/` is not at `<repo>/.specs` (e.g.
+  `./config/specs`).
+- **`verifiedBy` existence check (on by default):** after schema validation, each
+  spec's `verifiedBy` path must exist inside the repo root — a broken-link guard,
+  NOT a test run. Absolute paths, `..`-escapes, and symlinks leaving the repo are
+  rejected. A missing path fails (exit 1) naming the spec id + path. When there is
+  no readable working tree (e.g. a piped bundle) the check is skipped with a note.
 - Output: `OK <file>` or `FAIL <file>` plus indented errors per file, then
   `N files checked, M error(s)`. Manifest/disk drift prints `warning:` lines
   (or `FAIL:` under `--strict-manifest`).
 - Exit codes:
   - `0`: all valid.
-  - `1`: schema violations or an unreadable/symlinked spec file (author fixes).
+  - `1`: schema violations, an unreadable/symlinked spec file, or a missing/escaping
+    `verifiedBy` path (author fixes).
   - `2`: could not run (missing `.specs/`, no `manifest.json`, internal error).
 
 ## bundle

package/skill/references/schema-authoring.md

@@ -27,6 +27,7 @@ to each file for editor autocomplete.
 | `settings.defaultLocale` | string | no | fallback locale |
 | `settings.locales` | string[] | no | BCP-47 locales authored |
 | `settings.matchConfidenceThreshold` | number 0-1 | no | reserved for the deferred hybrid scorer |
+| `settings.stalenessThresholdDays` | number 1-3650 | no | days after a spec's `meta.reviewedAt` before it shows as stale; default 90 |
 | `settings.defaultDisplayMode` | DisplayMode | no | fallback render mode |
 
 ## SpecFile (`<area>.spec.json`)
@@ -45,10 +46,23 @@ to each file for editor autocomplete.
 | `description` | LocalizedString | yes | locale-keyed object, each value non-empty |
 | `businessRules` | LocalizedString[] | no | one locale-keyed object per rule |
 | `tags` | string[] | no | NOT localized |
+| `links` | Link[] | no | author-declared refs (tickets/docs/PRs); ≤10; see Link below |
+| `verifiedBy` | string[] | no | repo-relative test paths that DECLARE this spec; ≤20, each ≤200 chars. Declarative only (see note) |
+| `status` | SpecStatus | no | `"draft" \| "approved" \| "deprecated"`; omit = neutral (no default) |
 | `preferredDisplayMode` | DisplayMode | no | overrides `settings.defaultDisplayMode` |
 | `fingerprint` | ElementFingerprint | yes | the element link |
 | `meta` | SpecMeta | no | provenance + timestamps |
 
+### Link
+
+`{ "label": string (1-80), "url": string }`. `url` must be `http`/`https`
+(`^https?://`). Both fields required.
+
+**`verifiedBy` is declarative.** It lists tests that *claim* to cover the spec;
+`specpin validate` checks each path **exists** in the repo (a broken-link guard),
+it does NOT run the tests or imply they pass. Only list real files. Never present
+these as "verified"/"passing" — they are "linked".
+
 ## LocalizedString
 
 A locale-keyed object, NOT a flat string:
@@ -84,6 +98,11 @@ All four required when `meta` is present: `createdBy` (string),
 `createdAt` + `updatedAt` (RFC3339 date-time, format-checked by both validators),
 `source` (`"ai-generated" | "manual"`). Use `"ai-generated"` for specs you author.
 
+Optional review fields — **do NOT author these**; a human stamps them via the
+extension's Mark-reviewed action: `reviewedAt` (RFC3339 date-time), `reviewedBy`
+(a non-PII token like `createdBy`, e.g. `"agent"`/`"manual"` — never an email or
+identity, since it is committed to `.specs/` and included in export bundles).
+
 ## DisplayMode
 
 `"overlay" | "tooltip" | "sidebar" | "modal" | "inline-badge"`. Implemented: