usecontextual 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikael Endale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# usecontextual
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Contextual CLI: everything a script can do, with no AI. Zero runtime dependencies.
+
+> **Warning:** The package is `usecontextual`. `npx contextual` runs a different, unrelated package.
+
+Contextual isn't released yet. Two commands work in this version:
+
+| Command | What it does |
+|---|---|
+| `usecontextual check [--branch <name>]` | Checks the context against the spec (section 6.1). Exit code 1 when there are errors |
+| `usecontextual which <path>` | Shows who owns a file: a feature, the `shared:` line, or no one (exit code 1) |
+
+`init`, `update`, `check --fix` and `check --staged` print "not released yet" and exit. The design is in sections 6 and 7 of [the spec](https://github.com/mikaelendale/contextual/blob/main/docs/spec.md).
+
+## Tests
+
+```bash
+npm test
+```
+
+The tests use Node's built-in runner (Node 20 or newer). The main one is that `check` passes on [`example/`](https://github.com/mikaelendale/contextual/tree/main/example) with 0 errors. The rest break copies of the example and confirm `check` catches each break, test `which`, and check that the example still matches the templates.

package/bin/usecontextual.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.js"
+
+process.exitCode = runCli(process.argv.slice(2), {
+  cwd: process.cwd(),
+  out: (line) => process.stdout.write(`${line}\n`),
+  err: (line) => process.stderr.write(`${line}\n`),
+})

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "usecontextual",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "The Contextual CLI: adds, checks and updates the plain-markdown context that coding agents read.",
+  "type": "module",
+  "bin": {
+    "usecontextual": "bin/usecontextual.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "license": "MIT",
+  "author": "Mikael Endale",
+  "homepage": "https://contextual.mikaelen.site",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikaelendale/contextual.git",
+    "directory": "packages/cli"
+  }
+}

package/src/check.js

