@skitterbyte/skitterspec 1.0.0 → 2.0.0

package/src/init.js

@@ -3,48 +3,51 @@
 const fs = require('fs')
 const path = require('path')
 
-const { loadConfig, SCHEMA_VERSION } = require('./config.js')
+const { ensureWorktreeDirTrusted } = require('./env/trust.js')
+const { repoInfo, expandTokens } = require('./env/resolve.js')
 
 const ASSETS = path.join(__dirname, '..', 'assets')
 
-// Shipped generator scripts, copied into the consumer's scripts/ when enabled.
-const SHARED_LIB = [
-  path.join('scripts', 'lib', 'git-commits.js'),
-  path.join('scripts', 'lib', 'config.js'),
-]
-const CHANGELOG_SCRIPT = path.join('scripts', 'generate-changelog.js')
-const RELEASES_SCRIPT = path.join('scripts', 'generate-releases.js')
-const CONFIG_FILE = 'skitterspec.config.json'
-
-const SKILLS = [
-  'spec',
-  'spec-bug',
-  'spec-ready',
-  'spec-review',
-  'spec-go',
-  'spec-complete',
-  'spec-cancel',
-  'spec-init',
-  'spec-env',
-  'spec-env-down',
-  'spec-status',
-  'spec-pull',
-  'spec-push',
-  'commit',
-]
+// Skills, rules, and specs/.core templates are discovered from the bundled assets
+// tree rather than hardcoded, so each distribution installs exactly what it ships:
+// the tracker-free base carries the neutral skill set + env.config templates; a
+// provider superset (built by composing its fragments in) additionally carries its
+// sync skills and provider config templates, and they install with no code change.
+function listSkills() {
+  const dir = path.join(ASSETS, 'skills')
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+    .map((e) => e.name)
+    .sort()
+}
+
+function listRules() {
+  return fs
+    .readdirSync(path.join(ASSETS, 'rules'))
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+}
+
+// Templates scaffolded into specs/.core/ (the *.example configs + their *.md docs).
+// A consumer copies an example → live config to adopt the matching feature.
+function listCoreTemplates() {
+  return fs
+    .readdirSync(path.join(ASSETS, 'core'))
+    .filter((f) => f.endsWith('.example') || f.endsWith('.md'))
+    .sort()
+    .map((f) => path.join('core', f))
+}
+
+const SKILLS = listSkills()
 
-const RULES = ['spec-planning.md', 'commit-messages.md']
+const RULES = listRules()
 
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
 
-// Opt-in per-spec isolation config, scaffolded into specs/.core/ as templates
-// the consumer copies (env.config.json.example → env.config.json to adopt).
-const CORE_FILES = [
-  path.join('core', 'env.config.json.example'),
-  path.join('core', 'env.config.md'),
-  path.join('core', 'linear.config.json.example'),
-  path.join('core', 'linear.config.md'),
-]
+// Opt-in config templates, scaffolded into specs/.core/ (the base ships the
+// env.config isolation templates; a provider superset also ships its own).
+const CORE_FILES = listCoreTemplates()
 
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
@@ -171,6 +174,44 @@ function installIsolation(dir, { enabled }, opts) {
     path.join(dir, 'specs', '.core', 'env.config.json'),
     opts,
   )
