projectstore-codex 0.0.1 → 0.28.1

package/node_modules/projectstore/hooks/session-start.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+// projectstore — SessionStart hook.
+// 1. Reads .projectstore/projectstore.json from the project root. If absent or
+//    auto_inject=false, silently no-ops.
+// 2. Registers this session in <vault>/.projectstore/sessions/<id>.json,
+//    keyed by Claude's own session_id from hook stdin. Cleans stale
+//    entries (>24h). Detects other active sessions (mtime < 30min) and
+//    appends a warning so the agent knows it is not alone on this vault.
+// 3. Injects a NAVIGATION SKELETON — the layout's folders, what each is for,
+//    what is in flight, and the order to descend in. Not a copy of the vault:
+//    it used to inject every folder README, which on a real vault exceeded the
+//    10,000-character hook cap and was written to a file the agent then had to
+//    open. Bounded and O(1) in vault size by construction.
+
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import {
+  readConfig,
+  gatherVaultFacts,
+  renderVaultSkeleton,
+  writeSession,
+  readActiveSessions,
+  cleanupStaleSessions,
+  readStdinJson,
+  adoptHookInput,
+  projectRoot,
+  layoutPaths,
+  pickExisting,
+  activeHarnessId,
+  ensureRuntimeDir,
+  syncStatusLine,
+  cleanupStaleSessionState,
+  armReminder,
+  truncEnd,
+  truncFront,
+  PATH_CELL,
+  ERROR_CELL,
+  TITLE_CELL,
+} from "../scripts/lib.mjs";
+import { runStartupChecks } from "../scripts/doctor.mjs";
+import { resolveBinding, bindingOfferText } from "../scripts/worktree.mjs";
+
+// The marker lives under the harness's state directory; a legacy marker at
+// .claude/.projectstore-welcomed still counts while the window is open.
+function welcomedMarkerPath(proj) {
+  const p = layoutPaths(proj);
+  return pickExisting(p.welcomed(activeHarnessId()), p.legacy.welcomed);
+}
+function welcomedMarkerWritePath(proj) {
+  return layoutPaths(proj).welcomed(activeHarnessId());
+}
+
+// One-time orientation packet shown when projectstore first loads in a project.
+// Idempotent via a marker file at <project>/.claude/.projectstore-welcomed.
+// The welcome fires once per project, and a project can already be bound when
+// it does — a fresh install into a project someone bound first is the ordinary
+// case, not a corner (measured 2026-09-06: the first line a new user read told
+// them to bind a project whose vault the install preview had just named). So
+// the one instruction it carries branches on the binding; everything else is
+// the same message.
+function buildWelcome(cfg = null) {
+  const start = cfg && cfg.vault_path
+    ? `**Already bound**: this project's vault is \`${truncFront(String(cfg.vault_path), PATH_CELL)}\`. Ask for what you want — the agent picks up commands like \`/projectstore:adr\` and \`/projectstore:epic\` from the conversation, and you approve every write. If the vault has no folders yet, \`/projectstore:scaffold\` lays them out.`
+    : "**To start using it**: run `/projectstore:bind <vault-path>` and point it at an Obsidian vault (or any folder). After that, the agent will pick up commands like `/projectstore:adr` and `/projectstore:epic` from the conversation; you only approve the writes.";
+  return [
+    "# 👋 projectstore is loaded for the first time in this project",
+    "",
+    "**What it does**: turns the conversation's decisions into a structured Obsidian-friendly markdown vault — ADRs, epics, stories, runbooks, research. Agent-maintained, you approve every write.",
+    "",
+    start,
+    "",
+    "**About future updates**: Claude Code does NOT auto-update third-party marketplaces by default. To get notified of new releases (v0.7+):",
+    "1. Open `/plugin` → **Marketplaces** tab.",
+    "2. Find **SmartAndPoint**.",
+    "3. Toggle **auto-update** on.",
+    "",
+    "Without it, you'd run `/plugin marketplace update SmartAndPoint` manually. See https://github.com/SmartAndPoint/ProjectStore#updates for details.",
+    "",
+    "_This message appears once per project._",
+    "",
+    "_If projectstore helps you ship, a [GitHub star](https://github.com/SmartAndPoint/ProjectStore) helps others discover it. No pressure._",
+    "",
+  ].join("\n");
+}
+
+function showWelcomeOnce(proj, cfg = null) {
+  if (existsSync(welcomedMarkerPath(proj))) return "";
+  const text = buildWelcome(cfg);
+  try {
+    const marker = welcomedMarkerWritePath(proj);
+    ensureRuntimeDir(proj); // .projectstore/.gitignore ignores state/; the marker is not a session file
+    mkdirSync(dirname(marker), { recursive: true });
+    writeFileSync(marker, new Date().toISOString() + "\n", "utf8");
+  } catch {}
+  return text;
+}
+
+// Writes the payload and ends the process — after the flush, never before.
+//
+// The gather races its reads against a timer, so when the timer wins there are
+// reads still outstanding, and an evicted file could hold the event loop open
+// long past the budget the user is actually waiting on. Exiting here caps the
+// hook's wall time at that budget. The callback is the whole safety of it:
+// process.exit does not flush pending pipe writes, so exiting on the line after
+// a write is how a payload gets truncated.
+function emit(additionalContext, systemMessage) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext,
+    },
+  };
+  if (systemMessage) out.systemMessage = systemMessage;
+  process.stdout.write(JSON.stringify(out) + "\n", () => process.exit(0));
+}
+
+// Contract 3 — capped at 5 like the in-flight list, and for the same reason.
+// The warning costs ~138 characters per sibling on top of a 748-character
+// frame, so an uncapped list breaches the 10,000 composed cap at roughly 32
+// concurrent sessions. That bound is empirical, and an empirical bound is what
+// contract 1 exists to forbid; the cap makes it structural instead.
+const SIBLING_CAP = 5;
+
+function buildOthersWarning(others) {
+  const lines = [
+    "",
+    "---",
+    "",
+    `## ⚠️ Multi-session warning — ${others.length} other projectstore session(s) active on this vault`,
+    "",
+    "Another Claude Code session is currently working on the same vault.",
+    "Active session(s):",
+    "",
+  ];
+  for (const s of others.slice(0, SIBLING_CAP)) {
+    lines.push(
+      `- project: \`${truncFront(String(s.project_root ?? ""), PATH_CELL)}\`` +
+        // Free text from a session file this process never wrote, rendered five
+        // times over. The last unbounded term in the composed value: `last_active`
+        // is a real Date, the layout fields are plugin-bundled, counts are numbers.
+        ` — started ${truncEnd(String(s.started_at ?? ""), TITLE_CELL)},` +
+        ` last activity ${s.last_active.toISOString()}`,
+    );
+  }
+  if (others.length > SIBLING_CAP) {
+    lines.push(`- …and ${others.length - SIBLING_CAP} more — run \`/projectstore:status\``);
+  }
+  lines.push(
+    "",
+    "**Before creating new ADRs / epics / stories / research:**",
+    "1. Run `/projectstore:search <topic-keywords>` to check for in-flight artifacts on the same topic.",
+    "2. Run `/projectstore:status` to see what artifacts have been touched recently.",
+    "3. After creation, the plugin re-checks file existence right before write — collisions are detected, but topic / number reservation across sessions is on you and the other agent to coordinate.",
+    "",
+  );
+  return lines.join("\n");
+}
+
+async function main() {
+  // The payload before the project. readConfig() resolves through
+  // projectRoot(), so anything read above this line answers for whatever
+  // directory the process started in — silently, on any harness that exports
+  // no project-dir variable. Read once: fd 0 is empty on a second read, and
+  // `sid` below is this object's, not a re-read.
+  const input = adoptHookInput(readStdinJson());
+  const sid = input?.session_id || null;
+
+  const cfg = readConfig();
+  const proj = projectRoot();
+  // Asked only on the unbound path. A bound project must not spend a git
+  // subprocess at every session start on a question it has already answered;
+  // an unbound one that is not a worktree pays a single ~10 ms probe.
+  let binding = null;
+  if (!cfg) {
+    try { binding = resolveBinding(proj); } catch {}
+  }
+  const welcome = showWelcomeOnce(proj, cfg);
+  // The person's channel carries one instruction, and it has to be the right
+  // one: a bound project is told what it is bound to, not to bind again.
+  const welcomeSystemMessage = welcome
+    ? (cfg && cfg.vault_path
+      ? `👋 projectstore: first-run welcome shown. Bound to ${cfg.vault_path}. See /plugin → Marketplaces to enable auto-update.`
+      : "👋 projectstore: first-run welcome shown. Start with /projectstore:bind <vault-path>. See /plugin → Marketplaces to enable auto-update.")
+    : null;
+
+  if (!cfg) {
+    // The offer goes ahead of the welcome, not after it: a fresh worktree has no
+    // welcome marker either, so the first-run welcome fires here too — and its
+    // advice, to bind and point at a vault, is the wrong move for a checkout
+    // whose parent is already bound. Ordering is the cheap fix; the small
+    // redundancy is accepted rather than papered over with copy that will rot.
+    const offer = binding && binding.state === "inheritable" ? bindingOfferText(binding) : "";
+    const offerSystemMessage = offer
+      ? "projectstore: this worktree is unbound — /projectstore:bind --inherit adopts the binding of the checkout it was forked from."
+      : null;
+    const body = offer + (welcome || "");
+    if (body) {
+      // The person's channel carries ONE instruction. Joining both would put
+      // "bind --inherit" and "bind <vault-path>" in one line with no ordering
+      // cue — not redundancy but a contradiction, in the channel that gets read
+      // fastest. The body still carries the welcome for the agent.
+      return emit(body, offerSystemMessage || welcomeSystemMessage);
+    }
+    process.exit(0);
+  }
+
+  // Opt-in status line: keep settings.local.json pointed at this plugin
+  // version's statusline.mjs (self-heals on update). Best-effort; a settings
+  // write must never break session-context injection.
+  try { syncStatusLine(cfg, proj); } catch {}
+  // Statusline-feature housekeeping, like syncStatusLine — must run even when
+  // auto_inject=false (touch-session writes pointers regardless of it).
+  try { cleanupStaleSessionState(proj); } catch {}
+
+  // Arm BEFORE the auto_inject gate. The entry reminder's markers must be
+  // re-armed after a compaction whether or not this session injects context —
+  // an auto_inject=false session still writes code, and its reminder was
+  // discarded with the conversation just the same.
+  //
+  // `input` and `sid` are read at the top of main() now, because the project
+  // resolves from that payload; this block only consumes them.
+  //
+  // `compact` and `clear` are the two sources where the session id survives but
+  // the conversation does not, so a reminder already delivered is gone from
+  // context while its marker persists on disk. Arming lets it fire once more;
+  // the cap of two is enforced by the election, not here.
+  if (sid && (input?.source === "compact" || input?.source === "clear")) {
+    try { armReminder(proj, sid); } catch {}
+  }
+
+  if (cfg.auto_inject === false) {
+    if (welcome) return emit(welcome, welcomeSystemMessage);
+    process.exit(0);
+  }
+
+  // Contract 23, first half — the gather (and with it the activity read) runs
+  // BEFORE registration, so the continuity section sees the log exactly as the
+  // previous conversation left it. The exemption below is the other half: it
+  // protects the NEXT compaction, this ordering protects this one.
+  let facts = null;
+  let gatherError = null;
+  try {
+    facts = await gatherVaultFacts(cfg, { sessionId: sid, source: input?.source });
+  } catch (e) {
+    gatherError = e;
+  }
+
+  let warning = "";
+  // A bound vault that has vanished must not be silently recreated: ensureSessionsDir's
+  // recursive mkdir would manufacture it, and from the NEXT start the skeleton would
+  // assert eight rows of zeros and "nothing in progress" about a vault nobody
+  // scaffolded. The not-found shape has to survive more than one run to be worth
+  // anything (contract 17).
+  if (sid && !facts?.vaultMissing) {
+    try {
+      cleanupStaleSessions(cfg.vault_path, 24, sid);
+      writeSession(cfg.vault_path, sid, proj);
+      const others = readActiveSessions(cfg.vault_path, sid);
+      if (others.length > 0) warning = buildOthersWarning(others);
+    } catch (e) {
+      // Contract 3 — a raw `e.message` is free text and therefore unbounded;
+      // node's own filesystem errors already carry two full paths. Assigned
+      // here rather than appended: registration failure REPLACES the sibling
+      // warning, so the two cannot compound.
+      warning = `\n\n## projectstore: session registration failed\n\n${truncEnd(String(e.message), ERROR_CELL)}\n`;
+    }
+  }
+
+  // Cheap install-only doctor subset (ADR-005): one line, only when N > 0;
+  // aborted past its budget rather than reporting a false "clean".
+  let doctorMsg = null;
+  let offers = [];
+  try {
+    const r = runStartupChecks(cfg, proj);
+    if (r.skipped) {
+      doctorMsg = "projectstore doctor: startup checks skipped — run /projectstore:doctor";
+    } else if (r.count > 0) {
+      doctorMsg = `projectstore doctor: ${r.count} install issue(s) — run /projectstore:doctor`;
+    }
+    // Offers (doctor's OFFER_CHECKS): one-time steps a user should see once,
+    // e.g. the re-stamp after a plugin update — not issues, not silent.
+    offers = (r.offers || []).map((m) => `projectstore: ${m}`);
+  } catch {}
+  const systemMessage =
+    [welcomeSystemMessage, doctorMsg, ...offers].filter(Boolean).join(" · ") || null;
+
+  if (gatherError) {
+    emit(
+      welcome +
+        `# projectstore: vault load failed\n\n${truncEnd(String(gatherError.message), ERROR_CELL)}\n\nFix \`.projectstore/projectstore.json\` or run \`/projectstore:bind <path>\` again.`,
+      systemMessage,
+    );
+    return;
+  }
+  emit(welcome + renderVaultSkeleton(facts) + warning, systemMessage);
+}
+
+// A hook must never break session startup (contract 17): an unhandled rejection
+// in the async path would exit non-zero and surface as a hook failure to the
+// user, which is a worse outcome than a session with no orientation.
+main().catch(() => process.exit(0));

