@michaelmusyoka/eng-os-kit 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# eng-os-kit
+
+An engineering operating system for AI coding agents, installable with npm. Rules that stay in context, standards that load on demand as Agent Skills, and scripts that actually fail a build.
+
+Built for **Kilo Code**, and installs just as well into Claude Code, Roo Code, Cursor, or any agent implementing the Agent Skills standard.
+
+## Install
+
+Per project (recommended):
+
+```bash
+npx eng-os-kit init
+```
+
+Every project on this machine:
+
+```bash
+npx eng-os-kit init --global
+```
+
+Other agents:
+
+```bash
+npx eng-os-kit init --agent claude
+npx eng-os-kit init --agent all
+```
+
+Then **reload your editor** — Kilo Code only reliably picks up new `SKILL.md` files on reload.
+
+## What lands in your project
+
+```text
+.kilocode/
+├── rules/00-engineering-contract.md   # ~50 lines, always in context
+├── skills/                            # generic skills, loaded on demand
+├── skills-architect/                  # planning skills, Architect mode only
+└── skills-code/                       # code + UI skills, Code mode only
+.agent/
+├── state/feature-registry.json        # machine-validated project state
+├── state/known-issues.md
+├── state/decision-log.md
+├── templates/                         # prompt, verification, ADR, incident, feature
+├── scripts/                           # the enforcement layer
+├── prompts/  plans/  audits/  verification/  reports/
+```
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `npx eng-os-kit init` | install rules, skills and `.agent/` scaffolding |
+| `npx eng-os-kit add security-review test-strategy` | install a subset |
+| `npx eng-os-kit list` | every skill and its trigger description |
+| `npx eng-os-kit check` | run the enforcement scripts (CI-safe, exits non-zero) |
+| `npx eng-os-kit doctor` | what is installed where |
+
+Flags: `--agent kilocode|claude|roo|cursor|codex|all`, `--global`, `--skills a,b`, `--link` (symlink so `npm update` propagates), `--force`, `--cwd <path>`.
+
+## Skills
+
+| Skill | Mode | Triggers on |
+|---|---|---|
+| `engineering-contract` | all | starting non-trivial work, "what's the process" |
+| `repo-inspection` | architect | unfamiliar codebase, before any edit |
+| `implementation-prompt` | architect | auth/money/migrations/integrations, >3 files |
+| `api-database-contract` | all | any endpoint, schema, migration, idempotency |
+| `security-review` | all | auth, permissions, uploads, payments, webhooks |
+| `test-strategy` | all | writing tests, "is this tested", bug found |
+| `traceability-audit` | all | "is this done", before release |
+| `verification-evidence` | all | before claiming anything passed |
+| `release-gate` | all | before any production deploy |
+| `code-review` | code | reviewing a diff, after generating code |
+| `incident-response` | all | production broken, writing a postmortem |
+| `signature-dark-ui` | code | any UI work |
+
+## The enforcement layer
+
+Documentation that nothing checks is decoration. Three scripts do the checking:
+
+- **`placeholder-audit.sh`** — fails on committed secrets, `TODO`/`FIXME`/`placeholder`/`not implemented`, mocks in production paths; warns on dead `href="#"` links and debug output. Tests, docs and `.agent/` are excluded.
+- **`validate-registry.mjs`** — validates `feature-registry.json` and enforces the rule that matters: a feature cannot be `VERIFIED` or `PRODUCTION_READY` with an empty `evidence` array, or with evidence paths that do not exist.
+- **`capture-evidence.sh`** — runs a command and writes command + exit code + commit SHA + output to `.agent/verification/<feature-id>/`, so evidence is a file rather than a claim.
+
+Copy `.github/workflows/eng-os.yml` into your project and make the deploy job `needs: eng-os`. A pipeline that deploys on push without a passing gate makes every gate unreachable.
+
+## Design
+
+- **Always in context**: one ~50-line rules file. Precedence, six hard rules, statuses, report format.
+- **On demand**: everything else as a skill. The agent sees only name + description (~100 tokens each) until a task matches.
+- **Machine-checked**: the claims that agents get wrong — "tests pass", "it's complete" — are validated by scripts, not trust.
+
+## Customising
+
+Fork it. Edit `rules/engineering-contract.md` and the `skills/` folders, bump the version, then `npm publish` under your own scope, or install straight from git:
+
+```bash
+npx github:<you>/eng-os-kit init
+```
+
+Use `--link` during authoring so edits in the package show up in your project immediately.
+
+## License
+
+MIT.

