@c4a/context-cli 0.5.29-alpha.1

package/plugin/skills/semantic-reconcile/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: semantic-reconcile
+description: >
+  Internal skill for `/context:compile` and `/context:drop`. Consumes only
+  `context reconcile prepare` output, judges semantic relation/action for each
+  item, and emits a schema_version 1.0 semantic decision document for
+  `context reconcile review` / `context reconcile apply`.
+tools:
+  - Bash
+---
+
+# semantic-reconcile — decide Section reconciliation
+
+Judge duplicate, merge, conflict, reanchor, and unsupported cases from the
+CLI-prepared context. Emit decisions only; the CLI performs every write.
+
+## TL;DR — Non-negotiables
+
+- Input is only the `context reconcile prepare` payload. Do not Read, Glob, Grep, or Write workspace `raw/`, `knowledge/`, `archive/`, or `decisions/`.
+- Output exactly one YAML or JSON document with `schema_version: "1.0"` and `decisions[]`.
+- Use canonical relations: `exact_duplicate`, `strong_equivalent`, `near_duplicate`, `complement`, `supersedes`, `conflicts`, `reanchor`, `unsupported`, `keep_separate`, `ask_user`.
+- Use canonical actions: `duplicate_skip`, `merge_update`, `supersede`, `reanchor`, `remove_unsupported`, `keep_separate`, `split_then_reanchor`, `ask_user`.
+- `no-op` is not a decision action. For unchanged refresh items, emit no decision or `duplicate_skip`.
+- Never expose `src-N`, Section ids, or source refs as the user-facing choice. They may appear only in the structured payload.
+- `merge_update` is legal only when the final Section content is supported by one valid `source_ref`; otherwise use `keep_separate`, `split_then_reanchor`, or `ask_user`.
+- Unresolved conflicts and low-confidence support questions must be `action: ask_user`.
+
+<reference>
+
+## Decision Shape
+
+```yaml
+schema_version: "1.0"
+decisions:
+  - item_id: claim-001
+    relation: near_duplicate
+    action: merge_update
+    target:
+      node: payment-runtime
+      section_id: section-3
+    proposed:
+      content: "Runtime isolation uses sandboxing to avoid state pollution."
+      confidence: confirmed
+      source_ref: "src-2#runtime L12-14"
+      source_ref_text: "sandboxing to avoid state pollution"
+    rationale: "The new evidence refines the same claim."
+    user_confirmation:
+      required: true
+      question_type: merge_confirmation
+```
+
+## Action Rules
+
+| action | Required fields |
+|---|---|
+| `duplicate_skip` | `target` |
+| `merge_update` | `target`, `proposed.content`, `proposed.source_ref` |
+| `supersede` | `target`, `proposed.kind`, `proposed.content`, `proposed.source_ref` |
+| `reanchor` | `target`, `proposed.source_ref`, `proposed.confidence` |
+| `remove_unsupported` | `target` |
+| `keep_separate` | `target`, `proposed.kind`, `proposed.content`, `proposed.source_ref` |
+| `split_then_reanchor` | `target`, `proposed.sections[]` |
+| `ask_user` | `user_confirmation.required: true` |
+
+</reference>
+
+<procedures>
+
+### Step 1 — Read Prepared Context
+
+Use the caller-provided `context reconcile prepare` output. For each item,
+compare `proposed`, `candidates`, `previous_decisions`, and `evidence`.
+
+### Step 2 — Reuse Stable Priors
+
+If `previous_decisions[]` shows the same boundary and the prepared item still
+matches, emit the same final action. If the target changed, treat the previous
+decision as a prior only and continue judging.
+
+### Step 3 — Decide Relation And Action
+
+Classify each item:
+
+- Exact same claim already active -> `exact_duplicate` + `duplicate_skip`.
+- Same claim with safer wording and one supporting source -> `strong_equivalent` or `near_duplicate` + `merge_update`.
+- Additional but separate boundary -> `complement` + `keep_separate`.
+- New material replaces old rule -> `supersedes` + `supersede`.
+- Direct contradiction -> `conflicts` + `ask_user`.
+- Drop item still fully supported elsewhere -> `reanchor` + `reanchor`.
+- Drop item partly supported -> `reanchor` + `split_then_reanchor`.
+- No surviving support -> `unsupported` + `remove_unsupported`.
+- Evidence is close but not enough -> `ask_user`.
+
+### Step 4 — Emit Decisions
+
+Emit only executable final decisions plus unresolved `ask_user` questions.
+Do not include prose outside the document.
+
+### Step 5 — Self-verify
+
+- [ ] Every decision uses canonical relation/action values. If not, **Step 3**.
+- [ ] No `no-op` action appears. If not, **Step 3**.
+- [ ] Every write action has the required fields from [Action Rules](#action-rules). If not, **Step 4**.
+- [ ] No workspace files were read or written directly. If violated, restart from **Step 1**.
+
+</procedures>

package/scripts/build-plugin.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+/**
+ * build-plugin.ts — materialize plugin manifests from templates by
+ * substituting `__VERSION__` with the value from package.json.
+ *
+ * Template sources:
+ *   - plugin/.claude-plugin/plugin.json.template
+ *   - plugin/.codex-plugin/plugin.json.template
+ *
+ * Outputs:
+ *   - plugin/.claude-plugin/plugin.json
+ *   - plugin/.codex-plugin/plugin.json
+ *
+ * Run after `bun run build` (or as part of it) so packaged tarballs ship
+ * version-correct plugin manifests. Idempotent — overwrites on every run.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "..");
+
+async function main(): Promise<void> {
+  const pkgRaw = await readFile(resolve(pkgRoot, "package.json"), "utf-8");
+  const pkg = JSON.parse(pkgRaw) as { version?: string };
+  const version = pkg.version;
+  if (!version) {
+    throw new Error("package.json is missing `version`");
+  }
+
+  const manifests = [
+    {
+      label: "claude",
+      templatePath: resolve(pkgRoot, "plugin/.claude-plugin/plugin.json.template"),
+      outputPath: resolve(pkgRoot, "plugin/.claude-plugin/plugin.json"),
+    },
+    {
+      label: "codex",
+      templatePath: resolve(pkgRoot, "plugin/.codex-plugin/plugin.json.template"),
+      outputPath: resolve(pkgRoot, "plugin/.codex-plugin/plugin.json"),
+    },
+  ] as const;
+
+  for (const manifest of manifests) {
+    const template = await readFile(manifest.templatePath, "utf-8");
+    const rendered = template.replace(/__VERSION__/g, version);
+
+    await writeFile(manifest.outputPath, rendered);
+
+    const parsed = JSON.parse(rendered) as { name?: string; version?: string; skills?: string };
+    if (parsed.name !== "context") {
+      throw new Error(`${manifest.label} plugin.json name must be "context", got "${parsed.name}"`);
+    }
+    if (parsed.version !== version) {
+      throw new Error(`${manifest.label} plugin.json version mismatch: ${parsed.version} vs ${version}`);
+    }
+    if (manifest.label === "codex" && parsed.skills !== "./skills/") {
+      throw new Error(`codex plugin.json must point skills to "./skills/", got "${parsed.skills}"`);
+    }
+
+    process.stdout.write(`${manifest.label} plugin.json generated (name=${parsed.name}, version=${parsed.version})\n`);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`build-plugin failed: ${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+});

package/scripts/postinstall.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * postinstall hook for @c4a/context-cli.
+ *
+ * The goal is narrow: when someone installs this package as a Claude Code
+ * plugin, the `context` bin should end up on PATH so `/context:*` slash
+ * commands can Bash out to it. In every other install scenario (library
+ * dependency, `bun install -g`, CI, local `bun link`) we do nothing.
+ *
+ * Dangerous things this script used to do (review findings 高-1 / 高-2):
+ *   - Recursion: the child `bun install -g @c4a/context-cli` inherits the
+ *     same Claude env vars that triggered us, runs postinstall again, and
+ *     loops. Fixed by (a) hard re-entry guard via CONTEXT_CLI_POSTINSTALL
+ *     in the child env, and (b) skipping entirely when we are already
+ *     inside a global install (`npm_config_global === "true"`).
+ *   - Dev mode break: pinning the registry spec `@c4a/context-cli@<version>`
+ *     ignores the actual install source (local tarball, file:, github:,
+ *     unpublished pre-release). Fixed by never spawning a child install;
+ *     we print a single actionable hint with the registry fallback command.
+ *     The plugin tarball already contains the whole CLI, so the user can
+ *     just `bun install -g <same source>` themselves — we can't guess the
+ *     source reliably from inside postinstall.
+ *
+ * Structure: all decision logic lives in the pure, exported `decide()`
+ * function. The top-level side-effect wrapper is the only thing that reads
+ * `process.env`, spawns the PATH probe, or writes to stderr. This split
+ * lets a sibling `.test.ts` exercise every branch without spawning
+ * subprocesses (Bun test's subprocess sandboxing has been unreliable in
+ * this package, so in-process tests are the practical way to cover the
+ * script).
+ */
+
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+export const RE_ENTRY_ENV = "CONTEXT_CLI_POSTINSTALL";
+
+/**
+ * Pure decision function. Given an env snapshot and a "does `context` bin
+ * exist on PATH?" predicate result, return either a hint to print or a
+ * "do nothing" sentinel.
+ *
+ * Shape:
+ *   { action: "skip", reason: "<why>" }
+ *   | { action: "hint", lines: string[] }
+ *
+ * Every branch that reads process state in the real run is modeled here so
+ * tests can pass synthetic envs. The caller decides whether to actually
+ * print or set the re-entry guard.
+ */
+export function decide(env, hasContextBin) {
+  if (env[RE_ENTRY_ENV] === "1") {
+    return { action: "skip", reason: "re-entry guard" };
+  }
+  if (env.CI === "true" || env.CI === "1") {
+    return { action: "skip", reason: "CI" };
+  }
+  if (env.npm_config_global === "true") {
+    return { action: "skip", reason: "already global install" };
+  }
+  if (env.CONTEXT_CLI_SKIP_AUTO_LINK === "1") {
+    return { action: "skip", reason: "explicit opt-out" };
+  }
+  if (!looksLikeClaudePluginInstall(env)) {
+    return { action: "skip", reason: "not a Claude plugin install" };
+  }
+  if (hasContextBin) {
+    return { action: "skip", reason: "context already on PATH" };
+  }
+  const version = env.npm_package_version ?? "latest";
+  return {
+    action: "hint",
+    lines: [
+      "Claude plugin installed. To enable `/context:*` slash commands, make " +
+        "the `context` bin available on PATH by running one of:",
+      `  bun install -g @c4a/context-cli@${version}    # install from npm registry`,
+      "  bun link                                       # if installing a local build",
+    ],
+  };
+}
+
+/**
+ * Heuristic: does the caller's env smell like a Claude plugin install?
+ * We require the env var's *value* to contain "claude" (case-insensitive),
+ * not just the var to be set — `npm_config_user_agent` is set by every
+ * install, and `CLAUDE_PLUGIN_INSTALL=0` should not trigger us either.
+ */
+export function looksLikeClaudePluginInstall(env) {
+  const hints = ["CLAUDE_PLUGIN_INSTALL", "CLAUDE_CODE_PLUGIN", "npm_config_user_agent"];
+  for (const key of hints) {
+    const value = env[key];
+    if (!value) continue;
+    if (value.toLowerCase().includes("claude")) return true;
+  }
+  return false;
+}
+
+/**
+ * Real-world `hasContextBin` probe: shell out to `command -v` / `where`.
+ * Kept separate from `decide()` so tests can inject a synthetic value.
+ */
+export function probeContextBin() {
+  const lookup = process.platform === "win32"
+    ? spawnSync("where", ["context"], { stdio: "ignore" })
+    : spawnSync("sh", ["-c", "command -v context"], { stdio: "ignore" });
+  return lookup.status === 0;
+}
+
+function log(msg) {
+  process.stderr.write(`[context-cli postinstall] ${msg}\n`);
+}
+
+function main() {
+  const env = process.env;
+  // First pass with hasContextBin=false tells us whether every *other* gate
+  // was passed. Only if the decision is "hint" do we need the real PATH
+  // probe (avoids shelling out to sh/where in the common skip cases).
+  const provisional = decide(env, false);
+  if (provisional.action === "skip") return;
+
+  // Decision said "hint" — now probe the real PATH. If context IS on PATH,
+  // the user doesn't need the hint.
+  const final = decide(env, probeContextBin());
+  if (final.action === "hint") {
+    for (const line of final.lines) log(line);
+  }
+  // Set the re-entry guard so any child process we may spawn in the future
+  // (we currently don't, but belt-and-suspenders against recursion) will
+  // inherit it and skip their own postinstall.
+  env[RE_ENTRY_ENV] = "1";
+}
+
+// Side-effect wrapper only runs when this file is executed directly as a
+// script (the postinstall lifecycle does that). When the file is imported
+// by a test, `main()` is not invoked.
+//
+// IMPORTANT — two quirks that the obvious
+//   `import.meta.url === \`file://${process.argv[1]}\``
+// check silently fails on, producing an invisible-no-op postinstall:
+//
+//   1. **Percent-encoding**: `import.meta.url` is always WHATWG-encoded
+//      (`%20` for spaces, %-hex for many punctuation chars, uppercase
+//      Windows drive letters, UNC `\\?\` prefixes). Raw `argv[1]` isn't.
+//      A package install under `/Users/Dev Tools/...` reproducibly no-ops
+//      with the interpolated check; going through `pathToFileURL` fixes
+//      it.
+//   2. **Symlink resolution**: on macOS `/tmp` is a symlink to
+//      `/private/tmp`, and `import.meta.url` resolves that; `argv[1]`
+//      does not. npm stashes packages under symlinked paths on some
+//      setups (npm's cache, nvm prefixes, corporate homedir mounts). We
+//      realpath `argv[1]` before URL-encoding so both sides compare the
+//      canonical target.
+//
+// Either quirk alone turns the postinstall script into a silent no-op —
+// exactly the invisible-failure mode npm postinstall scripts are
+// infamous for. The combined check below is validated by the subprocess
+// tests in postinstall.test.ts.
+export function isDirectRun(metaUrl, argv1) {
+  if (!argv1) return false;
+  try {
+    let resolved = argv1;
+    try {
+      resolved = realpathSync(argv1);
+    } catch {
+      // argv[1] may not exist yet (weird, but possible under npm install
+      // lifecycle timing). Fall back to the raw path — pathToFileURL
+      // still normalizes encoding, so spaces-but-no-symlinks still works.
+    }
+    return metaUrl === pathToFileURL(resolved).href;
+  } catch {
+    return false;
+  }
+}
+
+if (isDirectRun(import.meta.url, process.argv[1])) {
+  try {
+    main();
+  } catch (err) {
+    log(`postinstall error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/templates/aspects/code/prompt.md

@@ -0,0 +1,29 @@
+# aspect: code
+
+> Code structure aspect. The `context capture-code` command invokes the
+> `@c4a/extract` / `@c4a/extract-ts` pipeline directly — it does not read
+> this file. The prompt exists as a placeholder so the init flow is
+> uniform and so a future scripted-aspect mechanism can take over without
+> reshuffling directory structure.
+
+## Target
+
+Extract `Package` / `Symbol` nodes and `imports` / `calls` / `extends` edges
+from the current git worktree.
+
+## Schema
+
+Payloads are written by the CLI as JSONL files under each dated bucket:
+
+- `packages.jsonl` — one `Package` per line
+- `symbols.jsonl` — one `Symbol` per line (recursive `members` flattened)
+- `edges.jsonl` — one relation per line (optional)
+- `_meta.yaml` — bucket metadata (`commit`, `captured_at`, `script_hash`,
+  `content_hash`)
+
+## Notes
+
+- Currently driven by the CLI, not by a per-aspect script. The scripted
+  `capture.ts` contract for non-code aspects is planned for a later release.
+- source-id is always `aspect:code`.
+- Bucket name is `YYYY-MM-DD-<sha7>` where `<sha7>` is `git rev-parse --short HEAD`.

package/templates/aspects/design-system/prompt.md

@@ -0,0 +1,27 @@
+# aspect: design-system
+
+> Design-system aspect placeholder. The current CLI does not yet provide
+> a scripted capture driver for this aspect — `context capture-aspect
+> design-system` will report that scripted aspects beyond `code` are not
+> implemented. This file exists so the init flow keeps the aspect slot
+> consistent for a future scripted-capture release.
+
+## Target
+
+Extract design tokens (color / spacing / typography) and component usage
+patterns from the codebase and design docs.
+
+## Schema (planned contract)
+
+When scripted capture lands, payloads will be written into dated buckets
+under `raw/aspect/design-system/<YYYY-MM-DD>-<hash7>/`:
+
+- `facts.jsonl` — one design-system fact per line (token definitions, usage
+  rules, deprecations)
+- `_meta.yaml` — bucket metadata (`token_count`, `source_files`,
+  `captured_at`, `script_hash`, `content_hash`)
+
+## Notes
+
+- Not executable by the current CLI.
+- source-id reserved as `aspect:design-system`.

package/templates/aspects/graphql/prompt.md

@@ -0,0 +1,24 @@
+# aspect: graphql
+
+> GraphQL aspect placeholder. The current CLI does not yet provide a
+> scripted capture driver — `context capture-aspect graphql` will report
+> that scripted aspects beyond `code` are not implemented.
+
+## Target
+
+Extract GraphQL type definitions, resolver mappings, and usage patterns
+from schema files and server code.
+
+## Schema (planned contract)
+
+Payloads produced by the future scripted capture:
+
+- `facts.jsonl` — GraphQL facts (type definitions, field descriptions,
+  resolver docs, deprecations)
+- `_meta.yaml` — bucket metadata (`schema_file`, `type_count`,
+  `captured_at`, `script_hash`, `content_hash`)
+
+## Notes
+
+- Not executable by the current CLI.
+- source-id reserved as `aspect:graphql`.

package/templates/aspects/openapi/prompt.md

@@ -0,0 +1,24 @@
+# aspect: openapi
+
+> OpenAPI aspect placeholder. The current CLI does not yet provide a
+> scripted capture driver — `context capture-aspect openapi` will report
+> that scripted aspects beyond `code` are not implemented.
+
+## Target
+
+Extract HTTP endpoints, request/response schemas, and auth requirements
+from OpenAPI spec files in the repo.
+
+## Schema (planned contract)
+
+Payloads produced by the future scripted capture will land under dated
+buckets and contain:
+
+- `facts.jsonl` — endpoint-level facts (path, method, auth, deprecation)
+- `_meta.yaml` — bucket metadata (`spec_version`, `endpoint_count`,
+  `captured_at`, `script_hash`, `content_hash`)
+
+## Notes
+
+- Not executable by the current CLI.
+- source-id reserved as `aspect:openapi`.