package/node_modules/projectstore/hooks/session-stop.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// projectstore — session-stop.mjs
+//
+// The entry reminder's fallback carrier (spec contract 14).
+//
+// The PostToolUse carrier reaches the main agent on its next own tool call.
+// Under a delegation-heavy configuration there may not be one: the main agent
+// hands the writing to subagents — whose calls count toward the score but are
+// never the audience — and then answers the user. Stop fires exactly there.
+//
+// Two things about Stop that shape this file:
+//
+//  * `additionalContext` on Stop CONTINUES the turn. So this hook must run the
+//    same create-then-emit election as the PostToolUse branch, not merely read
+//    the markers: a guard that only checks would emit, the turn would continue,
+//    the model would finish again, Stop would fire again — forever. Creating
+//    the marker before emitting is what makes the second firing impossible.
+//  * `stop_hook_active` is set while a Stop hook is already driving the turn.
+//    Honouring it is belt and braces; the election is the load-bearing guard.
+//
+// Not SubagentStop: it fires once per subagent and its continuation belongs to
+// the subagent, which is the actor that cannot open a story.
+//
+// Requires Claude Code 2.1.163+, where additionalContext on Stop is honoured.
+
+import {
+  readConfig,
+  readStdinJson,
+  adoptHookInput,
+  projectRoot,
+  entryScore,
+  readOpenStoryCache,
+  resolveOpenStory,
+  writeOpenStoryCache,
+  mayRemind,
+  electEmitter,
+  appendEntryLog,
+  entryReminderText,
+  ENTRY_THRESHOLD,
+} from "../scripts/lib.mjs";
+
+async function main() {
+  // The payload before the project: readConfig() resolves through
+  // projectRoot(), and on a harness that exports no project-dir variable the
+  // payload's cwd is the only answer better than this process's cwd. Read once
+  // — fd 0 is empty on a second read.
+  const input = adoptHookInput(readStdinJson());
+
+  const cfg = readConfig();
+  if (!cfg || cfg.guard === "off") return;
+
+  const sid = input?.session_id;
+  if (!sid) return;
+  if (input.stop_hook_active) return;
+  // Same audience rule as the tool-call carrier.
+  if (input.agent_id || input.agent_type) return;
+
+  const proj = projectRoot();
+  const score = entryScore(proj, sid);
+  if (score < ENTRY_THRESHOLD) return;
+  if (!mayRemind(proj, sid)) return;
+
+  let verdict = readOpenStoryCache(proj, sid);
+  if (verdict === null) {
+    verdict = await resolveOpenStory(cfg.vault_path);
+    writeOpenStoryCache(proj, sid, verdict);
+  }
+  // Nothing written to stdout yet, so exiting here cannot truncate anything.
+  if (verdict === "unknown") process.exit(0);
+  if (verdict !== false) return;
+
+  if (!electEmitter(proj, sid)) return;
+  appendEntryLog(proj, { at: new Date().toISOString(), session_id: sid, score, via: "Stop" });
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "Stop",
+      additionalContext: entryReminderText(score),
+    },
+  }) + "\n");
+}
+
+main().catch(() => {
+  // A hook must never break the user's turn.
+});

