@seanmars/tospec 0.13.0 → 0.14.0

package/dist/utils/spec-files.js

@@ -0,0 +1,44 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+/**
+ * Every `spec.md` under a change's `specs/` directory, at any depth.
+ *
+ * Deliberately recursive even though the supported layout is exactly
+ * `specs/<capability>/spec.md`: the merge path reads one level, so anything
+ * deeper is a file that would be applied by nobody. Finding it is what lets the
+ * validator report it and archive refuse — the original defect was that the
+ * merge path and the discovery path each answered "is there a delta spec here"
+ * on their own, and disagreed silently.
+ *
+ * Shared so that answer has exactly one definition. See
+ * tospec/decisions/20260730_014309-delta-spec-layout-one-level.md
+ *
+ * Returns absolute paths, sorted by code point for deterministic issue ordering
+ * (not localeCompare — that follows the process ICU locale and would order
+ * differently on CI than locally).
+ */
+export async function findSpecFiles(specsDir) {
+    const results = [];
+    const walk = async (dir) => {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            // A missing or unreadable specs/ means "no delta specs" to every caller.
+            return;
+        }
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile() && entry.name === 'spec.md') {
+                results.push(full);
+            }
+        }
+    };
+    await walk(specsDir);
+    return results.sort();
+}
+//# sourceMappingURL=spec-files.js.map

package/dist/utils/spec-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-files.js","sourceRoot":"","sources":["../../src/utils/spec-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAgB;IAClD,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,MAAM,IAAI,GAAG,KAAK,EAAE,GAAW,EAAiB,EAAE;QAChD,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,yEAAyE;YACzE,OAAO;QACT,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBACtD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrB,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@seanmars/tospec",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Spec-driven development CLI for structured requirements and issue workflows",
   "license": "MIT",
