@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/assets/core/gating.config.md

@@ -0,0 +1,81 @@
+# `gating.config.json` — release-gating config
+
+Opt-in config for **release gating**: whether each spec records a decision about
+shipping behind a feature flag.
+
+The problem it solves is not "we forgot to use a flag" — it is that
+**nobody can tell whether the question was asked**. A spec can go from `/spec`
+through
+implementation to `/spec-complete` with no flag and no mention of one, and that
+is indistinguishable from "we considered it and decided against". Prose guidance
+in a project rule has already been shown not to close that gap; a required header
+does, because its absence is visible.
+
+**Skitterspec bakes in the offer, never the mechanism.** How your project does
+flags — a resolver, an admin toggle, env precedence, a vendor SDK — is none of
+its business, and it never reads your flag code. It asks the question, cites your
+own documentation, and records the answer.
+
+**Adopt it** by copying `gating.config.json.example` → `gating.config.json` here
+(or `skitterspec init --gating`). While this file is absent the feature is
+entirely unused: no grill question, no header, nothing to check — which is read
+as "this project does not use feature flags".
+
+## Fields
+
+```jsonc
+{
+  // Where THIS project documents how its flags work — a repo-relative path,
+  // cited when the question is asked so the answer is an informed one.
+  // Skitterspec never reads the file; it only names it. Empty = say nothing.
+  "guidance": ".claude/rules/feature-flags.md",
+
+  // The value written when the user declines a flag, so a project can
+  // standardise its wording. Must keep the `none: <reason>` shape — the reason
+  // half is the whole point (see below). Empty falls back to `none: <reason>`.
+  "default": "none: <reason>"
+}
+```
+
+## The header it drives
+
+With this file present, every spec `/spec`, `/spec-bug` and `/spec-hotfix` write
+carries a `Gating:` field beside `Stack:` in `00-overview.md`:
+
+```
+> **Gating:** search-ranking-v2
+> **Gating:** none: additive, nothing to revert
+```
+
+Two valid shapes, and one that is not:
+
+| Value | Meaning |
+|-------|---------|
+| a flag name | ships behind that flag |
+| `none: <reason>` | deliberately not flagged, and why |
+| *missing, empty, or a bare `none`* | **not a decision** — nobody answered |
+
+The reason half is load-bearing. `none: additive, nothing to revert` is a
+decision a reviewer can disagree with; a bare `none` is a shrug, and a missing
+line is an oversight. Distinguishing those three is the entire feature.
+
+## What it never does
+
+- **It never blocks.** `skitterspec gating check` reports and exits 0;
+  `/spec-start` and `/spec-complete` mention a missing header and carry on.
+  Nothing here can stop a spec being started, completed or landed.
+- **It never accuses an old spec.** Only `specs/backlog/` and
+  `specs/in-progress/` are read. Specs finished or abandoned before you adopted
+  gating are out of range by construction, not by a filter someone has to
+  remember.
+- **It never learns your flag system.** `guidance` is a path it prints, nothing
+  more.
+
+## Checking
+
+```
+skitterspec gating check              # the spec in flight here
+skitterspec gating check <spec>       # one named spec
+skitterspec gating check --all        # every active spec
+skitterspec gating check --json       # for tooling
+```

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

@@ -0,0 +1,18 @@
+{
+  "jira": {
+    "siteUrl": "https://your-site.atlassian.net",
+    "projectKey": "PROJ",
+    "issueType": "Task",
+    "subtaskType": "Subtask"
+  },
+  "states": {
+    "backlog": "To Do",
+    "in-progress": "In Progress",
+    "complete": "Done",
+    "cancelled": "Done"
+  },
+  "auth": {
+    "emailEnv": "JIRA_EMAIL",
+    "tokenEnv": "JIRA_API_TOKEN"
+  }
+}

package/assets/core/jira.config.md