package/bin/eng-os.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { TARGETS, DEFAULT_TARGET, MODE_SUFFIX_SUPPORT } from "../lib/targets.mjs";
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, "package.json"), "utf8"));
+
+const argv = process.argv.slice(2);
+const cmd = argv.find((a) => !a.startsWith("-")) || "help";
+const flag = (name) => argv.includes(`--${name}`);
+const opt = (name, fallback) => {
+  const i = argv.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+  if (i === -1) return fallback;
+  const a = argv[i];
+  return a.includes("=") ? a.slice(a.indexOf("=") + 1) : argv[i + 1] ?? fallback;
+};
+const positionals = argv.filter((a) => !a.startsWith("-")).slice(1);
+
+const c = { r: "\x1b[31m", g: "\x1b[32m", y: "\x1b[33m", d: "\x1b[2m", b: "\x1b[1m", x: "\x1b[0m" };
+process.stdout.on("error", (e) => { if (e.code === "EPIPE") process.exit(0); });
+const say = (m) => process.stdout.write(m + "\n");
+const ok = (m) => say(`${c.g}✓${c.x} ${m}`);
+const warn = (m) => say(`${c.y}!${c.x} ${m}`);
+const die = (m) => { say(`${c.r}✗${c.x} ${m}`); process.exit(1); };
+
+const SKILLS_DIR = path.join(PKG_ROOT, "skills");
+const allSkills = () =>
+  fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, d.name, "SKILL.md")))
+    .map((d) => d.name)
+    .sort();
+
+function frontmatter(skill) {
+  const body = fs.readFileSync(path.join(SKILLS_DIR, skill, "SKILL.md"), "utf8");
+  const m = body.match(/^---\n([\s\S]*?)\n---/);
+  const out = {};
+  if (m) for (const line of m[1].split("\n")) {
+    const i = line.indexOf(":");
+    if (i > 0) out[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return out;
+}
+
+function copyDir(from, to, { link = false, force = false }) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  if (fs.existsSync(to)) {
+    if (!force) return "skipped";
+    fs.rmSync(to, { recursive: true, force: true });
+  }
+  if (link) { fs.symlinkSync(from, to, "dir"); return "linked"; }
+  fs.cpSync(from, to, { recursive: true });
+  return "installed";
+}
+
+function copyFile(from, to, { force = false }) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  if (fs.existsSync(to) && !force) return "skipped";
+  fs.copyFileSync(from, to);
+  return fs.existsSync(to) ? "installed" : "failed";
+}
+
+function resolveTarget(name) {
+  const t = TARGETS[name];
+  if (!t) die(`Unknown --agent "${name}". Choose one of: ${Object.keys(TARGETS).join(", ")}`);
+  return t;
+}
+
+function base() {
+  return flag("global") ? os.homedir() : path.resolve(opt("cwd", process.cwd()));
+}
+
+function selected() {
+  const req = opt("skills", positionals.length ? positionals.join(",") : null);
+  if (!req || req === "all") return allSkills();
+  const want = req.split(",").map((s) => s.trim()).filter(Boolean);
+  const known = allSkills();
+  const bad = want.filter((w) => !known.includes(w));
+  if (bad.length) die(`Unknown skill(s): ${bad.join(", ")}\nRun: eng-os list`);
+  return want;
+}
+
+function installSkills(target, agentName, root, opts) {
+  const results = [];
+  for (const skill of selected()) {
+    const fm = frontmatter(skill);
+    const mode = fm.mode && MODE_SUFFIX_SUPPORT.has(agentName) ? `-${fm.mode}` : "";
+    const dest = path.join(root, `${target.projectSkills}${mode}`, skill);
+    results.push([skill, copyDir(path.join(SKILLS_DIR, skill), dest, opts)]);
+  }
+  return results;
+}
+
+function cmdInit() {
+  const agentName = opt("agent", DEFAULT_TARGET);
+  const agents = agentName === "all" ? Object.keys(TARGETS) : [agentName];
+  const root = base();
+  const opts = { force: flag("force"), link: flag("link") };
+
+  say(`${c.b}eng-os-kit ${pkg.version}${c.x} → ${root}\n`);
+
+  for (const name of agents) {
+    const target = resolveTarget(name);
+    say(`${c.b}${target.label}${c.x}`);
+    for (const [skill, status] of installSkills(target, name, root, opts)) {
+      status === "skipped"
+        ? warn(`${skill} ${c.d}(already present, use --force)${c.x}`)
+        : ok(`${skill} ${c.d}${status}${c.x}`);
+    }
+    const rulesDest = path.join(root, target.projectRules, target.rulesFile);
+    const st = copyFile(path.join(PKG_ROOT, "rules", "engineering-contract.md"), rulesDest, opts);
+    st === "skipped" ? warn(`${target.rulesFile} ${c.d}(already present)${c.x}`) : ok(`${path.relative(root, rulesDest)}`);
+    say("");
+  }
+
+  if (flag("global")) { ok("Global install done. Reload your editor to pick up new skills."); return; }
+
+  for (const dir of [".agent/state", ".agent/prompts", ".agent/plans", ".agent/audits", ".agent/verification", ".agent/reports", ".agent/templates"]) {
+    fs.mkdirSync(path.join(root, dir), { recursive: true });
+  }
+  for (const f of fs.readdirSync(path.join(PKG_ROOT, "templates"))) {
+    copyFile(path.join(PKG_ROOT, "templates", f), path.join(root, ".agent/templates", f), opts);
+  }
+  for (const f of fs.readdirSync(path.join(PKG_ROOT, "state"))) {
+    copyFile(path.join(PKG_ROOT, "state", f), path.join(root, ".agent/state", f), opts);
+  }
+  fs.mkdirSync(path.join(root, ".agent/scripts"), { recursive: true });
+  for (const f of fs.readdirSync(path.join(PKG_ROOT, "scripts"))) {
+    const to = path.join(root, ".agent/scripts", f);
+    copyFile(path.join(PKG_ROOT, "scripts", f), to, opts);
+    if (fs.existsSync(to)) fs.chmodSync(to, 0o755);
+  }
+  ok(".agent/ state, templates and scripts ready");
+  say(`\n${c.d}Next:${c.x} reload your editor, then ask the agent: "read the engineering contract and run discovery".`);
+  say(`${c.d}Enforce:${c.x} npx eng-os check`);
+}
+
+function cmdList() {
+  say(`${c.b}Skills in eng-os-kit ${pkg.version}${c.x}\n`);
+  for (const s of allSkills()) {
+    const fm = frontmatter(s);
+    say(`${c.b}${s}${c.x}${fm.mode ? c.d + " [mode: " + fm.mode + "]" + c.x : ""}`);
+    say(`  ${c.d}${fm.description || ""}${c.x}\n`);
+  }
+  say(`${c.d}Install all:  npx eng-os-kit init${c.x}`);
+  say(`${c.d}Install some: npx eng-os-kit add security-review test-strategy${c.x}`);
+}
+
+function cmdAdd() {
+  if (!positionals.length && !opt("skills", null)) die("Name at least one skill. Run: eng-os list");
+  cmdInit();
+}
+
+function cmdCheck() {
+  const root = base();
+  let failed = 0;
+  const run = (label, file, args = []) => {
+    const local = path.join(root, ".agent/scripts", file);
+    const script = fs.existsSync(local) ? local : path.join(PKG_ROOT, "scripts", file);
+    say(`\n${c.b}› ${label}${c.x}`);
+    const bin = file.endsWith(".mjs") ? process.execPath : "bash";
+    const r = spawnSync(bin, [script, ...args], { stdio: "inherit", cwd: root });
+    if (r.status !== 0) failed++;
+  };
+  run("Placeholder / dead-path audit", "placeholder-audit.sh");
+  run("Feature registry validation", "validate-registry.mjs");
+  if (failed) die(`${failed} check(s) failed. Nothing is PRODUCTION_READY until these pass.`);
+  say(`\n${c.g}All eng-os checks passed.${c.x}`);
+}
+
+function cmdDoctor() {
+  const root = base();
+  const agentName = opt("agent", DEFAULT_TARGET);
+  const target = resolveTarget(agentName);
+  say(`${c.b}eng-os doctor${c.x} ${c.d}(${target.label} @ ${root})${c.x}\n`);
+  const check = (label, p) => fs.existsSync(path.join(root, p)) ? ok(`${label} ${c.d}${p}${c.x}`) : warn(`${label} missing ${c.d}${p}${c.x}`);
+  check("skills", target.projectSkills);
+  check("rules", path.join(target.projectRules, target.rulesFile));
+  check("state", ".agent/state/feature-registry.json");
+  check("scripts", ".agent/scripts/placeholder-audit.sh");
+  const skillsParent = path.dirname(path.join(root, target.projectSkills));
+  const leaf = path.basename(target.projectSkills);
+  const installed = fs.existsSync(skillsParent)
+    ? fs.readdirSync(skillsParent, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name.startsWith(leaf))
+        .flatMap((d) => fs.readdirSync(path.join(skillsParent, d.name)))
+    : [];
+  const missing = allSkills().filter((s) => !installed.includes(s));
+  if (missing.length) warn(`not installed: ${missing.join(", ")}`);
+  say(`\n${c.d}Reload the editor after any skill change — Kilo Code only reliably picks up SKILL.md changes on reload.${c.x}`);
+}
+
+function cmdHelp() {
+  say(`${c.b}eng-os-kit${c.x} ${pkg.version} — engineering operating system for AI coding agents
+
+${c.b}Usage${c.x}
+  npx eng-os-kit init [options]          install rules + all skills + .agent scaffolding
+  npx eng-os-kit add <skill...>          install specific skills only
+  npx eng-os-kit list                    list bundled skills and their triggers
+  npx eng-os-kit check                   run the enforcement scripts (CI-safe)
+  npx eng-os-kit doctor                  show what is installed where
+
+${c.b}Options${c.x}
+  --agent <name>   kilocode (default) | claude | roo | cursor | codex | all
+  --global         install to your home directory instead of this project
+  --skills a,b     comma separated subset
+  --link           symlink skills instead of copying (keeps them updatable)
+  --force          overwrite existing files
+  --cwd <path>     target project directory
+
+${c.b}Examples${c.x}
+  npx eng-os-kit init                              # Kilo Code, this project
+  npx eng-os-kit init --agent kilocode --global     # every project on this machine
+  npx eng-os-kit init --link                        # stay in sync with npm updates
+  npx eng-os-kit add security-review --agent roo
+`);
+}
+
+({ init: cmdInit, add: cmdAdd, list: cmdList, check: cmdCheck, doctor: cmdDoctor, help: cmdHelp }[cmd] || cmdHelp)();

