kataster 0.0.0-stage → 0.2.1

package/.claude/skills/feature/scripts/intake.ts

@@ -0,0 +1,356 @@
+/**
+ * Read-only intake for `/feature`.
+ *
+ * Turns a story id, a GitHub/Jira issue, a pasted URL or free text into a normalized source plus a routing hint.
+ * It never writes: no story, no mirror, no sync state. The skill decides what to do with the result.
+ *
+ *   node .claude/skills/feature/scripts/intake.ts ST-042 --json
+ *   node .claude/skills/feature/scripts/intake.ts #123 --json
+ *   node .claude/skills/feature/scripts/intake.ts PROJ-123 --from jira-issues.json --json
+ *   node .claude/skills/feature/scripts/intake.ts "customers attach photos to orders" --json
+ *
+ * Jira is reached through `mcp-atlassian`, which only the agent can call. The agent fetches the issue with MCP,
+ * writes it as JSON and passes it with `--from` – the same split the backlog sync uses.
+ */
+import { readFileSync } from "node:fs";
+import { loadBacklogConfig, type BacklogConfig } from "../../../lib/config.ts";
+import * as d from "../../../lib/discovery.ts";
+import { externalOf, type RemoteIssue } from "../../../lib/backlog.ts";
+import { readGithubIssue } from "../../../lib/backlog-github.ts";
+import { normalizeJiraIssue } from "../../../lib/backlog-jira.ts";
+
+type Route = "continue-story" | "review-story" | "implement-story" | "new-story" | "bug" | "feature";
+type SourceKind = "story" | "github" | "jira" | "text";
+
+interface Source {
+  kind: SourceKind;
+  ref: string;
+  title?: string;
+  url?: string;
+  status?: string;
+  labels: string[];
+  body?: string;
+}
+
+interface StoryRef {
+  id: string;
+  path: string;
+  title: string;
+  status: string;
+  type: string;
+}
+
+interface Intake {
+  source: Source;
+  story: StoryRef | null;
+  route: Route;
+  reason: string;
+  signals: {
+    bug: boolean;
+    scenarios: number;
+    checklistItems: number;
+    openQuestions: number;
+  };
+  warnings: string[];
+}
+
+const BUG_LABELS = new Set(["bug", "defect", "regression"]);
+const GH_URL = /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s]+)\/issues\/(\d+)(?:[?#].*)?$/i;
+const JIRA_URL = /^https?:\/\/[^/\s]+\/browse\/([A-Z][A-Z0-9_]+-\d+)(?:[?#].*)?$/i;
+
+function fail(message: string): never {
+  console.error(message);
+  process.exit(2);
+}
+
+function count(re: RegExp, text: string): number {
+  return (text.match(re) ?? []).length;
+}
+
+/** A bug is a hint for the routing, never a verdict – the grilling decides. */
+function looksLikeBug(title: string, labels: string[], issueType = ""): boolean {
+  if (labels.some((label) => BUG_LABELS.has(label.toLowerCase()))) return true;
+  if (/^bug$/i.test(issueType)) return true;
+  return /^\s*(?:\[bug\]|bug\b|fix\b)/i.test(title);
+}
+
+function findStory(id: string): d.Story | null {
+  const wanted = id.toUpperCase();
+  return d.loadStories().parsed.find((story) => d.storyId(story).toUpperCase() === wanted) ?? null;
+}
+
+function findLinked(kind: "github" | "jira", key: string): d.Story | null {
+  const wanted = kind === "github" ? key : key.toUpperCase();
+  return d.loadStories().parsed.find((story) => {
+    const ext = externalOf(story);
+    if (!ext || ext.provider !== kind) return false;
+    return (kind === "github" ? ext.key : ext.key.toUpperCase()) === wanted;
+  }) ?? null;
+}
+
+function storyRef(story: d.Story): StoryRef {
+  return {
+    id: d.storyId(story),
+    path: d.rel(story.path),
+    title: String(story.meta.title ?? ""),
+    status: String(story.meta.status ?? ""),
+    type: String(story.meta.type ?? "story"),
+  };
+}
+
+function routeFor(story: d.Story | null, bug: boolean): { route: Route; reason: string } {
+  if (story) {
+    const id = d.storyId(story);
+    switch (String(story.meta.status ?? "")) {
+      case "draft":
+        return { route: "continue-story", reason: `${id} is a draft – revise it instead of creating a parallel feature` };
+      case "review":
+        return { route: "review-story", reason: `${id} is waiting for its review – run /review-stories ${id} or revise it` };
+      case "ready":
+        return { route: "implement-story", reason: `${id} is ready – continue with /implement ${id}` };
+      case "in-progress":
+        return { route: "implement-story", reason: `${id} is in progress – continue with /implement ${id}` };
+      default: {
+        const status = String(story.meta.status ?? "not open");
+        return {
+          route: "new-story",
+          reason: `${id} is ${status} – finished work is final, so this becomes a new story`,
+        };
+      }
+    }
+  }
+  if (bug) {
+    return { route: "bug", reason: "flagged as a bug – restore documented behaviour, do not run feature discovery" };
+  }
+  return { route: "feature", reason: "new or changed behaviour – run the feature pipeline" };
+}
+
+function loadJiraIssues(path: string): { issue: RemoteIssue; raw: d.Obj }[] {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    fail(`Jira: could not read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const list = Array.isArray(raw)
+    ? raw
+    : (raw as d.Obj | null)?.issues ?? (raw as d.Obj | null)?.values ?? (raw as d.Obj | null)?.results ?? [];
+  if (!Array.isArray(list)) fail(`Jira: ${path} must contain an array of issues (or { "issues": [...] })`);
+  return list.flatMap((item) => {
+    if (item === null || typeof item !== "object") return [];
+    const issue = normalizeJiraIssue(item as d.Obj);
+    return issue ? [{ issue, raw: item as d.Obj }] : [];
+  });
+}
+
+function jiraIssueType(raw: d.Obj): string {
+  const fields = (raw.fields ?? raw) as d.Obj;
+  const type = fields.issuetype ?? fields.issue_type ?? raw.issuetype;
+  if (typeof type === "string") return type;
+  return typeof type?.name === "string" ? type.name : "";
+}
+
+function summarize(source: Source, body: string): Pick<Intake, "signals"> {
+  return {
+    signals: {
+      bug: looksLikeBug(source.title ?? "", source.labels),
+      scenarios: count(/\bScenario(?: Outline| Template)?\s*:/g, body),
+      checklistItems: count(/^\s*[-*]\s*\[[ xX]\]/gm, body),
+      openQuestions: count(/\[OPEN\]/g, body),
+    },
+  };
+}
+
+interface JiraHit {
+  source: Source;
+  linked: d.Story | null;
+  body: string;
+  jiraType: string;
+}
+
+function loadJira(key: string, from: string, cfg: BacklogConfig, warnings: string[]): JiraHit {
+  if (!from) {
+    fail(
+      `Jira ${key}: Jira is reached through mcp-atlassian, which only the agent can call.\n` +
+        "  Fetch the issue with jira_get_issue, write it as JSON, then:\n" +
+        `  node .claude/skills/feature/scripts/intake.ts ${key} --from <issue.json>`,
+    );
+  }
+  const issues = loadJiraIssues(from);
+  const hit = issues.find((entry) => entry.issue.key.toUpperCase() === key) ??
+    (issues.length === 1 ? issues[0] : undefined);
+  if (!hit) {
+    fail(
+      `Jira ${key}: no matching issue in ${from}` +
+        `${issues.length ? ` (found ${issues.map((i) => i.issue.key).join(", ")})` : ""}.`,
+    );
+  }
+  if (cfg.provider !== "jira") {
+    warnings.push(`configured backlog provider is '${cfg.provider}' – the issue is read as evidence only`);
+  }
+  return {
+    source: {
+      kind: "jira",
+      ref: hit.issue.key,
+      title: hit.issue.title,
+      url: hit.issue.url,
+      status: hit.issue.status,
+      labels: hit.issue.labels,
+      body: hit.issue.body,
+    },
+    linked: findLinked("jira", hit.issue.key),
+    body: hit.issue.body,
+    jiraType: jiraIssueType(hit.raw),
+  };
+}
+
+function main(): void {
+  const args = process.argv.slice(2);
+  const json = args.includes("--json");
+  const fromIndex = args.indexOf("--from");
+  const from = fromIndex >= 0 ? args[fromIndex + 1] ?? "" : "";
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--json") continue;
+    if (args[i] === "--from") {
+      i++;
+      continue;
+    }
+    positional.push(args[i]);
+  }
+  const input = positional.join(" ").trim();
+
+  if (!input) {
+    fail(
+      "Usage: node .claude/skills/feature/scripts/intake.ts <ST-NNN | #issue | PROJ-123 | URL | idea> " +
+        "[--from <jira-issues.json>] [--json]",
+    );
+  }
+
+  const cfg: BacklogConfig = loadBacklogConfig();
+  const warnings: string[] = [];
+  let source: Source;
+  let body = "";
+  let linked: d.Story | null = null;
+  let jiraType = "";
+
+  const storyMatch = /^(ST-\d{3,})$/i.exec(input);
+  const ghUrl = GH_URL.exec(input);
+  const jiraUrl = JIRA_URL.exec(input);
+  const ghRef = /^#(\d+)$/.exec(input);
+  const jiraRef = /^([A-Z][A-Z0-9_]+-\d+)$/.exec(input);
+
+  if (storyMatch) {
+    const id = storyMatch[1].toUpperCase();
+    const story = findStory(id);
+    if (story) {
+      linked = story;
+      body = story.body;
+      source = {
+        kind: "story",
+        ref: id,
+        title: String(story.meta.title ?? ""),
+        status: String(story.meta.status ?? ""),
+        labels: Array.isArray(story.meta.labels) ? story.meta.labels.map(String) : [],
+        body: story.body,
+      };
+    } else if (from) {
+      // `ST-` is the story prefix, but a Jira project may use the same key – the export disambiguates.
+      const hit = loadJira(id, from, cfg, warnings);
+      source = hit.source;
+      linked = hit.linked;
+      body = hit.body;
+      jiraType = hit.jiraType;
+    } else {
+      fail(`Story ${id} not found in docs/stories/.`);
+    }
+  } else if (ghRef || ghUrl) {
+    const key = ghRef ? ghRef[1] : ghUrl![3];
+    const repo = ghUrl ? `${ghUrl[1]}/${ghUrl[2]}` : undefined;
+    let issue: RemoteIssue | null;
+    try {
+      issue = readGithubIssue(cfg, key, repo);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (/ENOENT|spawnSync gh/i.test(message)) fail("GitHub: the `gh` CLI is not installed or not on PATH.");
+      fail(`GitHub: ${message}`);
+    }
+    if (!issue) fail(`GitHub issue #${key}${repo ? ` in ${repo}` : ""} not found (or not accessible).`);
+    if (cfg.provider !== "github") warnings.push(`configured backlog provider is '${cfg.provider}' – the issue is read as evidence only`);
+    if (issue.state === "closed") warnings.push("the issue is closed – confirm the work is still wanted");
+    body = issue.body;
+    source = {
+      kind: "github",
+      ref: `#${issue.key}`,
+      title: issue.title,
+      url: issue.url,
+      status: issue.state,
+      labels: issue.labels,
+      body: issue.body,
+    };
+    linked = findLinked("github", issue.key);
+  } else if (jiraRef || jiraUrl) {
+    const key = (jiraRef ? jiraRef[1] : jiraUrl![1]).toUpperCase();
+    const hit = loadJira(key, from, cfg, warnings);
+    source = hit.source;
+    linked = hit.linked;
+    body = hit.body;
+    jiraType = hit.jiraType;
+  } else {
+    body = input;
+    source = {
+      kind: "text",
+      ref: input,
+      title: input.split("\n")[0].slice(0, 120),
+      labels: [],
+      body: input,
+    };
+  }
+
+  const { signals } = summarize(source, body);
+  if (jiraType && /^bug$/i.test(jiraType)) signals.bug = true;
+
+  if (linked && source.kind !== "story") {
+    warnings.push(`linked to ${d.storyId(linked)} – run /backlog-sync pull first so the mirror is current`);
+  }
+  const broken = d.loadStories().failures.length;
+  if (broken) warnings.push(`${broken} story file(s) have broken frontmatter – run the story validator`);
+
+  const { route, reason } = routeFor(linked, signals.bug);
+  const result: Intake = {
+    source,
+    story: linked ? storyRef(linked) : null,
+    route,
+    reason,
+    signals,
+    warnings,
+  };
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const lines = [`Source   ${source.kind} ${source.ref}${source.title ? ` – "${source.title}"` : ""}`];
+  if (source.url) lines.push(`URL      ${source.url}`);
+  if (source.status) lines.push(`Status   ${source.status}`);
+  if (source.labels.length) lines.push(`Labels   ${source.labels.join(", ")}`);
+  if (result.story) {
+    lines.push(`Story    ${result.story.id} "${result.story.title}" (${result.story.status})`);
+    lines.push(`Path     ${result.story.path}`);
+  }
+  lines.push(`Route    ${route}`, `         ${reason}`);
+  lines.push(
+    `Signals  bug=${signals.bug ? "yes" : "no"} scenarios=${signals.scenarios} ` +
+      `checklist=${signals.checklistItems} open=${signals.openQuestions}`,
+  );
+  for (const warning of warnings) lines.push(`Warning  ${warning}`);
+  console.log(lines.join("\n"));
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/.claude/skills/grill-me/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+Call the `skill` tool with `grilling`.

package/.claude/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (glossary in CONTEXT.md and ADRs in docs/adr/) as we go.
+disable-model-invocation: true
+---
+
+Call the `skill` tool three times, for `grilling`, `domain-model` and `architect`.

package/.claude/skills/grilling/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: grilling
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.
+
+Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.
+
+Format a round like so:
+
+```
+❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+
+---
+
+❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>
+
+➡️ <your recommended answer>
+```
+
+Word each question so "yes" accepts your recommended answer.
+
+Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one.
+
+Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait.
+
+The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding.

package/.claude/skills/groom-backlog/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: groom-backlog
+description: Periodic grooming of the open backlog – challenges whether stories are still worth building, whether dependencies still hold and whether the priorities still match what the product needs now.
+disable-model-invocation: true
+argument-hint: "[BC-Name | ST-IDs, empty = every story that is not done]"
+---
+
+# Backlog Grooming
+
+Scope: the arguments from the invocation (empty → every story that is not `done`; `BC-Collection` → one bounded context; `ST-007 ST-008` → single stories).
+
+`/review-stories` asks "is this new story ready to build?". Grooming asks the opposite question about what has been
+lying around: **would we still write this story today?** The backlog was derived in one go from the event storming;
+every done story, every ADR and every answered open question since then may have made part of it wrong, redundant
+or differently important. Nothing here is a formality – a grooming run that changes nothing was a wasted run or a
+healthy backlog, and you have to be able to say which.
+
+Do **not** fix anything yourself. Grooming produces a decision for the user and a task for the `requirements-engineer`.
+
+## 1. Mechanical health check
+
+With a tracker (`backlog.provider` ≠ `local`), pull first (`/backlog-sync pull`) – grooming a stale mirror wastes the
+run. Then:
+
+```
+node .claude/skills/groom-backlog/scripts/backlog-health.ts <scope>
+```
+
+Dependency cycles, stories waiting for dropped or non-existent ones, priority inversions, `ready` stories blocked
+by `draft`, references to IDs `events.yaml` no longer has, stories that already have tests, parked `[OPEN]`
+decisions and open questions older than 30 days. These are **findings, not errors** – they say where to look, the
+judgement comes next. Read `docs/stories/BACKLOG.md` and `docs/stories/OPEN_QUESTIONS.md` as well.
+
+## 2. What changed since the backlog was written
+
+Before asking anyone else: build the list of changes the backlog may not have caught up with. `git log --oneline`
+since the last grooming review in `docs/reviews/`, the stories that went `done`, new and superseded ADRs, answered
+rows in `OPEN_QUESTIONS.md`, and the "revisit when …" lines parked in `docs/reviews/ST-NNN-code-review.md`. Hand
+this list to the subagents – they cannot see it, and without it they re-read the same stories that were already
+reviewed once.
+
+## 3. Challenge in parallel
+
+Start in **one** message, with the full file paths, the scope and the change list from step 2:
+
+- `product-owner` – is the value still real and still in the vision? Is the story already covered by what was
+  built? Does the MVP slice still hold? Which `must` is not a `must` any more, and which `could` turned out to be
+  one? Which need from the vision still has no story?
+- `lead-dev` – do `depends_on`, `size` and `risk` still fit **now that the code exists**? Which story has become
+  smaller because the foundation is there, which bigger? Which dependency is technical fiction? Which story should
+  be split, merged or dropped?
+- `ux-designer` – only for stories with the label `ui` (or an obvious frontend part): does the story still match
+  `docs/product/ux-guidelines.md`, and which one builds a screen that a newer story has replaced?
+
+Tell each one explicitly: **recommend, don't rewrite** – they change only the frontmatter fields they own
+(`priority` for the PO, `size`/`risk`/`depends_on` for the lead dev), everything else comes back as a proposal.
+
+## 4. Consolidate
+
+Write `docs/reviews/YYYY-MM-DD-backlog-grooming.md`:
+
+- the health-check findings with what they turned out to mean
+- per challenged story: keep / revise / split / merge / drop, with the reason and who said it
+- conflicts between the three – name them, don't average them away
+- proposed new stories, and stories proposed for `priority: wont`
+- what explicitly stays as it is, so the next run does not re-litigate it
+
+## 5. The user decides
+
+Present it in rounds, at most 3 questions at a time, each with a recommended answer. Adopt nothing without consent.
+A disagreement between PO and lead-dev is a question for the user, not something to resolve on their behalf.
+
+## 6. Apply
+
+- Content changes → `requirements-engineer`, referencing the grooming file.
+- **Dropped stories are never deleted**: they get `priority: wont` and keep their file, so the decision stays
+  traceable. A story that is wrong rather than unwanted goes back to `status: review` and through `/review-stories`.
+- A `done` story is never reopened – a change to finished behaviour is a new story.
+- New stories from the grooming get `status: draft` and go through `/review-stories` like any other.
+- With a tracker, push the applied changes (`/backlog-sync push`) before the wrap-up, so Jira/GitHub and the mirror
+  agree. A story that is not linked yet stays a local draft until the push creates it.
+
+## 7. Wrap-up
+
+`node .claude/skills/user-stories/scripts/validate-stories.ts`, then the health check again – the findings you
+decided to act on should be gone, and you should be able to say why each remaining one stays. Summarize in a few
+lines: how many stories were challenged, what changed, what was dropped, what the user still has to decide.
+
+## When to run it
+
+After a bounded context is finished, after a `/feature` has landed, or roughly every 8–10 done domain stories –
+and always before planning a larger block of work. Not between two stories of the same context: the backlog has
+not moved by then, and a grooming run that finds nothing twice in a row means the interval is too short.