@@ -0,0 +1,88 @@
+# `jira.config.json` — field reference
+
+The committed, shareable half of Jira sync. It holds ids, names and env-var
+NAMES — never a credential. Credentials live in the user-level store
+(`skitterspec-jira spec-sync credentials set`) or the environment.
+
+| Key | Meaning | Default |
+|-----|---------|---------|
+| `jira.siteUrl` | The Jira Cloud site (`https://<site>.atlassian.net`). Also keys the credentials-store entry. | `""` |
+| `jira.projectKey` | Where spec issues land — the identifier prefix (`PROJ-123`). Jira's project is the analogue of Linear's team; placement is decided here, once. | `""` |
+| `jira.issueType` | The issue type a spec mints as. | `"Task"` |
+| `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
+| `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
+| `states.<bucket>` | The Jira STATUS name for each lifecycle bucket. Must match the project's workflow statuses exactly; moves are applied by workflow transition, and an unreachable status refuses loudly. `cancelled` defaults to `Done` because default Jira workflows carry no Cancelled status. Pick work statuses, not pipeline stages — see **Choosing your status map** below. | see example |
+| `auth.emailEnv` / `auth.tokenEnv` | Env-var NAMES for the email + API-token pair (basic auth). | `JIRA_EMAIL` / `JIRA_API_TOKEN` |
+| `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
+| `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
+| `sync.fieldOwnership` | Which projection fields push (`description`, `subIssues`, `workflowState`, `assignee`; `"none"` declines one). | all `push` |
+| `release.ignorePaths` | Bookkeeping path prefixes `released` ignores, exactly as the Linear provider defines them. | `specs/`, changelogs |
+
+Descriptions are stored as ADF (Atlassian Document Format): the adapter
+renders markdown to ADF on push and reduces ADF back to text on read-back, so
+verification compares words, not bytes. Phase checklists render as live ADF
+task lists — still a read-only mirror: a box ticked in Jira is overwritten on
+the next push.
+
+## More than one name per bucket — read-only aliases
+
+A board usually has more states than the four buckets: "Blocked", "Next
+Sprint", "Released". A bucket's value may be an **array** instead of a string:
+
+```jsonc
+"states": {
+  "in-progress": ["Active", "Blocked"],
+  "complete": ["Closed", "Released"]
+}
+```
+
+- **The first name is the only one push writes**, and only when the spec
+  itself moves. The rest are never written.
+- **The rest are read as that bucket** wherever a listing interprets a status.
+  The array is parsed and validated like every other provider's, so one config
+  shape works across all of them. `spec-sync status` never reads a ticket's
+  status at all: skitterspec tells Jira about its own transitions and nothing
+  else.
+- **Nothing is pulled.** An alias changes what the report *says* about a
+  ticket, never the spec.
+- A plain string works exactly as before. An alias that also names another
+  bucket is refused at load. An alias the tracker lacks is reported by
+  `spec-sync states` but never blocks a push, because it is never written.
+
+## Choosing your status map
+
+Map the four buckets to **work** statuses, never to deployment stages. The
+buckets mirror the repo's work lifecycle — folder buckets for the spec, phase
+emoji for each subtask — so they translate honestly to To Do / In Progress /
+Done and never to a pipeline (On Test → On Live): the repo learns where work
+**is** as it happens, but it learns what **shipped** only when a release is
+cut, so a pipeline status driven from the spec lifecycle is wrong the moment
+it moves. The tell is the subtasks: a finished phase transitioned to `On Live`
+before anything was released is the mapping asking status to carry two
+different state machines.
+
+If your workflow encodes a deployment pipeline, three standard Jira moves keep
+the map honest:
+
+- **Give subtasks their own workflow.** A workflow *scheme* can assign the
+  subtask type a plain To Do / In Progress / Done workflow while the parent
+  type keeps the pipeline — subtasks genuinely have no delivery lifecycle, and
+  Jira lets you say so structurally.
+- **Track "which release contains this" with fix versions** — the Releases
+  hub. Your CI can fill it from `spec-sync released "<prev>..<tag>" --json`,
+  which lists the tickets a range contains from their `Refs:` trailers, each
+  with its spec and url. (Available on every plan; in the current "Spaces" UI it is not a
+  Features toggle but a **tab** — add it with `+` in the space's tab bar.)
+- **Let CI/CD integrations stamp environment position** (the deployments
+  panel), so it never needs to be a status at all.
+
+**Seeing the map is one command:** `spec-sync states` renders every bucket
+against the live project — the configured status, a verdict per row with the
+status's board category, the closest match when one is missing, and the
+one-line remap. Run it whenever the wiring feels uncertain; it changes
+nothing.
+
+Walking the parent through pipeline stages at *release* time is the host
+project's job, not skitterspec's: it writes nothing about releases or
+deployments on any provider. A leftover `release.stages` is flagged by
+`spec-sync doctor` as unused config.

package/assets/hooks/main-guard.cjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Main guard — the harness half.
+ *
+ * `main` is where work **lands**, not where it happens. The skills say so, and
+ * a skill is prose: it can be chained past, typed around, or simply not read.
+ * So the rule is also enforced one level down, where an `Edit` or a `Write` is
+ * a tool call the harness has to ask about first.
+ *
+ * IT REFUSES THE FIRST WRITE, NOT THE COMMIT, and that is the whole reason it
+ * is a different hook from `review-gate.cjs` rather than another branch inside
+ * it. Nothing has been written when this fires, so the fix costs one command —
+ * `/no-spec <name>` and carry on. A commit-time gate fires once the work
+ * already exists in the primary checkout, and in worktree mode moving it is the
+ * genuinely painful part: the primary checkout cannot `switch -c` out from
+ * under the other worktrees.
+ *
+ * THIS SCRIPT DECIDES NOTHING. It reads the tool call, hands the directory to
+ * `spec-env main check`, and turns one exit status into an answer. Every
+ * judgement — is isolation configured, is this the primary checkout, is HEAD
+ * the base branch, is an allow in force — lives in the engine, where it is unit
+ * tested. A hook with its own opinions is a second implementation that nothing
+ * can test and nobody remembers to update.
+ *
+ * IT FAILS OPEN, EVERYWHERE, for the same reasons `review-gate.cjs` does and
+ * with more at stake, because this one fires far more often. No engine, an
+ * unreadable payload, a repo with no isolation, a crash of its own — all of
+ * them allow the write. Being wrong the permissive way costs one edit on a rule
+ * the skills also carry; being wrong the other way costs someone their work
+ * with no idea why (`.claude/rules/negative-checks.md`).
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+// Let the call through, saying nothing. Exit 0 with no JSON is "no opinion" —
+// the tool proceeds exactly as if this hook did not exist, which is what the
+// overwhelming majority of invocations must do.
+function allow() {
+  process.exit(0)
+}
+
+/**
+ * Refuse, and say what to do instead.
+ *
+ * The JSON route rather than exit-2, because the reason reaches **Claude** —
+ * which is who has to act on it, by moving the work rather than by asking the
+ * user to switch the guard off. The exits are named in the refusal itself.
+ */
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }) + '\n',
+  )
+  process.exit(0)
+}
+
+function readPayload() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    // Unreadable or unparseable stdin is the cannot-tell case, not evidence.
+    return null
+  }
+}
+
+/**
+ * Where the engine is, in the order most likely to be right. Pure but for the
+ * existence check. Identical to `review-gate.cjs`'s, deliberately: a hook
+ * process does not inherit a package manager's `node_modules/.bin` on PATH, so
+ * the local install is looked for by path first — walking up from the project,
+ * because a git worktree's checkout has its own `node_modules`.
+ */
+function findEngine(projectDir) {
+  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
+  let at = projectDir
+  for (let i = 0; i < 6 && at; i++) {
+    for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
+      const candidate = path.join(at, 'node_modules', '.bin', name)
+      if (fs.existsSync(candidate)) return candidate
+    }
+    const up = path.dirname(at)
+    if (up === at) break
+    at = up
+  }
+  return 'skitterspec'
+}
+
+// The tools that write a file. A matcher is configured too, but a hook that is
+// reached some other way must still be inert rather than guessing.
+//
+// WHAT WOULD FOOL THIS: a write that does not go through a write TOOL — a shell
+// heredoc, `sed -i`, an editor outside the session. Those are left unguarded on
+// purpose. Covering them would mean parsing arbitrary shell for filesystem
+// effects, which cannot be done reliably, and the failure mode of getting it
+// wrong is refusing a command that has nothing to do with writing files. The
+// skills carry the rule for everything this matcher cannot see.
+const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
+
+// The path a write tool names: `file_path` for Edit, Write and MultiEdit,
+// `notebook_path` for NotebookEdit. Anything else is no path at all.
+function writeTarget(input) {
+  if (!input || typeof input !== 'object') return null
+  for (const key of ['file_path', 'notebook_path']) {
+    if (typeof input[key] === 'string' && input[key]) return input[key]
+  }
+  return null
+}
+
+function main() {
+  const payload = readPayload()
+  if (!payload) allow()
+
+  if (!WRITE_TOOLS.has(payload.tool_name)) allow()
+
+  // A worktree is its own checkout, and only the primary one is this guard's
+  // business. `cwd` is where the session stands; the target below is where the
+  // write lands, and the engine prefers it.
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
+  const session = typeof payload.session_id === 'string' ? payload.session_id : ''
+
+  const argv = ['spec-env', 'main', 'check', '--dir', cwd]
+  if (session) argv.push('--session', session)
+  // The FILE decides where the write lands, not the session's directory. Judged
+  // on `cwd` alone, a session on the base branch was refused its own scratchpad
+  // under /tmp, and a session in a worktree could write into the primary
+  // checkout unseen. No path in the payload → the engine judges `cwd`, as before.
+  const target = writeTarget(payload.tool_input)
+  if (target) argv.push('--path', target)
+
+  const result = spawnSync(findEngine(cwd), argv, { cwd, encoding: 'utf8', timeout: 8000 })
+
+  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
+  // process never ran or was killed, and neither is a refusal.
+  if (result.error || result.status === null) allow()
+  if (result.status !== 1) allow()
+
+  deny((result.stdout || '').trim())
+}
+
+// Guarded so the pieces above can be required and tested without the script
+// reading stdin and exiting.
+if (require.main === module) {
+  try {
+    main()
+  } catch {
+    // Even a bug in this file lets the write through.
+    allow()
+  }
+}
+
+module.exports = { findEngine, WRITE_TOOLS, writeTarget }