package/lib/targets.mjs

@@ -0,0 +1,49 @@
+// Where each agent expects rules and skills to live.
+// Kilo Code: https://kilo.ai/docs/features/skills  (.kilocode/skills, .kilocode/rules)
+export const TARGETS = {
+  kilocode: {
+    label: "Kilo Code",
+    projectSkills: ".kilocode/skills",
+    globalSkills: ".kilocode/skills",
+    projectRules: ".kilocode/rules",
+    rulesFile: "00-engineering-contract.md",
+    globalBase: ".kilocode"
+  },
+  claude: {
+    label: "Claude Code",
+    projectSkills: ".claude/skills",
+    globalSkills: ".claude/skills",
+    projectRules: ".",
+    rulesFile: "CLAUDE.md",
+    globalBase: ".claude"
+  },
+  roo: {
+    label: "Roo Code",
+    projectSkills: ".roo/skills",
+    globalSkills: ".roo/skills",
+    projectRules: ".roo/rules",
+    rulesFile: "00-engineering-contract.md",
+    globalBase: ".roo"
+  },
+  cursor: {
+    label: "Cursor",
+    projectSkills: ".cursor/skills",
+    globalSkills: ".cursor/skills",
+    projectRules: ".",
+    rulesFile: "AGENTS.md",
+    globalBase: ".cursor"
+  },
+  codex: {
+    label: "Codex / generic Agent Skills",
+    projectSkills: ".agents/skills",
+    globalSkills: ".agents/skills",
+    projectRules: ".",
+    rulesFile: "AGENTS.md",
+    globalBase: ".agents"
+  }
+};
+
+export const DEFAULT_TARGET = "kilocode";
+
+// Mode-scoped skills for agents that support skills-<mode> (Kilo Code, Roo).
+export const MODE_SUFFIX_SUPPORT = new Set(["kilocode", "roo"]);

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@michaelmusyoka/eng-os-kit",
+  "version": "1.0.0",
+  "description": "Production engineering operating system for AI coding agents: rules, Agent Skills, templates and enforcement scripts. Installs into Kilo Code, Claude Code, Roo, Cursor or any Agent Skills compatible agent.",
+  "keywords": ["kilocode", "kilo-code", "agent-skills", "skill", "claude-code", "roo-code", "ai-agent", "engineering-standards"],
+  "license": "MIT",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "bin": { "eng-os": "bin/eng-os.mjs" },
+  "files": ["bin", "lib", "rules", "skills", "templates", "scripts", "state", "README.md"],
+  "scripts": {
+    "selftest": "node bin/eng-os.mjs list && node bin/eng-os.mjs --help"
+  }
+}