@@ -0,0 +1,371 @@
+/*
+ * `usecontextual check`: validates a project's context against the spec
+ * (docs/spec.md, section 6.1). It only reads; it never changes a file.
+ * Not built yet: --fix and --staged (spec 6.2).
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { dirname, join, relative } from "node:path"
+
+import {
+  BLOCK_END,
+  BLOCK_START,
+  FEATURE_FILES,
+  REQUIRED_FIELDS,
+  STATUSES,
+  buildIndex,
+  contextualBlock,
+  hashText,
+  lineCount,
+  phaseIsDone,
+  readFeatures,
+  readPlan,
+  readShared,
+  readText,
+  statusFileFor,
+} from "./context.js"
+import { currentBranch, listFiles } from "./files.js"
+import { matches } from "./glob.js"
+
+const DEFAULT_CAPS = { agentsBlockLines: 60, statusLines: 40, featureReadmeLines: 60, startTokens: 3000 }
+const REQUIRED_CONTEXT_FILES = [
+  "build-plan.md",
+  "architecture.md",
+  "conventions.md",
+  "status/main.md",
+  "features/_index.md",
+  "stack/_index.md",
+  "stack/overview.md",
+  "stack/requirements.md",
+  "stack/deploy.md",
+  "design/deslop.md",
+  "design/principles.md",
+  "design/layouts.md",
+  "design/components.md",
+]
+const META_KEYS = ["contextual", "defaultBranch", "cli", "skillDirs", "lastSync", "hashes"]
+const PORTABLE_SKILL_FIELDS = new Set(["name", "description", "license", "compatibility", "metadata"])
+const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/
+const LOG_HEADING = /^(\d{4}-\d{2}-\d{2}) · \S+ · \S.*$/
+const DECISION_FILE = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*\.md$/
+const stripComments = (text) => text.replace(/<!--[\s\S]*?-->/g, "")
+
+function walkMarkdown(dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) return walkMarkdown(path)
+    return name.endsWith(".md") ? [path] : []
+  })
+}
+
+/**
+ * @param {{ root: string, branch?: string | null }} options
+ * @returns {{ root: string, branch: string | null, findings: { level: "error" | "warning", file: string | null, message: string }[] }}
+ */
+export function check({ root, branch = null }) {
+  const findings = []
+  const error = (file, message) => findings.push({ level: "error", file, message })
+  const warn = (file, message) => findings.push({ level: "warning", file, message })
+  const ctx = join(root, "context")
+  const rel = (path) => relative(root, path).split("\\").join("/")
+
+  // --- .meta.json
+  let meta = {}
+  try {
+    meta = JSON.parse(readText(join(ctx, ".meta.json")))
+  } catch (e) {
+    error("context/.meta.json", `isn't valid JSON (${e.message})`)
+  }
+  for (const key of META_KEYS) if (!(key in meta)) error("context/.meta.json", `is missing "${key}"`)
+  if (meta.lastSync && !("commit" in meta.lastSync && "date" in meta.lastSync)) {
+    error("context/.meta.json", `"lastSync" needs both "commit" and "date" (spec 3.7)`)
+  }
+  const caps = { ...DEFAULT_CAPS, ...(meta.caps ?? {}) }
+  const cli = meta.cli ?? "npx usecontextual"
+  const defaultBranch = meta.defaultBranch ?? "main"
+  const skillDirs = Array.isArray(meta.skillDirs) ? meta.skillDirs : []
+
+  // --- AGENTS.md and CLAUDE.md
+  const agentsPath = join(root, "AGENTS.md")
+  if (!existsSync(agentsPath)) {
+    error("AGENTS.md", "is missing")
+  } else {
+    const text = readText(agentsPath)
+    const block = contextualBlock(text)
+    if (!block) {
+      error("AGENTS.md", `has no Contextual block (${BLOCK_START} … ${BLOCK_END})`)
+    } else {
+      if (text.split(BLOCK_START).length > 2 || text.split(BLOCK_END).length > 2) error("AGENTS.md", "has more than one Contextual block")
+      const n = lineCount(block)
+      if (n > caps.agentsBlockLines) error("AGENTS.md", `the Contextual block is ${n} lines; the cap is ${caps.agentsBlockLines}`)
+    }
+  }
+  const claudePath = join(root, "CLAUDE.md")
+  if (!existsSync(claudePath)) {
+    error("CLAUDE.md", "is missing, so Claude Code won't read AGENTS.md. It needs the line @AGENTS.md")
+  } else if (!/^@AGENTS\.md[ \t]*$/m.test(readText(claudePath))) {
+    error("CLAUDE.md", "doesn't import AGENTS.md. Add the line @AGENTS.md")
+  }
+
+  // --- required files
+  for (const file of REQUIRED_CONTEXT_FILES) {
+    if (!existsSync(join(ctx, file))) error(`context/${file}`, "is missing")
+  }
+  const setupDone = existsSync(join(ctx, "idea.md"))
+  if (!setupDone) warn("context/idea.md", "doesn't exist yet: contextual-setup writes it")
+
+  // --- features
+  const features = readFeatures(root)
+  const byName = new Map(features.map((f) => [f.name, f]))
+  for (const f of features) {
+    const where = `context/features/${f.name}`
+    const readme = `${where}/README.md`
+    if (!KEBAB.test(f.name)) error(where, "feature folders are named in kebab-case (lowercase words joined by -)")
+    if (!f.readme) {
+      error(readme, "is missing")
+      continue
+    }
+    for (const field of REQUIRED_FIELDS) if (!(field in f.fields)) error(readme, `is missing its "${field}:" line`)
+    if ("status" in f.fields && !STATUSES.includes(f.status)) error(readme, `has status "${f.status}"; use one of: ${STATUSES.join(", ")}`)
+    if ("phase" in f.fields && f.phase === null) error(readme, `has phase "${f.fields.phase}"; use the phase number`)
+    if ("covers" in f.fields && f.covers.length === 0) error(readme, `"covers:" lists no paths`)
+    for (const dep of f.dependsOn) if (!byName.has(dep)) error(readme, `depends on "${dep}", which isn't a feature folder`)
+    if (!f.summary) error(readme, `needs a "## What it does" section; its first sentence goes in the index`)
+    if (f.acceptanceTotal === 0) error(readme, `needs at least one checkbox under "## Acceptance"`)
+    if (f.status === "shipped" && f.acceptanceTicked < f.acceptanceTotal) {
+      error(readme, `is shipped, but ${f.acceptanceTotal - f.acceptanceTicked} acceptance box(es) are unticked`)
+    }
+    const n = lineCount(f.readme)
+    if (n > caps.featureReadmeLines) error(readme, `is ${n} lines; the cap is ${caps.featureReadmeLines}. Split the feature into smaller ones`)
+
+    if (STATUSES.includes(f.status)) {
+      const expected = f.status === "planned" ? ["README.md"] : FEATURE_FILES
+      for (const file of expected) {
+        if (!f.files.includes(file)) error(`${where}/${file}`, `is missing (a ${f.status} feature has ${expected.join(", ")})`)
+      }
+      if (f.status === "planned") {
+        for (const file of FEATURE_FILES.slice(1)) {
+          if (f.files.includes(file)) error(`${where}/${file}`, "shouldn't exist yet: a planned feature has only README.md")
+        }
+      }
+      for (const file of f.files) {
+        if (!FEATURE_FILES.includes(file)) warn(`${where}/${file}`, "isn't one of the feature files (README, build, tests, notes, log)")
+      }
+    }
+  }
+
+  // --- build plan
+  let phases = []
+  if (existsSync(join(ctx, "build-plan.md"))) {
+    const plan = readPlan(readText(join(ctx, "build-plan.md")))
+    phases = plan.phases
+    for (const problem of plan.problems) error("context/build-plan.md", problem)
+    const planned = new Map()
+    for (const phase of phases) {
+      for (const item of phase.items) {
+        if (planned.has(item.name)) error("context/build-plan.md", `lists features/${item.name} more than once`)
+        planned.set(item.name, phase)
+        const f = byName.get(item.name)
+        if (!f) {
+          error("context/build-plan.md", `lists features/${item.name}, which has no folder`)
+          continue
+        }
+        if (f.phase !== null && f.phase !== phase.number) {
+          error(`context/features/${f.name}/README.md`, `says phase ${f.phase}, but build-plan.md has it in phase ${phase.number}`)
+        }
+        if (item.ticked && !["shipped", "deprecated"].includes(f.status)) {
+          error("context/build-plan.md", `features/${f.name} is ticked, but its status is ${f.status}`)
+        }
+        if (!item.ticked && f.status === "shipped") error("context/build-plan.md", `features/${f.name} is shipped but not ticked`)
+      }
+    }
+    for (const f of features) if (!planned.has(f.name)) error(`context/features/${f.name}`, "isn't in build-plan.md")
+    for (const phase of phases) {
+      const done = phaseIsDone(phase, byName)
+      if (done && phase.marker !== "done") error("context/build-plan.md", `every feature in Phase ${phase.number} is finished; mark it [done]`)
+      if (!done && phase.marker === "done") error("context/build-plan.md", `Phase ${phase.number} is marked [done], but not every feature in it is finished`)
+    }
+  }
+
+  // --- the feature index is derived, so it must match what would be rebuilt
+  const indexPath = join(ctx, "features", "_index.md")
+  if (existsSync(indexPath) && readText(indexPath) !== buildIndex({ cli, phases, featuresByName: byName })) {
+    error("context/features/_index.md", "is out of date: it doesn't match the feature READMEs and build-plan.md")
+  }
+
+  // --- status files
+  const statusDir = join(ctx, "status")
+  if (existsSync(statusDir)) {
+    for (const name of readdirSync(statusDir).filter((n) => n.endsWith(".md"))) {
+      const n = lineCount(readText(join(statusDir, name)))
+      if (n > caps.statusLines) error(`context/status/${name}`, `is ${n} lines; the cap is ${caps.statusLines}`)
+    }
+  }
+  const resolvedBranch = branch ?? currentBranch(root)
+  if (!resolvedBranch) {
+    warn(null, "couldn't tell the current branch, so its status file wasn't checked (pass --branch <name>)")
+  } else {
+    const file = statusFileFor(resolvedBranch, defaultBranch)
+    if (!existsSync(join(statusDir, file))) error(`context/status/${file}`, `is missing: the branch ${resolvedBranch} needs its status file`)
+  }
+
+  // --- every markdown file: links, leftover guidance, log entries
+  const markdown = [...(existsSync(agentsPath) ? [agentsPath] : []), ...walkMarkdown(ctx)]
+  for (const path of markdown) {
+    const text = readText(path)
+    const file = rel(path)
+    const visible = stripComments(text)
+    for (const m of visible.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+      const target = m[1]
+      if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#")) continue
+      const targetPath = target.split("#")[0].split("?")[0]
+      let decoded = targetPath
+      try {
+        decoded = decodeURI(targetPath)
+      } catch {
+        // keep it as written
+      }
+      if (targetPath && !existsSync(join(dirname(path), decoded))) error(file, `links to ${target}, which doesn't exist`)
+    }
+    if (setupDone && text.includes("<!-- fill:")) warn(file, "still has template guidance (<!-- fill: … -->) to replace")
+    if (path.endsWith(`${"log.md"}`) && file.startsWith("context/features/")) {
+      let previous = null
+      for (const m of visible.matchAll(/^## (.+)$/gm)) {
+        const heading = m[1].trim()
+        const date = heading.match(LOG_HEADING)?.[1]
+        if (!date) {
+          warn(file, `"## ${heading}" should read "## YYYY-MM-DD · agent · what was done"`)
+          continue
+        }
+        if (previous && date > previous) warn(file, `entries should be newest first ("${heading}" comes after an older entry)`)
+        previous = date
+      }
+    }
+  }
+
+  const decisionsDir = join(ctx, "decisions")
+  if (existsSync(decisionsDir)) {
+    for (const name of readdirSync(decisionsDir)) {
+      if (name.endsWith(".md") && name !== "README.md" && !DECISION_FILE.test(name)) {
+        warn(`context/decisions/${name}`, "decision files are named YYYY-MM-DD-<slug>.md")
+      }
+    }
+  }
+
+  // --- hashes (warnings only)
+  if (setupDone) {
+    const ideaHash = hashText(readText(join(ctx, "idea.md")))
+    if (!meta.hashes?.idea) warn("context/.meta.json", "has no hash for idea.md yet")
+    else if (meta.hashes.idea !== ideaHash) warn("context/idea.md", "has changed since setup. It holds the owner's own words and shouldn't be edited")
+  }
+  const deslopPath = join(ctx, "design", "deslop.md")
+  if (existsSync(deslopPath) && meta.hashes?.deslop && meta.hashes.deslop !== hashText(readText(deslopPath))) {
+    warn("context/design/deslop.md", `differs from the version Contextual ships; \`${cli} update\` restores it`)
+  }
+
+  // --- skills: present, valid, identical in every folder
+  const present = skillDirs.filter((d) => existsSync(join(root, d)))
+  if (skillDirs.length > 0 && present.length === 0) {
+    warn(null, `the skills aren't installed (${skillDirs.join(", ")}); \`${cli} update\` installs them`)
+  } else {
+    for (const d of skillDirs) if (!present.includes(d)) warn(d, "is missing; .meta.json lists it as a skill folder")
+    for (const d of present) {
+      for (const name of readdirSync(join(root, d))) {
+        if (statSync(join(root, d, name)).isDirectory()) checkSkill(join(root, d, name), `${d}/${name}`, name, error)
+      }
+    }
+    for (const d of present.slice(1)) compareTrees(join(root, present[0]), join(root, d), present[0], d, error)
+  }
+
+  // --- who owns each file (spec 3.8)
+  const architecturePath = join(ctx, "architecture.md")
+  const shared = existsSync(architecturePath) ? readShared(readText(architecturePath)) : null
+  if (existsSync(architecturePath) && shared === null) {
+    warn("context/architecture.md", `has no "shared:" line, so shared code can't be told apart from code no one owns`)
+  }
+  const ownFile = (p) =>
+    p.startsWith("context/") || p === "AGENTS.md" || p === "CLAUDE.md" || skillDirs.some((d) => p.startsWith(`${d.replace(/\/$/, "")}/`))
+  const projectFiles = listFiles(root).filter((p) => !ownFile(p))
+  const codeFiles = projectFiles.filter((p) => p.includes("/") || !/^(LICENSE.*|[^/]+\.(md|txt))$/i.test(p))
+  if (codeFiles.length === 0) {
+    warn(null, "found no code outside context/, so the covers: and shared: paths weren't checked")
+  } else {
+    for (const f of features) {
+      if (f.status !== "shipped" && f.status !== "in-progress") continue
+      for (const glob of f.covers) {
+        if (projectFiles.some((p) => matches(p, glob))) continue
+        const report = f.status === "shipped" ? error : warn
+        report(`context/features/${f.name}/README.md`, `covers ${glob}, which matches no files`)
+      }
+    }
+    for (const glob of shared ?? []) {
+      if (!projectFiles.some((p) => matches(p, glob))) warn("context/architecture.md", `shared: ${glob} matches no files`)
+    }
+    for (const p of projectFiles) {
+      const owners = features.filter((f) => f.covers.some((g) => matches(p, g))).map((f) => f.name)
+      const isShared = (shared ?? []).some((g) => matches(p, g))
+      if (owners.length > 1) error(p, `is covered by more than one feature: ${owners.join(", ")}`)
+      else if (owners.length === 1 && isShared) error(p, `is covered by ${owners[0]} and is also on the shared: line`)
+    }
+  }
+
+  return { root, branch: resolvedBranch, findings }
+}
+
+function readFrontmatter(text) {
+  if (!text.startsWith("---\n")) return null
+  const end = text.indexOf("\n---", 3)
+  if (end === -1) return null
+  const fields = {}
+  const lines = text.slice(4, end).split("\n")
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/)
+    if (!m) continue
+    let value = m[2].trim()
+    if (/^[>|][+-]?$/.test(value)) {
+      const block = []
+      while (i + 1 < lines.length && /^\s+\S|^\s*$/.test(lines[i + 1])) block.push(lines[++i].trim())
+      value = block.join(" ").trim()
+    }
+    fields[m[1]] = value.replace(/^(["'])(.*)\1$/, "$2")
+  }
+  return fields
+}
+
+function checkSkill(dir, label, folderName, error) {
+  const skillPath = join(dir, "SKILL.md")
+  if (!existsSync(skillPath)) {
+    error(`${label}/SKILL.md`, "is missing")
+    return
+  }
+  const fields = readFrontmatter(readText(skillPath))
+  if (!fields) {
+    error(`${label}/SKILL.md`, "needs frontmatter that starts on line 1 with --- and closes with ---")
+    return
+  }
+  for (const key of Object.keys(fields)) {
+    if (!PORTABLE_SKILL_FIELDS.has(key)) error(`${label}/SKILL.md`, `uses "${key}", which not every harness accepts (use name, description, license, compatibility, metadata)`)
+  }
+  const name = fields.name ?? ""
+  if (name !== folderName) error(`${label}/SKILL.md`, `name "${name}" must equal the folder name "${folderName}"`)
+  if (!KEBAB.test(name) || name.length > 64) error(`${label}/SKILL.md`, "name must be lowercase letters, digits and single hyphens, 64 characters at most")
+  const description = fields.description ?? ""
+  if (description.length === 0 || description.length > 1024) error(`${label}/SKILL.md`, `description must be 1 to 1,024 characters (it is ${description.length})`)
+}
+
+function compareTrees(a, b, labelA, labelB, error) {
+  const list = (dir, prefix = "") =>
+    readdirSync(dir)
+      .sort()
+      .flatMap((name) => (statSync(join(dir, name)).isDirectory() ? list(join(dir, name), `${prefix}${name}/`) : [`${prefix}${name}`]))
+  const filesA = list(a)
+  const filesB = list(b)
+  for (const f of new Set([...filesA, ...filesB])) {
+    if (!filesA.includes(f) || !filesB.includes(f)) {
+      error(`${filesA.includes(f) ? labelB : labelA}/${f}`, `is missing; the skill copies in ${labelA} and ${labelB} must be identical`)
+    } else if (readText(join(a, f)) !== readText(join(b, f))) {
+      error(`${labelB}/${f}`, `differs from ${labelA}/${f}; the skill copies must be identical`)
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,116 @@
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+
+import { check } from "./check.js"
+import { findRoot } from "./context.js"
+import { which } from "./which.js"
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))
+const DOCS = "https://github.com/mikaelendale/contextual"
+
+const HELP = `usecontextual ${version}
+
+Usage:
+  usecontextual check [--branch <name>]   check the context in this repo
+  usecontextual which <path>              show which feature owns a file
+
+Not released yet: init, update, check --fix, check --staged.
+Docs: ${DOCS}`
+
+function parseArgs(args) {
+  const flags = { _: [] }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg.startsWith("--")) {
+      const [key, inline] = arg.slice(2).split("=", 2)
+      if (inline !== undefined) flags[key] = inline
+      else if (args[i + 1] !== undefined && !args[i + 1].startsWith("--") && key === "branch") flags[key] = args[++i]
+      else flags[key] = true
+    } else {
+      flags._.push(arg)
+    }
+  }
+  return flags
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`
+
+function notReleased(what, err) {
+  err(`usecontextual ${what}: not released yet. See ${DOCS}`)
+  return 2
+}
+
+/** Runs the CLI and returns its exit code: 0 ok, 1 problems found, 2 usage errors and commands that aren't released yet. */
+export function runCli(argv, { cwd, out, err }) {
+  const [command, ...rest] = argv
+  const flags = parseArgs(rest)
+
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    out(HELP)
+    return 0
+  }
+  if (command === "--version" || command === "-v") {
+    out(version)
+    return 0
+  }
+  if (command === "init" || command === "update") return notReleased(command, err)
+  if (command === "check" && (flags.fix || flags.staged)) return notReleased(`check --${flags.fix ? "fix" : "staged"}`, err)
+  if (command !== "check" && command !== "which") {
+    err(`Unknown command "${command}". Run usecontextual --help.`)
+    return 2
+  }
+
+  const root = findRoot(cwd)
+  if (!root) {
+    err("No context/.meta.json here or in any folder above it. Run `npx usecontextual init` first.")
+    return 2
+  }
+
+  if (command === "check") {
+    if (flags.branch === true) {
+      err("--branch needs a branch name.")
+      return 2
+    }
+    const result = check({ root, branch: typeof flags.branch === "string" ? flags.branch : null })
+    const errors = result.findings.filter((f) => f.level === "error")
+    const warnings = result.findings.filter((f) => f.level === "warning")
+    out(`usecontextual check · ${basename(root)}${result.branch ? ` · branch ${result.branch}` : ""}`)
+    for (const f of [...errors, ...warnings]) {
+      out(`  ${f.level.padEnd(7)}  ${f.file ? `${f.file}: ` : ""}${f.message}`)
+    }
+    out(`${plural(errors.length, "error")}, ${plural(warnings.length, "warning")}`)
+    return errors.length > 0 ? 1 : 0
+  }
+
+  const target = flags._[0]
+  if (!target) {
+    err("Usage: usecontextual which <path>")
+    return 2
+  }
+  const result = which({ root, path: target, cwd })
+  if (result.outside) {
+    err(`${target} isn't inside this project.`)
+    return 2
+  }
+  if (result.contextual) {
+    out(`${result.path} is one of Contextual's own files; it needs no owner.`)
+    return 0
+  }
+  if (result.owners.length > 1) {
+    for (const f of result.owners) out(`${f.name}  context/features/${f.name}/README.md  (${f.status})`)
+    out("More than one feature covers this path. `usecontextual check` reports it as an error.")
+    return 2
+  }
+  if (result.owners.length === 1) {
+    const f = result.owners[0]
+    out(`${f.name}  context/features/${f.name}/README.md  (${f.status})`)
+    if (result.shared) out("It's also on the shared: line, which `usecontextual check` reports as an error.")
+    return 0
+  }
+  if (result.shared) {
+    out("shared  (the shared: line in context/architecture.md)")
+    return 0
+  }
+  out("no feature owns this path")
+  return 1
+}

