projectstore-codex 0.0.1 → 0.28.2

package/node_modules/projectstore/scripts/worktree.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// projectstore — worktree.mjs
+// Answers one question: is this project an unbound git worktree of a checkout
+// that IS bound, and therefore able to adopt its binding?
+//
+// `.gitignore` ignores `.claude/`, so a worktree created from a bound checkout
+// starts with no projectstore.json: the hooks run, find nothing, and every
+// /projectstore:* command is dead there. That is ADR decision 12 — the cheap,
+// independent half of the parallel-session problem.
+//
+// Compute-only: spawns git, reads config files, writes nothing. The write path
+// is /projectstore:bind --inherit, approval-gated like every other write.
+
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { projectRoot, readConfigAt, truncFront, PATH_CELL } from "./lib.mjs";
+import { gitIn } from "./diff-refs.mjs";
+
+// SessionStart is user-facing and budgets its gather in hundreds of
+// milliseconds; diff-refs' 15 s batch default would be fifteen seconds of a
+// hung session start.
+const GIT_TIMEOUT_MS = 2000;
+
+const git = (cwd, args) => gitIn(cwd, args, { timeout: GIT_TIMEOUT_MS });
+
+const trim = (s) => (typeof s === "string" ? s.trim() : null);
+
+// Every branch returns every field. A caller reading a field that only exists on
+// the happy path throws, and a hook swallows that into silence — which looks
+// exactly like the mechanism deciding it had nothing to say.
+function record(state, worktree, mainCheckout, vaultPath) {
+  return { state, worktree, mainCheckout, vaultPath };
+}
+
+// The main checkout behind a linked worktree.
+//
+// `dirname(<git-common-dir>)` is right for an ordinary repository and WRONG for
+// one created with --separate-git-dir, where the common dir sits outside any
+// checkout — the vault on this machine has exactly that shape, and there both
+// this and `git worktree list` name the git directory rather than a checkout.
+//
+// So the candidate is never trusted. Note what confirmation has to mean:
+// `--show-toplevel` answering only proves the candidate sits inside *a* working
+// tree, which is not the same as being the main checkout of *this* repository —
+// and when a separate git dir happens to live inside an unrelated repository,
+// that weaker check names the stranger and we would offer its vault. Identity is
+// therefore confirmed by asking the candidate for its own common dir and
+// requiring it to be the one we started from. Not knowing yields null, and null
+// must never produce an offer.
+function mainCheckoutOf(commonDir) {
+  const candidate = dirname(commonDir);
+  const top = trim(git(candidate, ["rev-parse", "--path-format=absolute", "--show-toplevel"]));
+  if (!top) return null;
+  const topCommon = trim(git(top, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+  return topCommon === commonDir ? top : null;
+}
+
+export function resolveBinding(projectDir = projectRoot()) {
+  // A bound project has nothing to ask, so it never pays for a git spawn. The
+  // `worktree` field therefore means "detected as a linked worktree", and
+  // detection only runs when unbound — `false` here is "not asked", not "no".
+  if (readConfigAt(projectDir)) return record("bound", false, null, null);
+
+  const gitDir = trim(git(projectDir, ["rev-parse", "--path-format=absolute", "--git-dir"]));
+  const commonDir = trim(git(projectDir, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+  // Git missing (ENOENT → status null) and a non-repository (exit 128) both land
+  // here, and both are ordinary unbound projects with the ordinary advice.
+  if (!gitDir || !commonDir) return record("unbound", false, null, null);
+
+  // --path-format=absolute matters: in a main checkout the common dir comes back
+  // as the relative `.git`, and dirname() of that is `.`.
+  if (gitDir === commonDir) return record("unbound", false, null, null);
+
+  const main = mainCheckoutOf(commonDir);
+  if (!main) return record("unbound", true, null, null);
+
+  const parent = readConfigAt(main);
+  if (!parent || !parent.vault_path) return record("unbound", true, main, null);
+
+  return record("inheritable", true, main, parent.vault_path);
+}
+
+// Pure: record in, block out. Both interpolated paths are user-controlled and
+// unbounded, so both go through the same cell truncation the sibling warning
+// uses — the composed SessionStart value is capped and this is one of its terms.
+export function bindingOfferText(b) {
+  return [
+    "# projectstore — this worktree is not bound",
+    "",
+    "This checkout has no `.projectstore/projectstore.json`, so `/projectstore:*` commands",
+    "cannot run here. The checkout it was forked from is bound:",
+    "",
+    `- main checkout: \`${truncFront(String(b.mainCheckout), PATH_CELL)}\``,
+    `- its vault: \`${truncFront(String(b.vaultPath), PATH_CELL)}\``,
+    "",
+    "Run `/projectstore:bind --inherit` to adopt that binding. It copies the binding",
+    "only — the vault is shared and unchanged, and no session state travels with it.",
+    "",
+    "",
+  ].join("\n");
+}
+
+function main() {
+  process.stdout.write(JSON.stringify(resolveBinding(projectRoot()), null, 2) + "\n");
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/node_modules/projectstore/skills/projectstore-decision-detector/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: projectstore-decision-detector
+description: When the user makes or accepts an architectural/technical decision (choosing between alternatives, locking in a pattern, picking a library or tool, settling a trade-off), suggest capturing it as an ADR via /projectstore:adr. Never write to the vault directly — only suggest, and let the /projectstore:adr command handle approval.
+---
+
+# Decision detector
+
+You watch for **decision moments** in the conversation:
+
+- The user explicitly chose between two or more alternatives ("we'll go with X over Y").
+- A trade-off was settled ("let's accept the latency hit for stronger consistency").
+- A library, framework, pattern, or tool was committed to.
+- An architectural property was fixed (auth model, storage layout, transport protocol, deployment topology).
+
+## When you detect such a moment
+
+1. **Check if a vault is bound**: confirm `.projectstore/projectstore.json` exists in the current project. If not, do nothing — this skill is silent without binding.
+
+2. **Check `active_skills` in the config**. If `false`, do nothing.
+
+3. **Check for an existing ADR** on the same topic first:
+   ```bash
+   grep -rli "<key-term>" "<vault>/adr/" 2>/dev/null
+   ```
+   If a matching ADR exists, suggest **updating** it (Read + propose Edit through normal approval flow) rather than creating a duplicate.
+
+4. **Suggest, do not act**. Write one short message to the user:
+
+   > 💡 *This looks like a decision worth recording. Want me to draft an ADR? Run `/projectstore:adr "<your-title>"` or just say "yes" and I'll fire it with the title above.*
+
+   Propose a concise title (≤80 chars), e.g. *"Use BFF pattern for OIDC"*.
+
+5. **Wait for explicit user confirmation** before invoking `/projectstore:adr`. Never auto-execute.
+
+## Anti-patterns (do not do)
+
+- Don't suggest an ADR for trivial choices (variable names, formatting).
+- Don't suggest an ADR more than once per detected decision — if the user said "not now", drop it for the session.
+- Don't write any vault file directly from this skill. ADR creation always goes through `/projectstore:adr` which gates writes with `AskUserQuestion`.
+- Don't change the ADR template, status, or numbering — that's `/projectstore:adr`'s job.

package/node_modules/projectstore/skills/projectstore-peer-reviewer/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: projectstore-peer-reviewer
+description: After a new projectstore artifact is created via /projectstore:adr, /projectstore:research, or /projectstore:epic (and similar generative commands), suggest running /projectstore:review <path> to peer-review the artifact with a fresh critic agent before it's committed. Only suggest for artifact kinds whose checklist has default_review=true. Never auto-execute — always ask first.
+---
+
+# Peer-reviewer skill
+
+You watch for moments where a new artifact has just been written by a `/projectstore:*` command and could benefit from peer review **before** it lands in git.
+
+## Trigger conditions
+
+After a successful invocation of any of:
+
+- `/projectstore:adr` — new ADR created
+- `/projectstore:research` — new research note created
+- `/projectstore:epic` — new epic created
+
+(See `scaffold/checklists.json` — kinds with `default_review: true`.)
+
+## What to do
+
+1. **Confirm a vault is bound** (`.projectstore/projectstore.json` exists). Otherwise stay silent.
+2. **Confirm `active_skills: true`** in config.
+3. **Read the frontmatter** of the freshly created file. If `review_status: pending` — eligible for suggestion. If `review_status: reviewed` or `n/a` — do nothing.
+4. **Suggest, do not act**. One short message:
+
+   > 🔍 *Want me to peer-review this <kind> before committing? `/projectstore:review <path>` spawns a fresh critic that hasn't seen our conversation — different angle, often catches missing alternatives or unstated assumptions.*
+
+5. **Wait for explicit user confirmation** before invoking `/projectstore:review`. Never auto-execute.
+
+6. If the user declines, drop it for this session — don't ask again for the same file.
+
+## Anti-patterns
+
+- Don't suggest review for kinds with `default_review: false` (meeting, runbook, story, concept). User can still invoke `/projectstore:review` manually if they want.
+- Don't suggest review more than once per artifact per session.
+- Don't run the review yourself — `/projectstore:review` handles the critic spawn, the approval flow, and the frontmatter update.
+- Don't reframe the suggestion as "this might need improvement" — that's sycophancy in disguise. The framing is "fresh-eyes pass", not "your work has problems".

package/node_modules/projectstore/skills/projectstore-story-completion/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: projectstore-story-completion
+description: When the user finishes work that maps to a known story (story file exists in epics/<id>/stories/) — all acceptance criteria appear satisfied, code merged, tests passing — suggest updating the story's frontmatter status (e.g. planned → in-progress → review → done) and regenerating the kanban. Never write to vault directly without /projectstore:* commands and explicit approval.
+---
+
+# Story completion / status update suggester
+
+You watch for moments where the conversation indicates progress on a known story:
+
+- A merge/PR was completed for work tied to a story.
+- The user said "story-001 is done" or similar.
+- All checkboxes in a story's `Decomposition` or `Acceptance Criteria` got ticked.
+- The user moved between phases of an epic (e.g., "moving to integration testing now").
+
+## What to do
+
+1. **Confirm a vault is bound** (`.projectstore/projectstore.json` exists). Otherwise stay silent.
+2. **Confirm `active_skills` is true** in config.
+3. **Try to identify the story file**: search `<vault>/epics/*/stories/` for files matching keywords from the conversation. If multiple candidates, ask the user which one via plain text (not AskUserQuestion — keep it light).
+4. **Propose the right transition**:
+   - Work about to **start** on a story → suggest `/projectstore:story plan <story>`
+     (writes the Implementation Plan, stamps `started_at`, moves to in-progress).
+   - Story looks **finished** → suggest `/projectstore:story close <story>`
+     (Final Summary, evidence suffixes on acceptance criteria, stamps
+     `closed_at`, moves to done) — and, before closing, the `reviewer` agent,
+     whose proposed `code_refs` come from `scripts/diff-refs.mjs` anchored at
+     the story's `started_at`.
+   - Intermediate move (e.g. → review) → propose the frontmatter status Edit
+     as before:
+
+   > 📋 *Looks like `epics/RECPLAT-333/stories/story-007-feature-pipeline.md` is moving to `review`. Want me to update its frontmatter and refresh the kanban?*
+
+5. **Do not modify the file** until the user says yes. When they confirm a
+   plain status move:
+   - Read the story file.
+   - Propose an Edit that changes `status:` and `updated:` in the frontmatter
+     (plus `started_at` when first entering in-progress outside the plan gate,
+     `closed_at` when moving to done outside the close gate — timestamps must
+     not be lost just because the gate was skipped; ISO-8601).
+   - Use AskUserQuestion to confirm the Edit before applying.
+   - After Edit, suggest running `/projectstore:kanban` to refresh the board.
+
+## Anti-patterns
+
+- Don't pick a story automatically — always ask if uncertain.
+- Don't bulk-update multiple stories in one go without per-file approval.
+- Don't change anything beyond `status`, `updated` and the lifecycle
+  timestamps (`started_at` / `closed_at`). Section content (plan, summary,
+  evidence) belongs to the `/projectstore:story plan|close` gates.
+- Don't trigger after every code change — only on clear completion signals.

package/node_modules/projectstore/skills/projectstore-vault-communication/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: projectstore-vault-communication
+description: When communicating with the user about anything stored in the projectstore vault (epics, stories, ADRs, research, kanban, backlog), reference every artifact by its human title from frontmatter — never by session-invented shorthand. Name the parent epic for stories; include status/priority when discussing state or plans. Applies by default in bound projects to summaries, plans, and progress reports.
+---
+
+# Vault-native communication
+
+Vault artifacts are the shared vocabulary between the user, this session, *other*
+sessions, and the post-compact agent. A title written in a file can be grepped,
+linked, and recognized in Obsidian six months from now. A label invented mid-session
+("T3", "P0-1", "the doctor story") dies with the session that coined it — and forces
+the user to cross-reference your earlier messages just to know what you meant.
+
+## Rules
+
+### 1. Call artifacts by their `title:`, not by number or slug
+
+```
+bad:  story-004 is done, story-005 is next
+good: "Unicode-aware slugify to unbreak ru filenames" (story-004) is done;
+      "YAML-escape template variables" (story-005) is next
+```
+
+The id in parentheses is welcome — as a *supplement*, never the only handle.
+
+### 2. Stories always carry their epic
+
+First mention in a message names both; after that a short form is fine.
+
+```
+bad:  let's start with story-001
+good: let's start with "doctor: deterministic consistency lint" (PS-IMPROVE › story-001)
+then: doctor lint story (story-001)
+```
+
+### 3. Resolution order for the name
+
+`title:` from frontmatter → filename without extension → relative path.
+Never a bare number ("story 3", "the second ADR").
+
+### 4. Plans and progress carry status (and priority when it matters)
+
+```
+bad:  the epic is moving along
+good: epic "Reliability by construction" (PS-IMPROVE, p0): 2 of 6 stories done,
+      "reconcile: re-derive kanban and indexes from frontmatter" is in-progress
+```
+
+### 5. Document-internal codes stay inside their document
+
+If a note defines its own legend (e.g. topics T1–T6 in a research note), those codes
+are fine *within that document*. In chat, expand them on first use in every message:
+
+```
+bad:  I suggest T3+T4 first, then T2/T6, T5, T1
+good: I suggest starting with the agent-roster topics — "which new roles fit" and
+      "rename projectstore-critic → critic" (topics 3–4 in research "v0.13 Design
+      Questions: Statusline, Agents, Doctor, Model Config") — their naming decisions
+      leak into every other ADR's wording
+```
+
+### 6. Link the file when the user may want to open it
+
+`epics/PS-IMPROVE/stories/story-001-doctor-deterministic-consistency-lint.md` —
+paths are clickable in the terminal and resolvable in Obsidian. Title first,
+path as the pointer.
+
+## When this applies
+
+- Any user-facing message *about vault contents*: status summaries, "what's next",
+  planning discussions, review results, kanban talk, backlog updates.
+- Artifacts you write into the vault: related-links and prose references use titles
+  and wiki-links, not invented codes.
+
+## When it does NOT apply
+
+- Short confirmations ("done", "committing now") with no artifact references.
+- Raw command output, code blocks, file paths inside tool calls.
+- Frontmatter ids themselves (`id: story-001` stays an id — that's its job).
+
+## Anti-patterns
+
+- ❌ "T3+T4 first, then T2/T6" — bare document-internal codes leaked into chat.
+- ❌ "P0-1 through P0-6 are specced" — priority labels used as names.
+- ❌ "the doctor story" when two doctor-shaped items exist (install diagnostics vs
+  vault consistency lint) — ambiguity is exactly what titles prevent.
+- ❌ Renaming an artifact in conversation ("the reliability epic" for an epic titled
+  "Reliability by construction" is fine as a gloss — but don't *invent* a different
+  working title and keep using it).
+
+## Activation
+
+Default-on when a vault is bound (`.projectstore/projectstore.json` exists) and
+`active_skills` is not `false` — same gating as the other passive skills. Silent
+otherwise. This skill changes *how you phrase things*; it never writes files and
+never blocks an action.

package/node_modules/projectstore/templates/claude-md-block.md.tmpl

@@ -0,0 +1,26 @@
+<!-- projectstore:agents v4 (managed by projectstore — edit outside markers) -->
+## projectstore agents
+
+- **A feature-sized request opens a vault artifact before it opens an editor.**
+  Analysis → placement (which epic, which story) → an ADR and/or spec when the
+  "how" is non-trivial → `projectstore:critic` → only then implementation →
+  `projectstore:reviewer`. "Feature-sized" is not a judgement about how the
+  request was phrased — it is about what the work touches: if you are about to
+  write across several source files, open the story first.
+- **Report instruction conflicts; do not arbitrate them.** If a session-level or
+  harness-level instruction contradicts this block, say so and ask which wins.
+  Resolving it silently is how the contradiction becomes invisible to the person
+  who could have settled it.
+- When spawning any agent below, resolve its model from
+  `.projectstore/harness/<harness>.json` → `agents.per_agent.<name>.model ?? agents.default.model`,
+  where `<name>` is the **bare** agent name (`critic` for `projectstore:critic`),
+  and pass it as the spawn's model parameter. No key — pass nothing.
+- After authoring or revising any vault artifact (ADR/research/epic/story) or
+  design proposal: run the `projectstore:critic` agent on it before treating it final.
+- Before implementing an epic/story: consult `projectstore:planner` — it plans
+  against how prior epics map to the codebase (`code_refs`).
+- After writing code, before commit / story-done: run `projectstore:reviewer` —
+  it verifies the diff actually closes the story's acceptance criteria.
+- When discussing vault contents, reference artifacts by their frontmatter
+  `title:` (with their parent epic), never by session-invented shorthand.
+<!-- /projectstore:agents -->

package/node_modules/projectstore/templates/de/adr.md.tmpl

@@ -0,0 +1,67 @@
+---
+type: adr
+id: {{id_json}}
+title: {{title_json}}
+status: proposed
+date: {{date}}
+authors: [{{author_json}}]
+tags: {{tags}}
+external_refs: {}
+supersedes: null
+superseded_by: null
+review_status: pending
+reviewed_at: null
+---
+
+# {{title}}
+
+| Feld | Wert |
+|---|---|
+| **Status** | proposed |
+| **Datum** | {{date}} |
+| **Autoren** | {{author}} |
+
+---
+
+## Kontext
+
+<!-- Welche Kräfte wirken? Warum ist die Entscheidung jetzt nötig? -->
+
+## Entscheidung
+
+<!-- Die Entscheidung selbst, klar und knapp formuliert. -->
+
+## Begründung
+
+<!-- Warum diese Entscheidung und nicht die Alternativen. Nummerierte Gründe bevorzugt. -->
+
+## Betrachtete Alternativen
+
+### Alternative A: {{alternative_a_name}}
+
+**Vorteile**:
+-
+
+**Nachteile**:
+-
+
+**Abgelehnt, weil**:
+
+## Konsequenzen
+
+**Positiv**:
+-
+
+**Negativ / Kompromisse**:
+-
+
+**Was sich in Code / Prozess ändert**:
+-
+
+## Referenzen
+
+-
+
+---
+
+*Zuletzt aktualisiert: {{date}}*

package/node_modules/projectstore/templates/de/concept.md.tmpl

@@ -0,0 +1,43 @@
+---
+type: concept
+slug: {{slug_json}}
+title: {{title_json}}
+status: draft
+date: {{date}}
+authors: [{{author_json}}]
+tags: {{tags}}
+---
+
+# {{title}}
+
+## Was ist das
+
+<!-- Definition in einem Absatz. -->
+
+## Warum es zählt
+
+<!-- Kontext, welches Problem dieses Konzept adressiert. -->
+
+## Wie es funktioniert
+
+<!-- Mechanismus, Komponenten, Zusammenspiel. -->
+
+## Wann einsetzen / nicht einsetzen
+
+**Einsetzen, wenn**:
+-
+
+**Nicht einsetzen, wenn**:
+-
+
+## Verwandtes
+
+-
+
+## Referenzen
+
+-
+
+---
+
+*Zuletzt aktualisiert: {{date}}*

package/node_modules/projectstore/templates/de/epic.md.tmpl

@@ -0,0 +1,59 @@
+---
+type: epic
+id: {{id_json}}
+title: {{title_json}}
+status: planned
+priority: p2
+created: {{date}}
+updated: {{date}}
+external_refs: {}
+tags: {{tags}}
+code_refs: []
+review_status: pending
+reviewed_at: null
+---
+
+# {{id}}: {{title}}
+
+| Feld | Wert |
+|---|---|
+| **Status** | planned |
+| **Priorität** | p2 |
+| **Erstellt** | {{date}} |
+| **Aktualisiert** | {{date}} |
+
+---
+
+## Ziel
+
+<!-- Wie sieht Erfolg für dieses Epic aus? -->
+
+## Kontext
+
+<!-- Hintergrund, Motivation, warum das jetzt wichtig ist. -->
+
+## Stories
+
+| Story | Status | Beschreibung |
+|-------|--------|--------------|
+| [story-001](./stories/story-001.md) | planned |  |
+
+## Erwartete Ergebnisse
+
+- [ ]
+
+## Abhängigkeiten
+
+-
+
+## Offene Fragen
+
+- [ ]
+
+## Verwandtes
+
+-
+
+---
+
+*Zuletzt aktualisiert: {{date}}*

package/node_modules/projectstore/templates/de/folder-readme.md.tmpl

@@ -0,0 +1,14 @@
+# {{folder_name}}
+
+{{folder_description}}
+
+## Index
+
+<!-- projectstore hält diesen Index aktuell, wenn Einträge über die /projectstore:*-Kommandos hinzukommen. -->
+
+| Datei | Titel | Status | Datum |
+|-------|-------|--------|-------|
+
+---
+
+*Verwaltet vom projectstore-Plugin. Manuelle Änderungen außerhalb der Index-Tabelle bleiben erhalten.*

package/node_modules/projectstore/templates/de/kanban.md.tmpl

@@ -0,0 +1,36 @@
+---
+
+kanban-plugin: board
+projectstore: derived
+generated_at: {{generated_at}}
+
+---
+
+## Backlog
+
+{{backlog_items}}
+
+## Zu erledigen
+
+{{todo_items}}
+
+## In Arbeit
+
+{{in_progress_items}}
+
+## Review
+
+{{review_items}}
+
+## Fertig
+
+{{done_items}}
+
+
+
+
+%% kanban:settings
+```
+{"kanban-plugin":"board","list-collapse":[false,false,false,false,false]}
+```
+%%

package/node_modules/projectstore/templates/de/meeting.md.tmpl

@@ -0,0 +1,38 @@
+---
+type: meeting
+date: {{date}}
+slug: {{slug_json}}
+title: {{title_json}}
+attendees: []
+tags: {{tags}}
+---
+
+# {{date}} — {{title}}
+
+## Teilnehmende
+
+-
+
+## Agenda
+
+-
+
+## Notizen
+
+###
+
+## Entscheidungen
+
+- [ ]
+
+## Aufgaben
+
+- [ ] **{{author}}**:
+
+## Nachfassen
+
+-
+
+---
+
+*Notiert von: {{author}}*

package/node_modules/projectstore/templates/de/research.md.tmpl

@@ -0,0 +1,47 @@
+---
+type: research
+slug: {{slug_json}}
+title: {{title_json}}
+status: draft
+date: {{date}}
+authors: [{{author_json}}]
+tags: {{tags}}
+review_status: pending
+reviewed_at: null
+---
+
+# {{title}}
+
+## Fragestellung
+
+<!-- Was wollen wir herausfinden? -->
+
+## Kurzfassung (TL;DR)
+
+<!-- Antwort in einem Absatz. Nach dem Hauptteil ausfüllen. -->
+
+## Vorgehen
+
+<!-- Wie wir untersucht haben: Quellen, Experimente, Benchmarks. -->
+
+## Ergebnisse
+
+###
+
+## Vergleich
+
+| Option | Vorteile | Nachteile |
+|--------|----------|-----------|
+|        |          |           |
+
+## Fazit
+
+<!-- Was wir empfehlen und warum. -->
+
+## Referenzen
+
+-
+
+---
+
+*Zuletzt aktualisiert: {{date}}*