package/rules/engineering-contract.md

@@ -0,0 +1,51 @@
+# Engineering Contract
+
+Always in context. Everything else loads on demand as a skill.
+
+## Precedence
+1. Explicit user instruction
+2. This contract
+3. Approved implementation prompt in `.agent/prompts/`
+4. Repository architecture docs and conventions
+5. Installed framework/package documentation
+6. General judgement
+
+Surface material conflicts. Do not resolve them silently.
+
+## Six rules that never bend
+1. **Inspect before editing.** Read the real files, schema, routes and tests. Do not assume structure.
+2. **Plan before production code.** Anything touching auth, money, migrations, external integrations, or more than three files needs an approved prompt first (skill: `implementation-prompt`). Smaller changes may proceed directly.
+3. **Never claim a check you did not run.** No "should work". Evidence or nothing (skill: `verification-evidence`).
+4. **Never fake production behaviour.** No mocks, stubbed success, hardcoded metrics or UI-only state in a production path.
+5. **Never weaken a test, type check, lint rule or security control to make something pass.** Fix the cause.
+6. **Never move a secret into client code, and never trust client-side validation for security.**
+
+## Statuses
+`PLANNED → IN_PROGRESS → IMPLEMENTED → VERIFIED → PRODUCTION_READY`, plus `BLOCKED`.
+
+`IMPLEMENTED` means code exists. It never means done. Only `VERIFIED` (evidence recorded) and `PRODUCTION_READY` (release gate passed) do.
+
+Track every feature in `.agent/state/feature-registry.json`. Conversation memory is not project state.
+
+## Blocked
+When a dependency, credential or decision is missing, stop and report: blocker, impact, what resolution is needed, what you could still verify. Never invent a dependency response.
+
+## Vertical slices
+UI → route/API → authentication → authorization → validation → service → persistence → integration → events → UI state. A UI-only or API-only implementation of a user-facing requirement is incomplete.
+
+## Final report format
+```
+### What I did
+- short bullets
+
+### Test
+1. exact command or manual step
+2. actual result
+
+### Needs your attention
+- decision, blocker, or None
+```
+Keep it short. Detail belongs in `.agent/prompts/`, `.agent/verification/` and `.agent/audits/`.
+
+## Skills available
+`repo-inspection`, `implementation-prompt`, `api-database-contract`, `security-review`, `test-strategy`, `traceability-audit`, `verification-evidence`, `release-gate`, `code-review`, `incident-response`, `signature-dark-ui`. Load the one that fits; do not work from memory of these standards.