package/src/context.js

@@ -0,0 +1,177 @@
+/*
+ * Reading a project's context: feature READMEs, the build plan, the shared
+ * list, .meta.json, the AGENTS.md block. Pure parsing, no judgment.
+ */
+
+import { createHash } from "node:crypto"
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+export const STATUSES = ["planned", "in-progress", "shipped", "deprecated"]
+export const FEATURE_FILES = ["README.md", "build.md", "tests.md", "notes.md", "log.md"]
+export const REQUIRED_FIELDS = ["status", "phase", "covers", "depends-on"]
+export const BLOCK_START = "<!-- contextual:start -->"
+export const BLOCK_END = "<!-- contextual:end -->"
+
+/** File text with line endings normalized to LF. */
+export function readText(path) {
+  return readFileSync(path, "utf8").replace(/\r\n/g, "\n")
+}
+
+export function lineCount(text) {
+  if (!text) return 0
+  return text.replace(/\n$/, "").split("\n").length
+}
+
+/** sha256 of the LF-normalized text, as stored in .meta.json. */
+export function hashText(text) {
+  return `sha256:${createHash("sha256").update(text.replace(/\r\n/g, "\n")).digest("hex")}`
+}
+
+/** The nearest folder at or above `start` that has context/.meta.json. */
+export function findRoot(start) {
+  let dir = resolve(start)
+  for (;;) {
+    if (existsSync(join(dir, "context", ".meta.json"))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** feat/boards → feat-boards (spec 3.4). */
+export function branchSlug(branch) {
+  return branch.toLowerCase().replace(/[^a-z0-9._-]/g, "-")
+}
+
+/** The status file name for a branch: the default branch always uses main.md. */
+export function statusFileFor(branch, defaultBranch) {
+  return branch === defaultBranch ? "main.md" : `${branchSlug(branch)}.md`
+}
+
+export function splitList(value) {
+  return (value ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+/** The first sentence of a paragraph, which becomes the feature's line in the index. */
+export function firstSentence(paragraph) {
+  const text = paragraph.trim().split("\n\n")[0].replace(/\s*\n\s*/g, " ")
+  const match = text.match(/^.*?[.!?](?=\s|$)/)
+  return (match ? match[0] : text).trim()
+}
+
+export function readFeature(featuresDir, name) {
+  const dir = join(featuresDir, name)
+  const files = readdirSync(dir).sort()
+  const feature = { name, dir, files, fields: {}, readme: null }
+  const readmePath = join(dir, "README.md")
+  if (!existsSync(readmePath)) return feature
+
+  const text = readText(readmePath)
+  feature.readme = text
+  feature.title = (text.match(/^# (.+)$/m) ?? [])[1] ?? null
+  const head = text.split(/^## /m)[0]
+  for (const line of head.split("\n")) {
+    const m = line.match(/^([a-z-]+):\s*(.*)$/)
+    if (m) feature.fields[m[1]] = m[2].trim()
+  }
+  feature.status = feature.fields.status
+  feature.phase = /^\d+$/.test(feature.fields.phase ?? "") ? Number(feature.fields.phase) : null
+  feature.covers = splitList(feature.fields.covers)
+  feature.dependsOn = splitList(feature.fields["depends-on"]).filter((d) => d !== "none")
+
+  const what = text.split(/^## What it does\n/m)[1]
+  feature.summary = what ? firstSentence(what.split(/^## /m)[0]) : null
+
+  const acceptance = (text.split(/^## Acceptance\n/m)[1] ?? "").split(/^## /m)[0]
+  feature.acceptanceTotal = (acceptance.match(/^- \[[ x]\] /gm) ?? []).length
+  feature.acceptanceTicked = (acceptance.match(/^- \[x\] /gm) ?? []).length
+  return feature
+}
+
+export function readFeatures(root) {
+  const featuresDir = join(root, "context", "features")
+  if (!existsSync(featuresDir)) return []
+  return readdirSync(featuresDir)
+    .filter((name) => statSync(join(featuresDir, name)).isDirectory())
+    .sort()
+    .map((name) => readFeature(featuresDir, name))
+}
+
+/**
+ * build-plan.md → phases. Headings that don't parse come back in `problems`
+ * rather than being guessed at.
+ */
+export function readPlan(text) {
+  const phases = []
+  const problems = []
+  for (const block of text.split(/^## /m).slice(1)) {
+    const heading = block.split("\n")[0].trim()
+    const m = heading.match(/^Phase (\d+) — (.+?)\s+\[(planned|in progress|done)\]$/)
+    if (!m) {
+      problems.push(`can't read the phase heading "## ${heading}" (expected "## Phase 1 — Name  [planned]")`)
+      continue
+    }
+    const items = []
+    for (const line of block.split("\n").slice(1)) {
+      const item = line.match(/^- \[([ x])\] features\/(\S+)/)
+      if (item) items.push({ name: item[2], ticked: item[1] === "x" })
+    }
+    phases.push({ number: Number(m[1]), name: m[2], marker: m[3], items })
+  }
+  return { phases, problems }
+}
+
+/** The globs on the `shared:` line of architecture.md, or null when there is no such line. */
+export function readShared(architectureText) {
+  const m = architectureText.match(/^shared:[ \t]*(.*)$/m)
+  return m ? splitList(m[1]) : null
+}
+
+/** The Contextual block of AGENTS.md, markers included, or null. */
+export function contextualBlock(agentsText) {
+  const start = agentsText.indexOf(BLOCK_START)
+  const end = agentsText.indexOf(BLOCK_END)
+  if (start === -1 || end === -1 || end < start) return null
+  return agentsText.slice(start, end + BLOCK_END.length)
+}
+
+const DONE = new Set(["shipped", "deprecated"])
+
+/** Is every feature in this phase shipped or deprecated? */
+export function phaseIsDone(phase, featuresByName) {
+  return phase.items.length > 0 && phase.items.every((item) => DONE.has(featuresByName.get(item.name)?.status))
+}
+
+/**
+ * The feature index, rebuilt from the READMEs and the plan (spec 4.3): a
+ * finished phase is one line; an open phase is a heading and a table.
+ */
+export function buildIndex({ cli, phases, featuresByName }) {
+  const header = `# Features\nRebuilt by \`${cli} check --fix\` from each feature's README and \`build-plan.md\`. Don't edit by hand.\n`
+  if (phases.length === 0) {
+    return `${header}\nNo features yet. \`contextual-setup\` adds them from the build plan.\n`
+  }
+  const collapsed = []
+  const open = []
+  for (const phase of phases) {
+    if (phaseIsDone(phase, featuresByName)) {
+      collapsed.push(`Phase ${phase.number} — ${phase.name}: done · ${phase.items.map((i) => i.name).join(", ")}`)
+      continue
+    }
+    const rows = phase.items
+      .filter((item) => featuresByName.has(item.name))
+      .map((item) => {
+        const f = featuresByName.get(item.name)
+        return `| [${f.name}](${f.name}/README.md) | ${f.status} | ${f.summary} |`
+      })
+    open.push(`## Phase ${phase.number} — ${phase.name}\n| Feature | Status | What it does |\n|---|---|---|\n${rows.join("\n")}`)
+  }
+  let out = header
+  if (collapsed.length) out += `\n${collapsed.join("\n")}\n`
+  for (const section of open) out += `\n${section}\n`
+  return out
+}

package/src/files.js

@@ -0,0 +1,48 @@
+import { execFileSync } from "node:child_process"
+import { readdirSync } from "node:fs"
+import { join } from "node:path"
+
+const SKIP_DIRS = new Set([".git", "node_modules", ".next", ".turbo", ".vercel", "dist", "build", "coverage"])
+
+/**
+ * Every file in the project, relative to `root`, with forward slashes. Uses git
+ * when it can, so `.gitignore` applies; otherwise walks the folder.
+ */
+export function listFiles(root) {
+  try {
+    const out = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    })
+    return out.split("\0").filter(Boolean)
+  } catch {
+    const files = []
+    const walk = (dir, prefix) => {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+          if (!SKIP_DIRS.has(entry.name)) walk(join(dir, entry.name), `${prefix}${entry.name}/`)
+        } else {
+          files.push(`${prefix}${entry.name}`)
+        }
+      }
+    }
+    walk(root, "")
+    return files
+  }
+}
+
+/** The current git branch in `root`, or null when git can't tell (not a repo, detached HEAD). */
+export function currentBranch(root) {
+  try {
+    const out = execFileSync("git", ["branch", "--show-current"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim()
+    if (out) return out
+  } catch {
+    // not a git repo
+  }
+  return process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME || null
+}

package/src/glob.js

@@ -0,0 +1,46 @@
+/*
+ * Glob matching for `covers:` and `shared:` lines.
+ *
+ * `**` matches any number of folders (including none), `*` matches within one
+ * path segment, `?` matches one character. Everything else is literal,
+ * including the brackets and parentheses Next.js uses in route folders, so
+ * `src/app/(auth)/**` and `src/app/boards/[boardId]/page.tsx` mean what they say.
+ */
+
+const cache = new Map()
+
+export function globToRegExp(glob) {
+  let re = ""
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === "*" && glob[i + 1] === "*") {
+      if (glob[i + 2] === "/") {
+        re += "(?:.*/)?" // "**/" is zero or more folders
+        i += 2
+      } else {
+        re += ".*" // a trailing "**" is everything below
+        i += 1
+      }
+    } else if (c === "*") {
+      re += "[^/]*"
+    } else if (c === "?") {
+      re += "[^/]"
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    }
+  }
+  return new RegExp(`^${re}$`)
+}
+
+export function matches(path, glob) {
+  let re = cache.get(glob)
+  if (!re) {
+    re = globToRegExp(glob)
+    cache.set(glob, re)
+  }
+  return re.test(path)
+}
+
+export function matchesAny(path, globs) {
+  return globs.some((glob) => matches(path, glob))
+}

package/src/which.js

@@ -0,0 +1,31 @@
+/*
+ * `usecontextual which <path>`: who owns a file (spec 3.8). A feature through
+ * its `covers:` globs, the `shared:` line in architecture.md, or no one.
+ */
+
+import { existsSync } from "node:fs"
+import { isAbsolute, join, relative, resolve } from "node:path"
+
+import { readFeatures, readShared, readText } from "./context.js"
+import { matches } from "./glob.js"
+
+export function which({ root, path, cwd = root }) {
+  const absolute = isAbsolute(path) ? path : resolve(cwd, path)
+  const rel = relative(root, absolute).split("\\").join("/")
+  if (rel === "" || rel.startsWith("../") || rel === ".." || isAbsolute(rel)) return { path: rel, outside: true }
+
+  let skillDirs = []
+  try {
+    skillDirs = JSON.parse(readText(join(root, "context", ".meta.json"))).skillDirs ?? []
+  } catch {
+    // check reports a broken .meta.json
+  }
+  const contextual =
+    rel.startsWith("context/") || rel === "AGENTS.md" || rel === "CLAUDE.md" || skillDirs.some((d) => rel.startsWith(`${d.replace(/\/$/, "")}/`))
+  if (contextual) return { path: rel, contextual: true, owners: [], shared: false }
+
+  const owners = readFeatures(root).filter((f) => f.covers.some((glob) => matches(rel, glob)))
+  const architecture = join(root, "context", "architecture.md")
+  const shared = existsSync(architecture) ? (readShared(readText(architecture)) ?? []) : []
+  return { path: rel, owners, shared: shared.some((glob) => matches(rel, glob)) }
+}