package/node_modules/projectstore/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "projectstore",
+  "version": "0.28.1",
+  "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
+  "keywords": [
+    "project-management",
+    "adr",
+    "epics",
+    "stories",
+    "kanban",
+    "obsidian",
+    "markdown",
+    "knowledge-base",
+    "engineering-process",
+    "claude-code",
+    "codex",
+    "agentic",
+    "ai-agents"
+  ],
+  "homepage": "https://github.com/SmartAndPoint/ProjectStore#readme",
+  "bugs": {
+    "url": "https://github.com/SmartAndPoint/ProjectStore/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SmartAndPoint/ProjectStore.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Evgenii Konev",
+    "email": "ekonev@smartandpoint.com",
+    "url": "https://github.com/SmartAndPoint"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "projectstore": "bin/projectstore.mjs"
+  },
+  "files": [
+    "bin/",
+    ".claude-plugin/",
+    "agents/",
+    "commands/",
+    "harnesses/",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "scaffold/",
+    "templates/",
+    "docs/",
+    "AGENTS.md",
+    ".mcp.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "guard": "node scripts/version-guard.mjs",
+    "packlist": "node scripts/version-guard.mjs --write-packlist",
+    "adapters": "node scripts/build-adapters.mjs --write",
+    "adapters:check": "node scripts/build-adapters.mjs --check",
+    "shells": "node packaging/shells.mjs --write",
+    "shells:check": "node packaging/shells.mjs --check",
+    "shells:build": "node packaging/shells.mjs --build --out dist",
+    "release:check": "npm run adapters:check && npm run guard && npm run shells:check && npm test && npm pack --dry-run"
+  }
+}