package/scripts/capture-evidence.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Runs a command and records real output as evidence.
+# Usage: .agent/scripts/capture-evidence.sh F-001 "npm test -- --run"
+set -uo pipefail
+
+FEATURE="${1:?usage: capture-evidence.sh <feature-id> \"<command>\"}"
+CMD="${2:?usage: capture-evidence.sh <feature-id> \"<command>\"}"
+
+DIR=".agent/verification/${FEATURE}"
+mkdir -p "$DIR"
+STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+SLUG="$(printf '%s' "$CMD" | tr -cs 'a-zA-Z0-9' '-' | cut -c1-40 | sed 's/-$//')"
+OUT="${DIR}/${STAMP}-${SLUG}.log"
+SHA="$(git rev-parse HEAD 2>/dev/null || echo 'not-a-git-repo')"
+
+{
+  echo "feature:   $FEATURE"
+  echo "command:   $CMD"
+  echo "commit:    $SHA"
+  echo "timestamp: $STAMP"
+  echo "host:      $(uname -sm)"
+  echo "---"
+} > "$OUT"
+
+set +e
+bash -lc "$CMD" 2>&1 | tail -400 >> "$OUT"
+CODE="${PIPESTATUS[0]}"
+set -e
+
+{ echo "---"; echo "exit_code: $CODE"; } >> "$OUT"
+
+if [ "$CODE" -eq 0 ]; then
+  echo "✓ PASS  exit 0  → $OUT"
+else
+  echo "✗ FAIL  exit $CODE  → $OUT"
+fi
+echo "Add this path to the feature's \"evidence\" array in .agent/state/feature-registry.json"
+exit "$CODE"