+  trustWorktreeRoot(dir)
+}
+
+// Seed the absolute worktree root into .claude/settings.local.json (gitignored)
+// so the operator enabling isolation isn't prompted on every edit into a
+// freshly-provisioned worktree. Best-effort: an unreadable config or malformed
+// settings file is reported, never fatal. `spec-env up` re-ensures this on every
+// provision, so a miss here self-heals.
+function trustWorktreeRoot(dir) {
+  let root
+  try {
+    const cfg = JSON.parse(
+      fs.readFileSync(path.join(dir, 'specs', '.core', 'env.config.json'), 'utf8'),
+    )
+    root = cfg && cfg.worktree && cfg.worktree.root
+  } catch {
+    /* fall through to the warning below */
+  }
+  if (!root) {
+    report.warnings.push('could not read worktree.root — skipped trusting the worktree dir')
+    return
+  }
+  const { repo, repoSlug } = repoInfo(dir)
+  const rootAbs = path.resolve(dir, expandTokens(root, { repo, repoSlug }))
+  const res = ensureWorktreeDirTrusted(dir, rootAbs)
+  const label = '.claude/settings.local.json (trusted worktree root)'
+  if (res.reason === 'malformed') {
+    report.warnings.push(
+      '.claude/settings.local.json is not valid JSON — did not trust the worktree' +
+        ` dir; add ${rootAbs} to permissions.additionalDirectories yourself`,
+    )
+  } else if (res.reason === 'created') {
+    report.created.push(label)
+  } else if (res.reason === 'added') {
+    report.updated.push(label)
+  } else {
+    report.skipped.push('.claude/settings.local.json (worktree root already trusted)')
+  }
 }
 
 function installClaudeMd(dir, { mode }) {
@@ -212,130 +253,6 @@ function installClaudeMd(dir, { mode }) {
   report.updated.push('CLAUDE.md (appended spec workflow section)')
 }
 
-// --- release tooling (changelog / release notes) ---------------------------
-
-// Build a release-config object from a loaded skitterspec.config.json.
-function releaseFromConfig(cfg) {
-  return {
-    changelog: { enabled: cfg.changelog.enabled, file: cfg.changelog.file },
-    releases: {
-      enabled: cfg.releases.enabled,
-      file: cfg.releases.file,
-      productName: cfg.releases.productName,
-      scopeAreas: cfg.releases.scopeAreas,
-    },
-    versionHook: cfg.versionHook,
-  }
-}
-
-function serializeConfig(release) {
-  return (
-    JSON.stringify(
-      {
-        version: SCHEMA_VERSION,
-        changelog: release.changelog,
-        releases: release.releases,
-        versionHook: release.versionHook,
-      },
-      null,
-      2,
-    ) + '\n'
-  )
-}
-
-// Write the resolved config. The release object already folds in any existing
-// file (the CLI seeds it from loadConfig), so this is a merge, not a clobber —
-// safe to persist without --force. Unchanged content is left alone.
-function writeConfig(dir, release) {
-  const target = path.join(dir, CONFIG_FILE)
-  const content = serializeConfig(release)
-  const exists = fs.existsSync(target)
-  if (exists && fs.readFileSync(target, 'utf8') === content) {
-    report.skipped.push(CONFIG_FILE)
-    return
-  }
-  fs.writeFileSync(target, content)
-  report[exists ? 'updated' : 'created'].push(CONFIG_FILE)
-}
-
-function installScripts(dir, release, opts) {
-  if (!release.changelog.enabled && !release.releases.enabled) return
-  for (const lib of SHARED_LIB) {
-    copyAsset(dir, lib, path.join(dir, lib), opts)
-  }
-  if (release.changelog.enabled) {
-    copyAsset(dir, CHANGELOG_SCRIPT, path.join(dir, CHANGELOG_SCRIPT), opts)
-  }
-  if (release.releases.enabled) {
-    copyAsset(dir, RELEASES_SCRIPT, path.join(dir, RELEASES_SCRIPT), opts)
-  }
-}
-
-// Idempotently add the npm scripts that drive generation at `npm version`.
-// Never overwrites a user's custom `version` script without --force.
-function wireVersionHook(dir, release, { force }) {
-  const pkgPath = path.join(dir, 'package.json')
-  if (!fs.existsSync(pkgPath)) {
-    report.skipped.push('version hook (no package.json)')
-    return
-  }
-
-  let pkg
-  try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
-  } catch {
-    report.warnings.push('package.json is not valid JSON — skipped version hook wiring')
-    return
-  }
-
-  const genCmds = []
-  const addFiles = []
-  if (release.changelog.enabled) {
-    genCmds.push('node scripts/generate-changelog.js')
-    addFiles.push(release.changelog.file)
-  }
-  if (release.releases.enabled) {
-    genCmds.push('node scripts/generate-releases.js')
-    addFiles.push(release.releases.file)
-  }
-  if (genCmds.length === 0) return
-
-  const versionCmd = [...genCmds, `git add ${addFiles.join(' ')}`].join(' && ')
-
-  const before = JSON.stringify(pkg)
-  pkg.scripts = pkg.scripts || {}
-
-  if (pkg.scripts.version && pkg.scripts.version !== versionCmd && !force) {
-    report.warnings.push(
-      'Kept your existing "version" npm script. To regenerate on release, add:\n' +
-        `      "version": "${versionCmd}"  (or re-run with --force)`,
-    )
-  } else {
-    pkg.scripts.version = versionCmd
-  }
-
-  const helpers = {}
-  if (release.changelog.enabled) {
-    helpers.changelog = 'node scripts/generate-changelog.js'
-    helpers['changelog:retro'] = 'node scripts/generate-changelog.js --retro'
-  }
-  if (release.releases.enabled) {
-    helpers.releases = 'node scripts/generate-releases.js'
-    helpers['releases:retro'] = 'node scripts/generate-releases.js --retro'
-  }
-  for (const [name, cmd] of Object.entries(helpers)) {
-    if (pkg.scripts[name] && pkg.scripts[name] !== cmd && !force) continue
-    pkg.scripts[name] = cmd
-  }
-
-  if (JSON.stringify(pkg) !== before) {
-    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
-    report.updated.push('package.json (version hook + scripts)')
-  } else {
-    report.skipped.push('package.json (version hook already present)')
-  }
-}
-
 function printReport(dir, mode) {
   const line = (label, items) => {
     if (!items.length) return
@@ -359,15 +276,14 @@ function printReport(dir, mode) {
       ' specs/.core/env.config.json.example → env.config.json) to enable it.\n'
   process.stdout.write(
     '\nDone. Skills resolve as /spec, /spec-ready, /spec-go, /spec-complete,' +
-      ' /spec-cancel, /spec-bug, /spec-init, /spec-env, /spec-env-down,' +
-      ' /spec-status, /spec-pull, /spec-push, /commit.\n' +
+      ' /spec-cancel, /spec-bug, /spec-init, /spec-env, /spec-env-down.\n' +
       'Next: tailor .claude/rules/spec-planning.md + the CLAUDE.md section to this' +
       " project's stack, then run /spec.\n" +
       isolationNote,
   )
 }
 
-async function init({ dir, force, claudeMd, mode, release, isolation }) {
+async function init({ dir, force, claudeMd, mode, isolation }) {
   if (!fs.existsSync(dir)) throw new Error(`target dir does not exist: ${dir}`)
   report.created.length = 0
   report.updated.length = 0
@@ -384,13 +300,6 @@ async function init({ dir, force, claudeMd, mode, release, isolation }) {
   if (mode !== 'update') installIsolation(dir, { enabled: isolation }, { force })
   if (claudeMd) installClaudeMd(dir, { mode })
 
-  // Release tooling. The CLI resolves `release` from flags/prompts; when called
-  // directly (e.g. tests, update) fall back to the on-disk/default config.
-  const rel = release || releaseFromConfig(loadConfig(dir))
-  if (mode !== 'update') writeConfig(dir, rel)
-  installScripts(dir, rel, { force })
-  if (mode !== 'update' && rel.versionHook) wireVersionHook(dir, rel, { force })
-
   printReport(dir, mode)
 }
 
@@ -399,5 +308,4 @@ module.exports = {
   SKILLS,
   RULES,
   SPEC_FOLDERS,
-  releaseFromConfig,
 }

package/src/prompts.js

@@ -6,12 +6,11 @@
  * non-interactive path (flags / --yes / CI) never loads this module, so the
  * test suite never imports the interactive UI.
  *
- * `seed` is the resolved release config (existing file merged with any flags),
- * used to pre-fill every answer. `isolationSeed` pre-fills the per-spec isolation
- * question. Returns `{ release, isolation }`.
+ * `isolationSeed` pre-fills the per-spec isolation question. Returns
+ * `{ isolation }`.
  */
 
-async function promptSetup({ seed, pkgExists, isolationSeed = false }) {
+async function promptSetup({ isolationSeed = false } = {}) {
   const prompts = require('prompts')
 
   let cancelled = false
@@ -23,71 +22,35 @@ async function promptSetup({ seed, pkgExists, isolationSeed = false }) {
   const questions = [
     {
       type: 'confirm',
-      name: 'changelogEnabled',
-      message: 'Generate a dev-facing CHANGELOG from commit subjects?',
-      initial: seed.changelog.enabled,
-    },
-    {
-      type: (prev) => (prev ? 'text' : null),
-      name: 'changelogFile',
-      message: 'Changelog filename',
-      initial: seed.changelog.file,
-    },
-    {
-      type: 'confirm',
-      name: 'releasesEnabled',
-      message: 'Generate user-facing release notes from Release-Note: footers?',
-      initial: seed.releases.enabled,
-    },
-    {
-      type: (_prev, values) => (values.releasesEnabled ? 'text' : null),
-      name: 'releasesFile',
-      message: 'Release-notes filename',
-      initial: seed.releases.file,
-    },
-    {
-      type: (_prev, values) => (values.releasesEnabled ? 'text' : null),
-      name: 'productName',
-      message: 'Product name (shown in the release-notes header)',
-      initial: seed.releases.productName,
+      name: 'isolation',
+      message: 'Enable per-spec isolation — a git worktree per spec?',
+      initial: isolationSeed,
     },
   ]
 
-  if (pkgExists) {
-    questions.push({
-      type: 'confirm',
-      name: 'versionHook',
-      message: 'Wire an npm "version" hook to regenerate these on release?',
-      initial: seed.versionHook,
-    })
-  }
-
-  questions.push({
-    type: 'confirm',
-    name: 'isolation',
-    message: 'Enable per-spec isolation — a git worktree per spec?',
-    initial: isolationSeed,
-  })
-
   const ans = await prompts(questions, { onCancel })
   if (cancelled) throw new Error('Setup cancelled')
 
-  return {
-    release: {
-      changelog: {
-        enabled: ans.changelogEnabled,
-        file: ans.changelogFile || seed.changelog.file,
-      },
-      releases: {
-        enabled: ans.releasesEnabled,
-        file: ans.releasesFile || seed.releases.file,
-        productName: ans.productName || seed.releases.productName,
-        scopeAreas: seed.releases.scopeAreas,
-      },
-      versionHook: pkgExists ? Boolean(ans.versionHook) : seed.versionHook,
+  return { isolation: Boolean(ans.isolation) }
+}
+
+/**
+ * Interactive confirm for removing leftover release tooling on `update`. Returns
+ * true only on an explicit yes; a cancel (Ctrl-C / Esc) resolves to false so the
+ * default is always to keep the files.
+ */
+async function confirmRemoveReleaseTooling() {
+  const prompts = require('prompts')
+  const ans = await prompts(
+    {
+      type: 'confirm',
+      name: 'remove',
+      message: 'Found release tooling (now in @skitterbyte/skittership). Remove it here?',
+      initial: false,
     },
-    isolation: Boolean(ans.isolation),
-  }
+    { onCancel: () => false },
+  )
+  return Boolean(ans.remove)
 }
 
-module.exports = { promptSetup }
+module.exports = { promptSetup, confirmRemoveReleaseTooling }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Reuben Greaves
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/assets/core/linear.config.json.example

@@ -1,39 +0,0 @@
-{
-  "linear": {
-    "teamKey": "",
-    "teamId": "",
-    "initiativeId": ""
-  },
-  "mapping": {
-    "specFolder": "project",
-    "phases": "milestone",
-    "tasks": "issue"
-  },
-  "states": {
-    "backlog": "Backlog",
-    "in-progress": "In Progress",
-    "complete": "Done",
-    "cancelled": "Cancelled"
-  },
-  "snapshot": {
-    "overviewFile": "00-overview.md"
-  },
-  "branch": {
-    "pattern": "{type}/{slug}"
-  },
-  "sync": {
-    "baseDir": "specs/.core/linear-base",
-    "backupDir": "specs/.core/linear-backups",
-    "fieldOwnership": {
-      "description": "both",
-      "milestones": "both",
-      "phaseBodies": "both",
-      "acceptanceCriteria": "both",
-      "taskBreakdown": "both",
-      "workflowState": "pull",
-      "priority": "pull",
-      "labels": "pull"
-    },
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
-  }
-}

package/assets/core/linear.config.md

@@ -1,121 +0,0 @@
-# `linear.config.json` — Linear hybrid-sync config
-
-Opt-in config for the git-like Linear sync (`/spec-status`, `/spec-pull`,
-`/spec-push`, and the Linear-aware paths of `/spec` and `/spec-go`). Linear owns
-**status and discussion**; the repo stays the **co-authoring surface for spec
-content**. Sync is bidirectional but git-like: explicit commands, a committed
-**base sidecar** for three-way merge, and no blind overwrites.
-
-**Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
-is absent the feature is simply unused — `/spec`, `/spec-go`, and the CLI's
-`spec-sync` subcommands behave exactly as they do today (local-only). Adopt it by
-copying `linear.config.json.example` → `linear.config.json` here and filling in
-your team / initiative IDs.
-
-The loader (`src/sync/config.js` → `loadLinearConfig`) merges your file over the
-frozen defaults below and returns `{ config, present }`; `present:false` means no
-live `linear.config.json` was found (the opt-in gate — it never throws on
-absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error.
-
-## Fields
-
-```jsonc
-{
-  // Which Linear team/initiative specs sync into. IDs are read by the Phase 2
-  // MCP adapter; leave blank until you connect the `linear` MCP server.
-  "linear": {
-    "teamKey": "",        // human-facing key, e.g. "ENG" (optional)
-    "teamId": "",         // Linear team UUID (create target)
-    "initiativeId": ""    // optional Initiative that groups these specs
-  },
-
-  // How a spec's parts map onto Linear objects. Defaults mirror Decision 7:
-  // spec folder → Project, phases → Milestones, tasks → Issues. `phases` may be
-  // switched to "issue" if your workspace doesn't expose project milestones.
-  "mapping": {
-    "specFolder": "project",
-    "phases": "milestone",   // "milestone" | "issue"
-    "tasks": "issue"
-  },
-
-  // Map the spec's lifecycle bucket → the Linear workflow-state name. Used when
-  // translating workflowState across the boundary (Linear owns status → `pull`).
-  "states": {
-    "backlog": "Backlog",
-    "in-progress": "In Progress",
-    "complete": "Done",
-    "cancelled": "Cancelled"
-  },
-
-  // The spec's entry-point file the local snapshot + frontmatter live in.
-  "snapshot": {
-    "overviewFile": "00-overview.md"
-  },
-
-  // Git branch name derived for a linked spec. Tokens: {type}, {slug},
-  // {identifier} (the Linear issue/project identifier, e.g. ENG-123). Shared
-  // with the isolation engine's branch derivation (src/env/resolve.js).
-  "branch": {
-    "pattern": "{type}/{slug}"
-  },
-
-  // The three-way merge engine's on-disk state.
-  "sync": {
-    // Committed base sidecar dir: the last-synced snapshot per spec, as
-    // {baseDir}/{identifier}.base.json. Committed so each worktree carries its
-    // own base and the divergence check stays accurate.
-    "baseDir": "specs/.core/linear-base",
-
-    // Backup-before-force lands the about-to-be-clobbered side here (the
-    // reflog). --force never destroys without first writing a copy.
-    "backupDir": "specs/.core/linear-backups",
-
-    // Per-field sync direction — collapses which fields can ever conflict:
-    //   "both" — co-authored: push + pull, may conflict (both moved off base).
-    //   "pull" — Linear→local only (e.g. status/priority); a local edit never
-    //            pushes and a conflict resolves to remote-wins.
-    //   "push" — local→Linear only; a remote edit never pulls and a conflict
-    //            resolves to local-wins.
-    // Any field key you add here joins the compared field set; a value outside
-    // both|pull|push is rejected at load time.
-    "fieldOwnership": {
-      "description": "both",
-      "milestones": "both",
-      "phaseBodies": "both",
-      "acceptanceCriteria": "both",
-      "taskBreakdown": "both",
-      "workflowState": "pull",
-      "priority": "pull",
-      "labels": "pull"
-    },
-
-    // Markdown sections of 00-overview.md that are local-only scaffolding and
-    // are stripped from the pushed `description` (never sent to Linear).
-    "localOnlySections": ["State log", "Changelog", "Open questions"]
-  }
-}
-```
-
-## Field ownership & conflicts
-
-The spec is a set of structured fields, most written by only one side. Marking a
-field's owner collapses which fields can genuinely conflict:
-
-- A `pull` field (Linear owns it) never reports as **pushable** — a stray local
-  edit is informational and gets reverted on the next pull.
-- A `push` field (the repo owns it) never reports as **pullable**.
-- Only a `both` field where **both** sides moved off the committed base is a real
-  `conflict` — `/spec-push` / `/spec-pull` refuse it unless `--force` (which
-  backs up the losing side into `sync.backupDir` first).
-
-After any successful pull/push/force the engine **rewrites the base** so the next
-three-way compare starts clean.
-
-## What to commit
-
-- **`sync.baseDir`** (default `specs/.core/linear-base/`) — **commit it.** The base
-  sidecar is the last-synced snapshot the three-way merge compares against; each
-  worktree carries its own base, so it must travel with the branch.
-- **`sync.backupDir`** (default `specs/.core/linear-backups/`) — **gitignore it.**
-  These are `--force` recovery copies (a local reflog), per-machine and not shared.
-  Add `specs/.core/linear-backups/` to your `.gitignore`.

package/assets/rules/commit-messages.md

@@ -1,85 +0,0 @@
-# Commit Messages
-
-## Format
-
-`type(scope): subject` — [Conventional Commits](https://www.conventionalcommits.org/)
-
-## Length limits
-
-- **Subject line:** 50 characters max
-- **Body lines:** 72 characters max
-
-(These match the common commitlint defaults — if your project runs commitlint,
-they'll be enforced; otherwise treat them as the convention.)
-
-## Template
-
-```
-type(scope): subject
-
-- Bullet point 1
-- Bullet point 2
-```
-
-## Types
-
-`feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`
-
-## Rules
-
-- Start bullets with a verb (Add, Fix, Refactor, Remove, Update)
-- Be specific about what changed (file, module, feature)
-- No emojis, no trailing punctuation
-- No **authorship** trailers — `Co-authored-by`, `Signed-off-by`, etc.
-  (The `Release-Note:` footers below are the one permitted exception — they
-  carry content, not attribution.)
-- Use plain `git commit -m "message"` only
-- Output ONLY the commit message — no explanations before or after
-
-## Release notes footer (user-facing changes)
-
-When a change is **user-visible** (a feature, fix, or improvement an end user
-would notice), add a `Release-Note:` footer. The terse subject feeds the
-dev-facing changelog (`CHANGELOG.md` by default); the footer feeds the
-user-facing release notes (`RELEASES.md` by default) via
-`scripts/generate-releases.js`, run at `npm version`. Both are generated from
-the same commit. Filenames, the product name, and the scope→area map are
-configured in `skitterspec.config.json` (this whole section applies only when
-the release tooling is installed — see the project README).
-
-```
-feat(tasks): explicit state/created dates + sort-by
-
-- Add stateEnteredAt column, sortBy param
-
-Release-Note: You can now sort your task inbox by when an item entered its
-current state or when it was created, with both dates shown on every row.
-```
-
-Grammar:
-
-- `Release-Note: <text>` — a plain-English, benefit-framed sentence aimed at
-  users (not "add column X" — say what they can now do). Multi-line is fine;
-  wrap continuation lines at 72 like the body.
-- `Release-Note!: <text>` — same, but also promoted into the release's
-  **Highlights** line. Use for the headline change of a release.
-- `Release-Area: <name>` — optional. Overrides the scope→area mapping (from
-  `skitterspec.config.json` → `releases.scopeAreas`) when the dev scope isn't a
-  user area (e.g. scope `engine` but area `Platform`).
-- `Release-Note: none` — explicit "not user-facing" marker (same effect as
-  omitting it; documents the decision).
-
-Rules:
-
-- **Opt-in.** Omit the footer for internal/dev-only changes (`chore`, `test`,
-  `docs`, `style`, refactors with no user effect, plumbing). Only commits with a
-  footer appear in `RELEASES.md`.
-- Put a **blank line before** the footer (so it's a proper commit footer).
-- `feat`→New, `fix`→Fixed, `perf`/`refactor`→Improved, breaking→Action required
-  — the bucket is derived from the commit type, so just write the note.
-
-## Abbreviations
-
-Common short forms are fine in subjects — e.g. `config`, `ctx`, `impl`, `util`,
-`id`, `repo`. List any project-specific abbreviations your team allows in your
-own `.claude/rules/`.