package/node_modules/projectstore/scaffold/checklists.json

@@ -0,0 +1,88 @@
+{
+  "_description": "Per-kind structural checklists used by /projectstore:review. Each kind defines `default_review` (whether the projectstore-peer-reviewer skill auto-suggests review after creation) and an `items` array fed verbatim to the critic agent.",
+  "adr": {
+    "default_review": true,
+    "items": [
+      "Decision section is unambiguous — a stranger could implement it from this file alone, with no other context.",
+      "At least one named Alternative is present with an explicit rejection reason ('Rejected because: ...').",
+      "Consequences include at least one Negative / trade-off stated honestly. Reject sales framing.",
+      "All hand-wavy referents ('we', 'users', 'the system') are resolved to concrete actors or components.",
+      "No marketing language: 'blazingly', 'robust', 'best-in-class', 'magnificent', 'rock-solid', etc.",
+      "Context explains why the decision is needed NOW (vs. a year ago or in 6 months).",
+      "References cite at least one external doc / prior ADR / RFC if relevant.",
+      "Status, Date, Authors metadata filled (not template placeholders).",
+      "No TODOs, no '...', no empty bullets in the final body."
+    ]
+  },
+  "research": {
+    "default_review": true,
+    "items": [
+      "Question is sharp — answerable by yes/no/comparison, not 'tell me about X'.",
+      "TL;DR is a single paragraph that gives the conclusion before the body.",
+      "Method describes how findings were gathered (docs read, benchmarks run, experts asked) — not just 'I researched'.",
+      "Comparison table has populated Pros AND Cons cells; empty cells flagged.",
+      "Conclusion explicitly ties back to the original Question. Recommendation is actionable.",
+      "References are linkable (URL / file path), not 'see [some doc]'.",
+      "No unstated benchmarks ('it's faster' without numbers).",
+      "Findings are evidence-based, not opinion. Where opinion appears, it's labelled."
+    ]
+  },
+  "spec": {
+    "default_review": true,
+    "items": [
+      "How we solve references at least one ADR by id; the references resolve.",
+      "Behavioral contracts are numbered and individually testable — each states an observable outcome, not an implementation step.",
+      "Acceptance items are checkboxes; acceptance is explicitly ADDITIVE to the covered stories' own criteria, not a replacement.",
+      "Acceptance items that belong to specific stories carry a '— stories: <id>' attribution; items meant for all covered stories are unattributed on purpose.",
+      "frontmatter stories: uses <epic-id>/<story-id> path form, inline flow list.",
+      "Mandatory sections present (How we solve / Behavioral contracts / Acceptance); Modules-on-disk and Testing may be omitted only for research spikes.",
+      "For a spike spec: contracts read as questions-to-answer plus exit criteria.",
+      "No TODOs, no '...', no empty bullets in the final body."
+    ]
+  },
+  "epic": {
+    "default_review": true,
+    "items": [
+      "Goal is measurable — success can be verified, not just described.",
+      "Context explains why this epic exists and which downstream pieces depend on it.",
+      "Stories table has at least 2 entries; first story description is concrete enough to start.",
+      "Expected Results contains testable outcomes, not aspirations.",
+      "Dependencies list external blockers (people, systems, decisions), not just sibling stories.",
+      "Open Questions are real unknowns, not rhetorical filler.",
+      "Priority assigned (p0 / p1 / p2), not left as default if epic is non-trivial."
+    ]
+  },
+  "story": {
+    "default_review": false,
+    "items": [
+      "Description states the user/actor and the value of the change.",
+      "Decomposition checklist has items granular enough to finish in a session each.",
+      "Acceptance Criteria are testable (someone could write tests from these).",
+      "Technical Notes flag any non-obvious risks or constraints."
+    ]
+  },
+  "concept": {
+    "default_review": false,
+    "items": [
+      "Definition fits in one paragraph; a stranger leaves knowing what the concept IS.",
+      "Examples ground the concept (at least one concrete case)."
+    ]
+  },
+  "meeting": {
+    "default_review": false,
+    "items": [
+      "Attendees listed.",
+      "Decisions section captures what was actually decided (not just discussed).",
+      "Action items have an owner."
+    ]
+  },
+  "runbook": {
+    "default_review": false,
+    "items": [
+      "Purpose states WHEN to run this runbook (trigger conditions).",
+      "Prerequisites are listable checks, not prose.",
+      "Verification step exists and is testable.",
+      "Rollback step exists for any irreversible action."
+    ]
+  }
+}