package/scripts/placeholder-audit.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Fails when unfinished production behaviour is committed.
+# Usage: .agent/scripts/placeholder-audit.sh [path]   (default: repo root)
+set -uo pipefail
+
+ROOT="${1:-.}"
+STRICT_PATTERN='TODO|FIXME|XXX|HACK|placeholder|coming soon|not implemented|NotImplemented|dummy|FAKE_|hardcoded'
+MOCK_PATTERN='mockResolvedValue|jest\.mock|MSW_ENABLED|process\.env\.MOCK|useMockData|__mocks__/'
+DEADLINK_PATTERN='href=["'"'"']#["'"'"']|href=["'"'"']["'"'"']|to=["'"'"']#["'"'"']'
+DEBUG_PATTERN='console\.log|debugger;|print\(.*DEBUG'
+SECRET_PATTERN='(AKIA[0-9A-Z]{16})|(sk_live_[0-9a-zA-Z]{10,})|(-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----)|(ghp_[0-9a-zA-Z]{20,})'
+
+EXCLUDES=(--exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build
+          --exclude-dir=.next --exclude-dir=coverage --exclude-dir=vendor --exclude-dir=.venv
+          --exclude-dir=__tests__ --exclude-dir=tests --exclude-dir=test --exclude-dir=e2e
+          --exclude-dir=.agent --exclude-dir=.kilocode --exclude-dir=.claude
+          --exclude=*.test.* --exclude=*.spec.* --exclude=*.md --exclude=*.lock --exclude=*.map
+          --exclude=placeholder-audit.sh --exclude=validate-registry.mjs --exclude=capture-evidence.sh)
+
+fail=0
+scan() {
+  local label="$1" pattern="$2" severity="$3"
+  local hits
+  hits="$(grep -rInE "$pattern" "$ROOT" "${EXCLUDES[@]}" 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    local n; n="$(printf '%s\n' "$hits" | wc -l | tr -d ' ')"
+    echo "[$severity] $label — $n occurrence(s)"
+    printf '%s\n' "$hits" | head -40 | sed 's/^/    /'
+    [ "$n" -gt 40 ] && echo "    ... $((n - 40)) more"
+    [ "$severity" = "FAIL" ] && fail=1
+    echo
+  else
+    echo "[ok]   $label"
+  fi
+}
+
+echo "Placeholder / dead-path audit — $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+echo "Scanning: $ROOT (production paths; tests and docs excluded)"
+echo
+scan "committed secrets"            "$SECRET_PATTERN"   "FAIL"
+scan "unfinished markers"           "$STRICT_PATTERN"   "FAIL"
+scan "mocks in production paths"    "$MOCK_PATTERN"     "FAIL"
+scan "dead links / empty hrefs"     "$DEADLINK_PATTERN" "WARN"
+scan "debug output"                 "$DEBUG_PATTERN"    "WARN"
+
+echo
+if [ "$fail" -ne 0 ]; then
+  echo "RESULT: FAIL — resolve each FAIL occurrence, or document it in .agent/state/known-issues.md and exclude it deliberately."
+  exit 1
+fi
+echo "RESULT: PASS"