+  "homepage": "https://github.com/seanmars/tospec#readme",
+  "bugs": {
+    "url": "https://github.com/seanmars/tospec/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seanmars/tospec.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -26,7 +34,8 @@
     "dist",
     "bin",
     "schemas",
-    "assets"
+    "assets",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=22.22.0"

package/schemas/issue/schema.yaml

@@ -19,15 +19,18 @@ artifacts:
     validation:
       requiredSections: [Feedback Loop, Root Cause, Fix Plan, Test Plan, Tasks]
   - id: specs
-    generates: specs/**/*.md
+    # Exactly one directory level — same constraint as sdd. See
+    # tospec/decisions/20260730_014309-delta-spec-layout-one-level.md
+    generates: specs/*/spec.md
     description: Optional behavior-changing delta specifications
     template: spec.md
     requires: []
     optional: true
     instruction: |
       Write delta specs only when the fix changes externally observable behavior
-      (same grammar as sdd). If the bug stems from a wrong spec, fix that
-      Requirement with MODIFIED.
+      (same grammar as sdd, same layout: specs/<capability>/spec.md, exactly one
+      directory level). If the bug stems from a wrong spec, fix that Requirement
+      with MODIFIED.
 apply:
   requires: [task]
   tracks: task.md

package/schemas/sdd/schema.yaml

@@ -15,17 +15,25 @@ artifacts:
       add/modify/remove), Capabilities (New/Modified capabilities and their specs),
       Impact (affected code/APIs/dependencies/systems). This is what specs and
       design expand from; never write file paths or code snippets (they go stale).
+      If the change has no externally observable effect at all (tooling, CI,
+      docs), say so in Impact and set `skip_specs: true` in the change's
+      .tospec.yaml — see the specs artifact below.
     validation:
       requiredSections: [Why, What Changes, Impact]
       minSectionLength:
         Why: 50
   - id: specs
-    generates: specs/**/*.md
+    # Exactly one directory level. A deeper path (specs/<area>/<capability>/spec.md)
+    # is rejected by the validator: archive's merge only reads one level, so a nested
+    # file would validate clean and then vanish on archive. See
+    # tospec/decisions/20260730_014309-delta-spec-layout-one-level.md
+    generates: specs/*/spec.md
     description: Delta specifications for affected capabilities
     template: spec.md
     requires: [proposal]
     instruction: |
-      Write delta specs from the proposal. One file per capability.
+      Write delta specs from the proposal. One file per capability, at
+      specs/<capability>/spec.md — exactly one directory level, never nested.
       Grammar: ## ADDED|MODIFIED|REMOVED|RENAMED Requirements /
       ### Requirement: <name> (the body must contain SHALL or MUST) /
       #### Scenario: <name> (four #, WHEN/THEN/AND bullets).
@@ -34,6 +42,11 @@ artifacts:
       capability exists); archive carries it into the newly created main spec. Do
       not add Purpose to an existing capability's delta (edit the main spec's
       Purpose directly instead).
+      A change with genuinely no behavioral effect (infrastructure, tooling,
+      doc-only) writes no delta and declares `skip_specs: true` in its
+      .tospec.yaml instead. Use it only when that is actually true — never
+      invent a Requirement to get past validation, and never set the marker on a
+      change that does have delta specs (validation rejects that contradiction).
   - id: design
     generates: design.md
     description: Technical design and testing seams

package/dist/core/templates/workflows/reconcile.d.ts

@@ -1,14 +0,0 @@
-/**
- * Skill Template Workflow Modules
- *
- * This file is generated by splitting the legacy monolithic
- * templates file into workflow-focused modules.
- *
- * reconcile is a standalone skill again. The archive workflow proactively
- * decides whether a reconcile is warranted and asks the user before archiving;
- * when the user agrees, this is the procedure that runs.
- */
-import type { SkillTemplate, CommandTemplate } from '../types.js';
-export declare function getTospecReconcileSkillTemplate(): SkillTemplate;
-export declare function getTospecReconcileCommandTemplate(): CommandTemplate;
-//# sourceMappingURL=reconcile.d.ts.map

package/dist/core/templates/workflows/reconcile.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../../src/core/templates/workflows/reconcile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAoElE,wBAAgB,+BAA+B,IAAI,aAAa,CAc/D;AAED,wBAAgB,iCAAiC,IAAI,eAAe,CAYnE"}

package/dist/core/templates/workflows/reconcile.js

@@ -1,94 +0,0 @@
-const RECONCILE_BODY = `Whether a spec still matches the source code is a semantic judgment no CLI can make — that's why this is agent work, not a \`tospec\` subcommand. The CLI's job is the part that IS machine-checkable: the reconciled spec must still pass full validation, and \`tospec archive --require-reconcile\` refuses unless \`reconcile-report.md\` reports PASS.
-
-**Steps**
-
-1. **List the Requirements this change touches**
-
-   For sdd: every Requirement in \`specs/<capability>/spec.md\` under the change directory. For issue: the Requirement(s) referenced in the ticket/\`task.md\`, plus any delta specs the change produced.
-
-   **No-delta case**: an issue fix with no behavior change has no delta specs at all. Don't invent Requirements to check — instead confirm \`task.md\`'s described fix matches what the code actually does, and note this as the no-delta case in the report (see format below).
-
-2. **Compare each Requirement against the actual implementation**
-
-   For each Requirement, locate the corresponding code (the files apply touched are a good starting point) and judge: does the implemented behavior match what the Requirement's scenarios describe?
-
-   **Can't find any corresponding implementation at all**: that's a CODE-BUG, same severity as a behavioral mismatch — the Requirement was agreed to and never built. Don't wave it through as MATCH.
-
-3. **Sweep the other direction — behavior nobody asked for**
-
-   Step 2 walks Requirements to code, so it can only find what is *missing*. It cannot see the opposite: behavior in the diff that **maps to no Requirement** at all. Walk the change's diff once and flag anything the specs never asked for.
-
-   **Report it, never spec it.** "Code wins" settles how a Requirement is *worded*, not whether behavior *belongs* — it is not a licence to make unrequested work look agreed after the fact. Never add a Requirement to cover scope creep: tell the user what you found and let them decide to keep it, drop it, or plan it properly.
-
-4. **Resolve every mismatch — code wins**
-
-   - If the spec is stale relative to the code (the code is correct, the spec described the old behavior): update the delta spec's Requirement with **MODIFIED**, pasting the complete, corrected Requirement block. Then:
-     \`\`\`bash
-     tospec validate "<name>" --json
-     \`\`\`
-     Must pass before moving to the next Requirement — record the validate result in that Requirement's report entry.
-   - If the code itself is wrong (it doesn't do what was actually agreed in ticket/design, or is missing entirely): **stop**. Do not touch the spec to paper over a bug. Report the mismatch to the user and suggest returning to \`tospec-apply\` to fix the code before archiving.
-
-5. **Write the reconcile report**
-
-   Create \`reconcile-report.md\` in the change directory in exactly this format — \`tospec archive --require-reconcile\` parses the first \`Conclusion:\` line, so the heading and label text must match:
-
-   \`\`\`markdown
-   # Reconcile Report: <change-name>
-   ## Summary
-   Conclusion: <PASS or FAIL>
-   ## Requirements
-   ### <Requirement name>
-   - Implementation: <module/function description, not a hard path>
-   - Verdict: MATCH | SPEC-UPDATED (updated to match code) | CODE-BUG (stops archiving)
-   - Notes: <the difference and how it was handled; SPEC-UPDATED must include the validate result>
-   \`\`\`
-
-   Fill the \`Conclusion:\` line with exactly one literal — \`Conclusion: PASS\` or \`Conclusion: FAIL\` (FAIL may append a \`(reason)\` note); never leave both options in one line, or \`tospec archive --require-reconcile\` can't parse it. \`Conclusion:\` is **FAIL** if even one Requirement is CODE-BUG — a single unresolved defect blocks the whole change, not just that Requirement. It's **PASS** only when every Requirement resolved to MATCH or SPEC-UPDATED (with validate passing). For the no-delta case, still emit the Summary and a single Requirements entry describing the task.md-vs-code comparison (module described, not a Requirement name).
-
-6. **Final artifact validation**
-   \`\`\`bash
-   tospec validate "<name>" --json
-   \`\`\`
-   Even when no spec needed updating, run the full change validation before finishing. If it reports an artifact problem, fix the affected artifact and re-run until it passes. Do not write \`Conclusion: PASS\` while validation is failing.
-
-**Output**
-
-Summarize how many Requirements matched, how many specs were updated, whether anything was flagged as a code defect, and anything found that no Requirement asked for. If \`Conclusion: PASS\`, prompt: "Run \`tospec-archive\` to finish up — it passes \`--require-reconcile\` for free now that \`reconcile-report.md\` reports PASS." If \`Conclusion: FAIL\`, prompt to return to \`tospec-apply\` first — do not proceed to archive.
-
-**Guardrails**
-- Code is the source of truth for behavior — spec updates always follow code, never the other way around
-- Scope creep is reported, never specced — "code wins" settles a Requirement's wording, never whether unrequested behavior belongs
-- Never edit source code from this workflow — a code-side mismatch is diagnosis, not a license to patch here
-- Every MODIFIED delta must re-pass \`tospec validate\` before moving to the next Requirement
-- \`reconcile-report.md\` is required output, in the exact format above — \`tospec archive --require-reconcile\` depends on both its existence and its \`Conclusion:\` line
-- One comparison pass per Requirement — check it against the code once and record the verdict. \`reconcile-report.md\` is the deliverable, not another review target: don't re-audit the report after writing it, and don't re-check a Requirement already judged MATCH`;
-export function getTospecReconcileSkillTemplate() {
-    return {
-        name: 'tospec-reconcile',
-        description: 'Reconcile a change\'s Requirements against the actual implementation — code wins on any mismatch — and write reconcile-report.md. Use before archiving a change whose specs may have drifted from the code.',
-        instructions: `Reconcile \`specs/\` against the implementation for every Requirement this change touched — code wins on any mismatch. Run this before \`tospec-archive\` when the change's specs may have drifted from the code.
-
-**Input**: The user's request should name the change to reconcile.
-
-${RECONCILE_BODY}`,
-        license: 'MIT',
-        compatibility: 'Requires tospec CLI.',
-        metadata: { author: 'tospec' },
-        allowedTools: ['Bash(tospec:*)', 'Read', 'Write', 'Edit', 'Grep', 'Glob'],
-    };
-}
-export function getTospecReconcileCommandTemplate() {
-    return {
-        name: 'TOSPEC: Reconcile',
-        description: 'Reconcile specs against the implementation, code as source of truth',
-        category: 'Workflow',
-        tags: ['workflow', 'reconcile', 'archive-gate'],
-        content: `Reconcile \`specs/\` against the implementation for every Requirement this change touched — code wins on any mismatch. Run this before \`tospec-archive\` when the change's specs may have drifted from the code.
-
-**Input**: The argument after \`tospec-reconcile\` is the change name to reconcile.
-
-${RECONCILE_BODY}`,
-    };
-}
-//# sourceMappingURL=reconcile.js.map

package/dist/core/templates/workflows/reconcile.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../../../../src/core/templates/workflows/reconcile.ts"],"names":[],"mappings":"AAYA,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wQAgEiP,CAAC;AAEzQ,MAAM,UAAU,+BAA+B;IAC7C,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE,6MAA6M;QAC1N,YAAY,EAAE;;;;EAIhB,cAAc,EAAE;QACd,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,sBAAsB;QACrC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9B,YAAY,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iCAAiC;IAC/C,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,WAAW,EAAE,qEAAqE;QAClF,QAAQ,EAAE,UAAU;QACpB,IAAI,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,cAAc,CAAC;QAC/C,OAAO,EAAE;;;;EAIX,cAAc,EAAE;KACf,CAAC;AACJ,CAAC"}