kataster 0.0.0-stage → 0.2.1

package/.claude/skills/adopt/scripts/repo-map.ts

@@ -0,0 +1,123 @@
+/**
+ * Builds the deterministic repository map that `/adopt` works from.
+ *
+ *   node .claude/skills/adopt/scripts/repo-map.ts              # write map + root AGENTS block
+ *   node .claude/skills/adopt/scripts/repo-map.ts --json       # print the map, write nothing
+ *   node .claude/skills/adopt/scripts/repo-map.ts --check      # exit 1 when the map is stale
+ *   node .claude/skills/adopt/scripts/repo-map.ts --adopt <path>
+ *
+ * The map is generated from manifests and git history. It is not a domain model: it says where code lives,
+ * how packages depend on each other and which slice to adopt first. Domain meaning comes from the grilling.
+ */
+import { ROOT, findPackage, markAdopted, packageCounts, proposeSlices, readRepoMap, scanRepo, stableMap, updateProjectTooling, writeRepoMap, writeRootBlock } from "../../../lib/repo.ts";
+import { graphLabel, graphToolLabel } from "../../../lib/toolgraph.ts";
+
+const args = process.argv.slice(2);
+const root = ROOT;
+
+function usage(): void {
+  console.log(
+    [
+      "Usage: node .claude/skills/adopt/scripts/repo-map.ts [--json|--check|--adopt <path>]",
+      "",
+      "  (no option)     write docs/architecture/repo-map.{json,md} and the root AGENTS.md block",
+      "  --json          print the map as JSON without writing",
+      "  --check         exit 1 when the checked-in map no longer matches the repository",
+      "  --adopt <path>  mark a package as adopted (after the grilling)",
+      "  --no-tool-graph skip the build-tool graph query (Turbo/Nx/Bazel); manifest graph only",
+    ].join("\n"),
+  );
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+const adoptIndex = args.indexOf("--adopt");
+if (adoptIndex !== -1) {
+  const path = args[adoptIndex + 1];
+  if (!path) {
+    console.error("--adopt needs a package path, e.g. apps/billing");
+    process.exit(1);
+  }
+  try {
+    const map = markAdopted(root, path);
+    const pkg = findPackage(map, path);
+    console.log(`Adopted: ${pkg?.path ?? path}${pkg?.name ? ` (${pkg.name})` : ""}`);
+    console.log("The root AGENTS.md block now lists it as adopted.");
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+const map = scanRepo(root, {
+  // --check stays fast and environment-independent; the graph is enrichment, not part of the stable map.
+  toolGraph: !args.includes("--check") && !args.includes("--no-tool-graph"),
+});
+// Refreshing the map must not forget which slices were already adopted.
+const previous = readRepoMap(root);
+if (previous) {
+  for (const pkg of map.packages) {
+    const old = previous.packages.find((p) => p.path === pkg.path);
+    if (old?.adopted) {
+      pkg.adopted = true;
+      pkg.adoptedAt = old.adoptedAt;
+    }
+  }
+}
+
+if (args.includes("--json")) {
+  console.log(JSON.stringify(map, null, 2));
+  process.exit(0);
+}
+
+if (args.includes("--check")) {
+  const existing = readRepoMap(root);
+  if (!existing) {
+    console.error("No docs/architecture/repo-map.json yet – run repo-map.ts once.");
+    process.exit(1);
+  }
+  if (stableMap(existing) === stableMap(map)) {
+    console.log("OK – the repository map matches the manifests.");
+    process.exit(0);
+  }
+
+  const before = new Map(existing.packages.map((p) => [p.path, p]));
+  const after = new Map(map.packages.map((p) => [p.path, p]));
+  const added = [...after.keys()].filter((p) => !before.has(p));
+  const removed = [...before.keys()].filter((p) => !after.has(p));
+  const changed = [...after.keys()].filter((p) => before.has(p) && JSON.stringify(before.get(p)) !== JSON.stringify(after.get(p)));
+  console.error("The repository map is stale – run `node .claude/skills/adopt/scripts/repo-map.ts` and review the diff.");
+  if (added.length) console.error(`  added:   ${added.join(", ")}`);
+  if (removed.length) console.error(`  removed: ${removed.join(", ")}`);
+  if (changed.length) console.error(`  changed: ${changed.join(", ")}`);
+  process.exit(1);
+}
+
+const written = writeRepoMap(root, map);
+const profileUpdated = updateProjectTooling(root, map.tooling);
+const agentsUpdated = writeRootBlock(root, map);
+const proposal = proposeSlices(map);
+
+console.log(`Repository map written: ${written.json.replace(`${root}/`, "")}, ${written.md.replace(`${root}/`, "")}`);
+console.log(`Tooling: ${map.tooling.kind === "none" ? "none (single package)" : map.tooling.kind}${map.tooling.config ? ` (${map.tooling.config})` : ""}`);
+if (map.toolGraph) {
+  console.log(`Tool graph: ${graphLabel(map.toolGraph)}${map.toolGraph.task ? ` (${map.toolGraph.task})` : ""} – ${map.toolGraph.packages.length} package(s), ${map.toolGraph.edges.length} edge(s)`);
+} else {
+  const tool = graphToolLabel(map.tooling.kind);
+  if (tool) console.log(`Tool graph: ${tool} graph not available – using the manifest graph`);
+}
+console.log(`Packages: ${map.packages.length} (${packageCounts(map)})`);
+if (profileUpdated) console.log("Updated .claude/project.json → repo.tooling");
+if (agentsUpdated) console.log("Updated the generated repository block in AGENTS.md");
+
+if (proposal.domain) {
+  console.log("");
+  const label = proposal.domain.path === "." ? "root package" : proposal.domain.path;
+  console.log(`Suggested first slice: ${label} (${proposal.domain.name})`);
+  if (proposal.library) console.log(`  with shared library: ${proposal.library.path} (${proposal.library.name})`);
+  console.log(`Mark it adopted after the grilling: node .claude/skills/adopt/scripts/repo-map.ts --adopt ${proposal.domain.path}`);
+}

package/.claude/skills/adopt/scripts/rule-doc.ts

@@ -0,0 +1,80 @@
+/**
+ * Scaffolds and validates `.claude/rules/*.md` – path-scoped rules with `paths:` frontmatter.
+ *
+ *   node .claude/skills/adopt/scripts/rule-doc.ts libs-shared --paths "libs/**" --title "Shared libraries"
+ *   node .claude/skills/adopt/scripts/rule-doc.ts --check
+ *   node .claude/skills/adopt/scripts/rule-doc.ts --list
+ *
+ * A rule for a whole directory should be `<dir>/AGENTS.md` instead – that is the mechanism both harnesses load
+ * on demand. `.claude/rules/` is for patterns a directory cannot express (e.g. every SQL file). Claude Code reads
+ * these files natively; OpenCode's plugin injects a matching rule when a file under its `paths:` is touched.
+ */
+import { relPath, validateRules, writeRule } from "../../../lib/architecture.ts";
+import { ROOT } from "../../../lib/repo.ts";
+
+const args = process.argv.slice(2);
+
+function usage(): void {
+  console.log(
+    [
+      "Usage: node .claude/skills/adopt/scripts/rule-doc.ts <slug> --paths <glob> [--paths <glob>] [--title <title>]",
+      "       node .claude/skills/adopt/scripts/rule-doc.ts --check",
+      "       node .claude/skills/adopt/scripts/rule-doc.ts --list",
+    ].join("\n"),
+  );
+}
+
+if (args.includes("--help") || args.includes("-h")) {
+  usage();
+  process.exit(0);
+}
+
+if (args.includes("--check")) {
+  const { rules, errors } = validateRules(ROOT);
+  for (const error of errors) console.error(`ERROR ${error}`);
+  if (errors.length) process.exit(1);
+  console.log(`OK – ${rules.length} rule file${rules.length === 1 ? "" : "s"} valid.`);
+  process.exit(0);
+}
+
+if (args.includes("--list")) {
+  const { rules, errors } = validateRules(ROOT);
+  for (const rule of rules) console.log(`${rule.path}: ${rule.paths.join(", ")} – ${rule.title}`);
+  if (errors.length) {
+    for (const error of errors) console.error(`ERROR ${error}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+const slug = args.find((arg) => !arg.startsWith("--"));
+if (!slug) {
+  usage();
+  process.exit(1);
+}
+
+const paths: string[] = [];
+for (let i = 0; i < args.length; i += 1) {
+  if (args[i] !== "--paths") continue;
+  const value = args[i + 1];
+  if (!value || value.startsWith("--")) {
+    console.error("--paths needs a glob, e.g. --paths \"libs/**\"");
+    process.exit(1);
+  }
+  paths.push(...value.split(",").map((p) => p.trim()).filter(Boolean));
+}
+
+const titleIndex = args.indexOf("--title");
+const fallbackTitle = slug.replaceAll("-", " ").replace(/^\w/, (c) => c.toUpperCase());
+const title = titleIndex !== -1 && args[titleIndex + 1] && !args[titleIndex + 1].startsWith("--")
+  ? args[titleIndex + 1]
+  : fallbackTitle;
+
+try {
+  const path = writeRule(ROOT, slug, paths, title);
+  console.log(`Created ${relPath(ROOT, path)}.`);
+  console.log("Fill the rule body during the grilling; one rule per file, and name its enforcement point.");
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/.claude/skills/architect/ADR-FORMAT.md

@@ -0,0 +1,97 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. Written in English.
+
+## Template
+
+```md
+---
+status: proposed
+date: YYYY-MM-DD
+---
+
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why. Cite the driving requirement with its path, e.g. `docs/product/vision.md`.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why*, not in filling out sections.
+
+## Status
+
+The `status` frontmatter is mandatory, because decisions here go through the user:
+
+- `proposed` – every new ADR, whoever writes it (main session or `domain-architect`)
+- `accepted` – **set only by the user**
+- `rejected`
+- `superseded by ADR-NNNN` – accepted ADRs are never edited; a new ADR replaces them
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Considered Options**: only when the rejected alternatives are worth remembering
+- **Consequences**: only when non-obvious downstream effects need to be called out (incl. follow-up spikes or tech tasks)
+
+## Large decisions
+
+For decisions with several serious options and many criteria (e.g. the tech stack, see [TECH-STACK.md](./TECH-STACK.md)), use the full form:
+
+```md
+---
+status: proposed
+date: YYYY-MM-DD
+---
+
+# NNNN – {Short title}
+
+## Context and Problem
+{Which question is being decided, and why now?}
+
+## Driving Requirements
+- {Requirement} – source: `docs/...`
+
+## Considered Options
+1. {Option A}
+2. {Option B}
+
+## Evaluation
+| Criterion | Option A | Option B |
+|---|---|---|
+| … | … | … |
+
+## Decision
+{Chosen option} – because {reasoning that follows from the evaluation}.
+
+## Consequences
+- Positive: …
+- Negative / cost: …
+- Follow-up work (spikes, tech tasks): …
+
+## Open Points
+- HS-… / questions
+```
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will look at the system and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it: you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "The product is a single deployable PWA." "Cases are stored as an event history; their status is projected from it."
+- **Integration patterns between contexts.** "Ordering and fulfilment communicate via domain events, not direct calls."
+- **Technology choices that carry lock-in.** Database, auth provider, hosting, offline storage. Not every library: just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Product master data is owned by the catalogue context; others reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the system.** "Customers must be able to submit without an account." "The warehouse has no reliable Wi-Fi."
+- **Rejected alternatives when the rejection is non-obvious.** Otherwise someone will suggest them again in six months.

package/.claude/skills/architect/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: architect
+description: Build and sharpen the project's architecture and record decisions as ADRs in docs/adr/ (incl. the tech stack decision). Use when discussing architectural shape, integration between bounded contexts, technology choices, or when recording or editing an ADR.
+---
+
+# Architecture
+
+Actively build and sharpen the architecture as you design. This is the *active* discipline: challenging decisions, inventing scenarios that stress them, and writing decisions down the moment they crystallise. (Merely *reading* ADRs for context is not this skill. This skill is for when you're changing the architecture, not just consuming it.)
+
+Domain language (the glossary in `CONTEXT.md`), bounded contexts, aggregates and the logical data model belong to the `domain-model` skill. Architecture builds on them: the domain comes first, technology follows.
+
+## File structure
+
+```
+/
+├── CONTEXT.md                  ← glossary (domain-model skill)
+└── docs/
+    ├── adr/                    ← architecture decisions (this skill)
+    │   ├── 0001-tech-stack.md
+    │   └── 0002-...
+    ├── architecture/
+    │   └── data-model.md       ← logical data model (domain-model skill)
+    └── domain/
+        ├── context-map.md
+        └── events.yaml
+```
+
+Once code exists and contexts live in separate modules, context-specific decisions may move next to the code (`src/<context>/docs/adr/`); system-wide decisions stay in `docs/adr/`.
+
+## During the session
+
+### Challenge against existing decisions
+
+When a proposal conflicts with an accepted ADR, call it out immediately: "ADR 0002 says reports work offline, but this assumes a live connection. Do we supersede 0002?" Accepted ADRs are never edited; they are superseded by a new one.
+
+### Trace every decision back to a requirement
+
+Architecture follows documented needs, not taste. Every decision cites its driving requirement with a path (`docs/product/vision.md`, `docs/domain/events.yaml`, a story, a hotspot). No documented requirement → no extra complexity. If the requirement is missing, it's a question for the user or a hotspot, not an assumption.
+
+### Discuss concrete scenarios
+
+Stress-test decisions with specific scenarios: "A field worker is in a basement without connectivity and wants to record a result – what happens?" "Two people close the same case at the same time." Force precision about the boundaries where the architecture could break.
+
+### Cross-reference with docs and code
+
+When the user states how something works, check `docs/` (and the code, once it exists) for agreement. Surface contradictions: "The data model has one owner per item, but you just said items can be lent with a second owner. Which is right?"
+
+### Prefer the simplest architecture
+
+The simplest architecture that meets the documented requirements is the default. Distributed systems, separate apps or microservices each need a concrete, documented requirement as justification.
+
+### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse**: the cost of changing your mind later is meaningful
+2. **Surprising without context**: a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off**: there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). New ADRs always start as `proposed`; **only the user sets `accepted`**.
+
+### The tech stack decision
+
+Decide only after the event storming and a rough domain model exist; before that the facts are missing. Follow [TECH-STACK.md](./TECH-STACK.md).

package/.claude/skills/architect/TECH-STACK.md

@@ -0,0 +1,21 @@
+# Tech Stack Decision
+
+Decide only once the event storming and a rough domain model exist. Before that, the facts are missing. Record the result as a large ADR (see [ADR-FORMAT.md](./ADR-FORMAT.md)), `status: proposed`.
+
+## Criteria (evaluate each with evidence from `docs/`)
+
+1. **On-site use**: Is work done on a device (phone/tablet)? What is the network coverage (Wi-Fi in the hall)? Offline required?
+2. **Device features**: Camera, QR/barcode scanning, push notifications, offline use – is the browser (PWA) enough, or are native apps needed?
+3. **User groups & access**: Public reporting (e.g. visitors) vs. internal team, roles, authentication.
+4. **Other consumers**: Are there concrete additional clients or integrations today that justify a standalone API?
+5. **Team & maintenance**: Who develops and runs this long-term? Which languages does the team know?
+6. **Operations**: Hosting, cost, backups, updates – as few moving parts as possible.
+7. **Future-proofing without up-front cost**: Does the option allow later expansion without paying for it today?
+
+## Evaluate at least these options
+
+- **A – Full-stack monolith as a PWA** (e.g. Next.js with a cleanly separated domain layer). One deployment, usable on mobile via browser/PWA.
+- **B – Separate API (Go or TypeScript) + web app + mobile app**. Maximum decoupling, three codebases and release processes.
+- **C – Hybrid**: monolith with a clearly separated domain/API layer now; extract an API or build a native app only when there is concrete need.
+
+Evaluation as a table (criterion × option, with reasoning). The recommendation must follow from the table. Name effort differences explicitly. Uncertainties → propose a spike story.

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

@@ -0,0 +1,198 @@
+---
+name: backlog
+description: Keeps docs/stories/ in sync with the configured backlog backend – local (default), GitHub Issues via gh, or Jira via mcp-atlassian.
+disable-model-invocation: true
+argument-hint: "[status | pull | push] [ST-NNN ...]"
+---
+
+# Backlog Backend
+
+`docs/stories/` is the exchange format, not necessarily the backlog. `.claude/project.json` decides where the source
+of truth lives:
+
+```jsonc
+"backlog": {
+  "provider": "local",                    // local | github | jira
+  "github": { "repo": "", "labelPrefix": "kataster" },
+  "jira": {
+    "mcpServer": "mcp-atlassian",
+    "project": "PROJ",
+    "issueType": "Story",
+    "labelPrefix": "kataster",
+    "statusMap": {
+      "draft": "To Do", "review": "In Review", "ready": "Ready",
+      "in-progress": "In Progress", "done": "Done", "superseded": "Won't Do"
+    },
+    "priorityMap": { "must": "Highest", "should": "High", "could": "Medium", "wont": "Lowest" }
+  }
+}
+```
+
+| Provider | Source of truth | Transport |
+|---|---|---|
+| `local` | `docs/stories/` | none – the default, nothing changes |
+| `github` | GitHub Issues | `gh` CLI (deterministic, works from scripts) |
+| `jira` | Jira | `mcp-atlassian` (MCP is agent-only; the scripts prepare and consume the payloads) |
+
+**With a tracker, the tracker leads.** `docs/stories/` is a local mirror that keeps validation, test traceability and
+offline work intact. You may create and edit stories there; publish them through the sync. A change made in the
+tracker is pulled into the mirror.
+
+## Running a sync
+
+- empty or `status` → `backlog-status.ts`: what is linked, what drifted.
+- `pull` → GitHub: `backlog-pull.ts`; Jira: fetch with MCP, write the JSON, `backlog-pull.ts --from`.
+- `push [ST-NNN …]` → GitHub: `backlog-push.ts`; Jira: `jira-plan.ts` → MCP → `jira-record.ts` → plan again for links.
+- A single story argument limits push/plan to that story; pull processes every issue in the import.
+
+## What syncs
+
+Only the backlog core:
+
+- the story body and `title`, `type`, `context`, `priority`, `size`, `risk`, `events`, `depends_on`, `labels`, `status`
+- the external reference, `external: { provider, key, url }`
+- nothing else: `docs/reviews/`, `docs/stories/OPEN_QUESTIONS.md`, ADRs and `BACKLOG.md` stay local. `BACKLOG.md` is
+  generated from the mirror and never synced.
+
+The story keeps its stable `ST-NNN` id; the tracker key lives in `external`. Test titles (`ST-NNN: <scenario>`) and the
+domain IDs therefore do not change when a tracker is added. **Never renumber a story, never write `external` by hand.**
+
+The issue body is the story body plus a machine block:
+
+- GitHub: `<!-- kataster:story … -->` (hidden in the rendered issue)
+- Jira: a ```` ```kataster-story … ``` ```` code block (Jira Cloud drops HTML comments when it converts Markdown to ADF)
+
+The block restores the fields the tracker has no field for. The tracker wins for the fields it does have: status,
+priority and the `kataster-*` labels.
+
+## GitHub
+
+`gh` must be installed and authenticated (`gh auth login`, `repo` scope). `repo` may be empty – then `gh` uses the
+repository it runs in. Labels are created on demand.
+
+```bash
+node .claude/skills/backlog/scripts/backlog-status.ts   # what is linked, what drifted (--check exits 1)
+node .claude/skills/backlog/scripts/backlog-push.ts     # create/update issues from the mirror
+node .claude/skills/backlog/scripts/backlog-pull.ts     # import issue changes into the mirror
+```
+
+A story without `external` is created by `push`; an issue whose title starts with `ST-NNN:`, that carries the
+`kataster` label, or that contains the machine block is picked up by `pull`. `done` and `superseded` close the issue;
+`superseded` closes as "not planned". A status change through `story-status.ts` also updates the linked issue.
+
+## Jira
+
+Jira is reached through `mcp-atlassian`. A script cannot call MCP, so the agent is the transport and the scripts do
+the mapping:
+
+1. **Plan the push.**
+   ```bash
+   node .claude/skills/backlog/scripts/jira-plan.ts [ST-NNN ...]
+   ```
+   **Pull before you push.** `jira-plan` cannot see Jira, so it cannot detect a conflict; the import does. Fetch and
+   import the issues first, then plan. A local file that the import left alone is safe to push; a conflict means the
+   tracker won and the mirror is current.
+   It prints JSON actions: `create` (`jira_create_issue`), `update` (`jira_update_issue`), `transition`
+   (`jira_transition_issue`) and `link` (`jira_create_issue_link`). For a story with no `external.key` the action is
+   `create`; its links are planned after the key exists.
+2. **Execute with the MCP server named in `backlog.jira.mcpServer`.**
+   - `create`: call `jira_create_issue` with the given `arguments`. Keep `key` and `browse_url` from the response.
+   - `update`: call `jira_update_issue`.
+   - `transition`: call `jira_get_transitions` for the issue first, pick the transition that reaches the `target`
+     status, then call `jira_transition_issue`. If the issue is already there, skip it.
+   - `link`: call `jira_create_issue_link`. `Blocks` is read as "outward issue blocks inward issue", so a story that
+     depends on another has the dependency as `outward_issue_key`.
+   - An action with `skip` is a note, not an MCP call: either the story is linked to another provider (fix the
+     configuration or the external ref), or a link has to wait until the dependency has a Jira key. Re-run the plan
+     after recording the missing key.
+3. **Record the keys.**
+   ```bash
+   node .claude/skills/backlog/scripts/jira-record.ts --from results.json
+   # [{"story":"ST-012","key":"PROJ-123","url":"https://…/browse/PROJ-123"}]
+   ```
+4. **Create the links.** Run `jira-plan.ts` again now that the keys exist and execute the `link` actions.
+5. **Pull.**
+   - Search with JQL `project = "<project>" AND labels = "kataster" ORDER BY key ASC`, or load the known keys
+     individually with `jira_get_issue`; ask for `summary, description, status, labels, priority`.
+   - Write the result as JSON and import it:
+     ```bash
+     node .claude/skills/backlog/scripts/backlog-pull.ts --from issues.json
+     ```
+     Accepted shape:
+     ```json
+     [{ "key": "PROJ-123", "summary": "ST-012: …", "description": "…", "status": "Ready",
+        "labels": ["kataster", "kataster-status-ready"], "priority": "High",
+        "browse_url": "https://…/browse/PROJ-123" }]
+     ```
+     `{ "key": "…", "fields": { "summary": "…", "description": "…", "status": { "name": "…" },
+     "priority": { "name": "…" }, "labels": [] } }` is accepted too.
+
+Jira may normalize Markdown on the way in and out. The mirror follows what Jira returns, so the first pull can
+reformat a body; that is not a lost change. The machine block lives in a code block because Jira Cloud ADF drops HTML
+comments.
+
+`statusMap` and `priorityMap` must match the project's Jira workflow and priority scheme. If a status has no
+transition, report it – do not invent one. The status label (`kataster-status-*`) is a fallback when the Jira status
+name is not in the map. Jira labels allow only letters, numbers and a few separators, so story labels are sanitized on
+the issue; the machine block keeps the original labels and restores them on a pull.
+
+## Conflicts
+
+The sync keeps a hash of the local file and of the remote issue at the last successful sync
+(`.claude/state/backlog-sync.json`):
+
+- **Remote changed, local unchanged** → pull updates the mirror.
+- **Remote unchanged, local changed** → pull leaves the local story alone; push publishes it.
+- **Both changed** → *the tracker wins*. Pull overwrites the mirror, backs the local file up to
+  `.kataster/backup/backlog/<timestamp>/` and says so. Push refuses that story and tells you to pull first.
+- **A local story has no external ref** → push creates it; pull reports it as local-only.
+- **A linked issue disappeared** → reported as orphan. Nothing is deleted automatically.
+- **Jira has no conflict detection in the plan** → pull first. The import compares the hashes and reports a conflict;
+  only then is the mirror safe to push.
+
+Never force a conflict away, never delete a story because its issue is gone, and never re-create an orphaned issue
+silently – ask the user.
+
+## When to sync
+
+- after `requirements-engineer` created or changed stories → `push`
+- after `product-owner` or `lead-dev` changed `priority`, `size`, `risk`, `depends_on` → `push`
+- before `/review-stories` → `pull`, then review, then `push` the approved stories
+- before `/implement` → `pull`; after each status change the workflow updates the tracker (GitHub directly, Jira by
+  the printed MCP transition), and after `done` → `push`
+- before `/groom-backlog` → `pull`; after applying the grooming → `push`
+- a story must be linked before it reaches `ready` – the validator refuses an unlinked `ready` story in tracker mode
+
+## Setup
+
+**GitHub:** `backlog.provider: "github"`. Fill `backlog.github.repo` if it is not the current repository. Authenticate
+`gh` once.
+
+**Jira:** `backlog.provider: "jira"`, a real `backlog.jira.project`, and the `mcp-atlassian` server configured in the
+harness. Claude Code: `.mcp.json`; OpenCode: the `mcp` block in `opencode.jsonc`:
+
+```jsonc
+{
+  "mcp": {
+    "mcp-atlassian": {
+      "type": "local",
+      "command": ["uvx", "mcp-atlassian"],
+      "enabled": true,
+      "environment": { "JIRA_URL": "https://…", "JIRA_USERNAME": "…", "JIRA_API_TOKEN": "…" }
+    }
+  }
+}
+```
+
+Never put tokens in `.claude/project.json` or in a committed file. `/backlog-sync` reports a missing server, an empty
+project or a missing `gh` login – tell the user, don't work around it.
+
+## Rules
+
+- `docs/stories/` is the mirror in tracker mode, not the source. Changes made there are pushed; changes made in the
+  tracker are pulled.
+- The tracker leads on conflict; the local file is backed up, never silently lost.
+- Story labels must not start with the management prefix (`kataster` / `kataster-…`); those are owned by the sync.
+- `ST-NNN` is stable. Do not renumber, do not change `external` by hand, do not edit `BACKLOG.md`.
+- Reviews and open questions are local artifacts – do not push them.
+- Report missing access (no `gh`, no MCP server, no transition) and let the user decide.

package/.claude/skills/backlog/scripts/backlog-pull.ts

@@ -0,0 +1,45 @@
+/**
+ * Pulls tracker changes into the local mirror.
+ *
+ *   GitHub  deterministic, via `gh`
+ *   Jira    requires the issue data the agent fetched through MCP: `--from <issues.json>`
+ *
+ * Usage: node backlog-pull.ts [--from <jira-issues.json>]
+ */
+import { readFileSync } from "node:fs";
+import { loadBacklogConfig } from "../../../lib/config.ts";
+import { pullGithub } from "../../../lib/backlog-github.ts";
+import { jiraImport } from "../../../lib/backlog-jira.ts";
+
+const cfg = loadBacklogConfig();
+const fromIndex = process.argv.indexOf("--from");
+const from = fromIndex >= 0 ? process.argv[fromIndex + 1] : "";
+
+if (cfg.provider === "local") {
+  console.log("Backlog: local – docs/stories/ is the backlog, nothing to pull.");
+  process.exit(0);
+}
+if (cfg.provider === "jira" && !from) {
+  console.error(
+    "Backlog: jira is reached through mcp-atlassian, which only the agent can call.\n" +
+      "  Fetch the issues with jira_search/jira_get_issue, write them as JSON, then:\n" +
+      "  node .claude/skills/backlog/scripts/backlog-pull.ts --from <issues.json>",
+  );
+  process.exit(2);
+}
+
+try {
+  if (cfg.provider === "github") {
+    const report = pullGithub(cfg);
+    for (const line of report.lines) console.log(line);
+  } else {
+    const raw = JSON.parse(readFileSync(from, "utf8"));
+    const issues = Array.isArray(raw) ? raw : raw.issues ?? raw.values ?? raw.results ?? [];
+    const report = jiraImport(cfg, issues);
+    for (const line of report.lines) console.log(line);
+  }
+  process.exit(0);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/.claude/skills/backlog/scripts/backlog-push.ts

@@ -0,0 +1,38 @@
+/**
+ * Publishes local stories to the tracker.
+ *
+ *   GitHub  deterministic, via `gh`
+ *   Jira    cannot be done from a script – MCP is agent-only. This prints the exact next step and exits 2.
+ *
+ * Usage: node backlog-push.ts [ST-NNN ...]
+ */
+import { loadBacklogConfig } from "../../../lib/config.ts";
+import { pushGithub } from "../../../lib/backlog-github.ts";
+
+const ids = process.argv.slice(2).filter((arg) => /^ST-\d+$/i.test(arg));
+const cfg = loadBacklogConfig();
+
+if (cfg.provider === "local") {
+  console.log("Backlog: local – the story files are the backlog, nothing to push.");
+  process.exit(0);
+}
+if (cfg.provider === "jira") {
+  const scope = ids.length ? ` ${ids.join(" ")}` : "";
+  console.error(
+    "Backlog: jira is reached through mcp-atlassian, which only the agent can call.\n" +
+      `  1. node .claude/skills/backlog/scripts/jira-plan.ts${scope}\n` +
+      "  2. Execute every action with the mcp-atlassian tools.\n" +
+      "  3. node .claude/skills/backlog/scripts/jira-record.ts --from <results.json>\n" +
+      "  4. Run jira-plan.ts again to create the issue links.",
+  );
+  process.exit(2);
+}
+
+try {
+  const report = pushGithub(cfg, ids);
+  for (const line of report.lines) console.log(line);
+  process.exit(0);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}