package/scripts/validate-registry.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Validates .agent/state/feature-registry.json: schema-ish checks plus the rules
+// that actually catch false completion claims. No dependencies.
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.argv[2] || process.cwd();
+const file = path.join(root, ".agent/state/feature-registry.json");
+const STATUSES = ["PLANNED", "IN_PROGRESS", "IMPLEMENTED", "VERIFIED", "PRODUCTION_READY", "BLOCKED"];
+const NEEDS_EVIDENCE = ["VERIFIED", "PRODUCTION_READY"];
+
+if (!fs.existsSync(file)) {
+  console.error(`✗ missing ${path.relative(root, file)} — run: npx eng-os-kit init`);
+  process.exit(1);
+}
+
+let data;
+try { data = JSON.parse(fs.readFileSync(file, "utf8")); }
+catch (e) { console.error(`✗ invalid JSON: ${e.message}`); process.exit(1); }
+
+const errors = [];
+const warnings = [];
+const features = data.features;
+
+if (!Array.isArray(features)) {
+  console.error("✗ top-level \"features\" must be an array");
+  process.exit(1);
+}
+
+const seen = new Set();
+for (const [i, f] of features.entries()) {
+  const at = f?.id || `features[${i}]`;
+  const need = (k, test, msg) => { if (!test) errors.push(`${at}: ${msg || `missing or invalid "${k}"`}`); };
+
+  need("id", typeof f.id === "string" && /^F-\d{3,}$/.test(f.id), `"id" must look like F-001`);
+  if (seen.has(f.id)) errors.push(`${at}: duplicate id`);
+  seen.add(f.id);
+  need("title", typeof f.title === "string" && f.title.length > 2);
+  need("criticality", ["critical", "standard"].includes(f.criticality), `"criticality" must be "critical" or "standard"`);
+  need("status", STATUSES.includes(f.status), `"status" must be one of ${STATUSES.join(", ")}`);
+  need("requirements", Array.isArray(f.requirements) && f.requirements.length > 0, `needs at least one requirement id`);
+  need("acceptanceCriteria", Array.isArray(f.acceptanceCriteria) && f.acceptanceCriteria.length > 0, `needs at least one acceptance criterion`);
+  need("tests", Array.isArray(f.tests));
+  need("evidence", Array.isArray(f.evidence));
+
+  if (NEEDS_EVIDENCE.includes(f.status)) {
+    if (!f.evidence?.length) errors.push(`${at}: status ${f.status} with no evidence — evidence is required, not optional`);
+    if (!f.tests?.length) errors.push(`${at}: status ${f.status} with no tests listed`);
+    for (const e of f.evidence || []) {
+      const p = path.join(root, e);
+      if (!e.startsWith("http") && !fs.existsSync(p)) errors.push(`${at}: evidence path does not exist: ${e}`);
+    }
+  }
+  if (f.status === "PRODUCTION_READY" && f.criticality === "critical" && !(f.security || []).length) {
+    errors.push(`${at}: critical feature marked PRODUCTION_READY with no security checks recorded`);
+  }
+  if (f.status === "BLOCKED" && !f.notes) warnings.push(`${at}: BLOCKED without notes explaining the blocker`);
+  if (f.criticality === "critical" && f.status === "IMPLEMENTED") warnings.push(`${at}: critical feature IMPLEMENTED but not VERIFIED`);
+}
+
+const count = (s) => features.filter((f) => f.status === s).length;
+console.log(`Feature registry: ${features.length} feature(s)`);
+console.log(STATUSES.map((s) => `  ${s}: ${count(s)}`).join("\n"));
+if (warnings.length) { console.log("\nWarnings:"); warnings.forEach((w) => console.log(`  ! ${w}`)); }
+if (errors.length) {
+  console.error("\nErrors:");
+  errors.forEach((e) => console.error(`  ✗ ${e}`));
+  console.error(`\nRESULT: FAIL (${errors.length} error(s))`);
+  process.exit(1);
+}
+console.log("\nRESULT: PASS");