package/assets/hooks/review-gate.cjs

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+'use strict'
+
+/**
+ * Review gate — the harness half.
+ *
+ * `/spec-next` refuses to build the next phase while a review is owed, but a
+ * skill is prose: it can be chained past, typed around, or simply not read. So
+ * a phase ending is also enforced one level down, where a `git commit` is a
+ * tool call the harness has to ask about first.
+ *
+ * THIS SCRIPT DECIDES NOTHING. It reads the tool call, hands the command line
+ * to `spec-env review gate --check --for-command`, and turns one exit status
+ * into an answer. Every judgement — is this a commit, is a verdict owed, is
+ * this project even using the gate — lives in the engine, where it is unit
+ * tested. A hook with its own opinions is a second implementation that nothing
+ * can test and nobody remembers to update.
+ *
+ * IT FAILS OPEN, EVERYWHERE. No engine on the machine, an unreadable payload, a
+ * repo with no isolation, a spec it cannot resolve, a crash of its own — all of
+ * them allow the commit. Blocking one is an accusation
+ * (`.claude/rules/negative-checks.md`), and the only thing worth accusing on is
+ * the engine saying, positively, that this spec owes a verdict. Being wrong the
+ * other way costs one unreviewed commit, on a gate the skills also enforce;
+ * being wrong this way costs someone their commit with no idea why.
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+// Let the call through, saying nothing. Exit 0 with no JSON is "no opinion" —
+// the tool proceeds exactly as if this hook did not exist, which is what almost
+// every invocation must do.
+function allow() {
+  process.exit(0)
+}
+
+/**
+ * Refuse, and say what would clear it.
+ *
+ * The JSON route rather than exit-2, because the reason reaches **Claude** —
+ * which is who has to act on it. A commit blocked with no route onward is how a
+ * gate gets switched off wholesale instead of answered, so the three exits are
+ * named in the refusal itself.
+ */
+function deny(reason) {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    }) + '\n',
+  )
+  process.exit(0)
+}
+
+function readPayload() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8')
+    const parsed = JSON.parse(raw)
+    return parsed && typeof parsed === 'object' ? parsed : null
+  } catch {
+    // Unreadable or unparseable stdin is the cannot-tell case, not evidence.
+    return null
+  }
+}
+
+/**
+ * Where the engine is, in the order most likely to be right. Pure but for the
+ * existence check.
+ *
+ * A hook process does not inherit a package manager's `node_modules/.bin` on
+ * PATH, so the local install is looked for by path first — walking up from the
+ * project, because a git worktree's checkout has its own `node_modules`. PATH
+ * is the fallback for a global install, and `SKITTERSPEC_BIN` overrides
+ * everything for anyone whose layout is neither.
+ */
+function findEngine(projectDir) {
+  if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
+  let at = projectDir
+  for (let i = 0; i < 6 && at; i++) {
+    for (const name of ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']) {
+      const candidate = path.join(at, 'node_modules', '.bin', name)
+      if (fs.existsSync(candidate)) return candidate
+    }
+    const up = path.dirname(at)
+    if (up === at) break
+    at = up
+  }
+  return 'skitterspec'
+}
+
+function main() {
+  const payload = readPayload()
+  if (!payload) allow()
+
+  // Only Bash runs a commit. A matcher is configured too, but a hook that is
+  // reached some other way must still be inert rather than guessing.
+  if (payload.tool_name !== 'Bash') allow()
+
+  const command = payload.tool_input && payload.tool_input.command
+  if (typeof command !== 'string' || !command.trim()) allow()
+
+  // The commit's own directory decides which spec this is about — a worktree is
+  // its own checkout, and the answer differs per worktree.
+  const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
+
+  const result = spawnSync(
+    findEngine(cwd),
+    ['spec-env', 'review', 'gate', '--check', '--for-command', command, '--dir', cwd],
+    { cwd, encoding: 'utf8', timeout: 8000 },
+  )
+
+  // No engine, a crash, a timeout — all cannot-tell. `status` is null when the
+  // process never ran or was killed, and neither is a refusal.
+  if (result.error || result.status === null) allow()
+  if (result.status !== 1) allow()
+
+  deny(
+    (result.stdout || '').trim() +
+      '\n\nThis phase is waiting on a verdict. Relay these to the operator ' +
+      'rather than choosing one: press a verdict on the page, /spec-reviewed if ' +
+      'a pass is already waiting, or /spec-skip "<reason>" to move on with the ' +
+      'reason recorded.\n\nAll three are theirs to type. /spec-skip is the same ' +
+      'exit as \'skitterspec spec-env review skip "<reason>"\' — a command ' +
+      'rather than an incantation, because the long form is what nobody retypes ' +
+      'and a gate with an unreachable exit gets switched off wholesale instead ' +
+      'of answered.',
+  )
+}
+
+// Guarded so the pieces above can be required and tested without the script
+// reading stdin and exiting.
+if (require.main === module) {
+  try {
+    main()
+  } catch {
+    // Even a bug in this file lets the commit through.
+    allow()
+  }
+}
+
+module.exports = { findEngine }