package/skills/api-database-contract/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: api-database-contract
+description: Standards for designing endpoints, error models, database entities, constraints, indexes, idempotency and migrations. Use this whenever adding or changing an API route, server action, database table, column, or migration, when defining error responses, and when a state-changing operation could be retried. Load before writing any schema or endpoint.
+---
+
+# API and Database Contracts
+
+## Every endpoint defines
+method, path, purpose, authentication, permission, request schema, validation, response schema, error cases, rate limit, timeout, idempotency behaviour, pagination/filtering/sorting, audit behaviour.
+
+## Error model
+| Code | Meaning |
+|---|---|
+| 400 | malformed request |
+| 401 | unauthenticated |
+| 403 | authenticated but not permitted |
+| 404 | missing, or hidden for authorization reasons |
+| 409 | conflict / concurrent update |
+| 422 | semantically invalid |
+| 429 | rate limited |
+| 500 | internal failure |
+| 503 | dependency unavailable |
+
+Never leak stack traces, SQL, secrets, internal paths or provider payloads. Return a stable error `code` string alongside the message so clients can branch without string matching.
+
+## Every entity defines
+ownership, primary key, relationships, nullability, unique constraints, indexes supporting its real queries, audit fields, retention, deletion behaviour (hard vs soft, and what cascades).
+
+Use database constraints for critical integrity rules. Application-level validation must not be the only protection — a unique index is the only thing that actually prevents a duplicate under concurrency.
+
+## Idempotency
+Any state-changing operation that an external system, a retry, or an impatient user can repeat needs a duplicate-safety story. Options: idempotency key with stored response, natural unique constraint, or conditional update on a version column. Choose one explicitly and test:
+- same request + same key → one logical operation, same response
+- different key → separate operation where permitted
+- concurrent identical requests → one winner, no partial state
+
+## Migrations
+Versioned, reproducible from empty, tested, reviewed, safe for existing data. Before a production migration assess: lock duration, downtime, backfill volume, rollback path, and whether old and new application versions can both run against the intermediate schema. Assume no migration is safely reversible until you have reversed it.