contextdevkit 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,18 @@ this project follows [Semantic Versioning](https://semver.org/).
 ## [Unreleased]
 
 ### Added
+- **Legacy-install migration (rename follow-through).** `install.mjs` now carries
+  an old `vibekit/` install forward to `contextkit/` automatically on `npx
+  contextdevkit --update` (and via an explicit `node install.mjs --migrate
+  [--dry-run]`). New `tools/install/migrate.mjs`: atomically MOVES the folder
+  (preserving memory/ADRs, config + level, pipeline tasks, `.env`), rewrites the
+  rename tokens in `settings.json` (killing the duplicate-hook trap),
+  `.gitignore`, `.gitattributes`, git-hook wrappers, `contextkit/.env`, and
+  `CLAUDE.md` (the last two backed up to `*.bak`), and deletes the stale
+  `/vibe-*` + `setupvibedevkit` command files. Refuses (no-op + warning) when
+  BOTH folders exist; idempotent; never throws into the installer (rule 2). New
+  `tools/integration-test-migrate.mjs` (25 asserts) wired into `test` +
+  `prepublishOnly`.
 - **agent-forge squad — Fase 6: declarative pipeline DSL + dry-run engine
   (ADR-0015 Part A).** The forge's orchestration is now a diffable, simulate-
   impact-mappable plan. New `templates/contextkit/squads/agent-forge/pipeline.yaml`

package/install.mjs

@@ -29,6 +29,7 @@ import { ensureDir, read, writeIfMissing, overwrite, copyTree, copyTreeIfMissing
 import { detectStack, requireBasename, looksGreenfield } from './tools/install/project.mjs';
 import { installGitHooks, patchGitignore, patchGitattributes } from './tools/install/git.mjs';
 import { uninstall } from './tools/install/uninstall.mjs';
+import { migrateLegacy } from './tools/install/migrate.mjs';
 import { isValidLevel } from './templates/contextkit/runtime/config/levels.mjs';
 import { parseArgs, HELP, prompt, LEVEL_LABELS } from './tools/install/cli.mjs';
 
@@ -63,6 +64,18 @@ async function main() {
     return;
   }
 
+  // Standalone migration: carry a legacy vibekit/ install forward, then stop.
+  if (args.migrate) {
+    const { report } = await migrateLegacy(target, { dryRun: args.dryRun });
+    console.log(report.length ? '\n' + report.join('\n') + '\n' : '\nℹ️  no legacy vibekit/ install found — nothing to migrate.\n');
+    return;
+  }
+
+  // Auto-migration: before ANYTHING reads contextkit/ (config, settings), carry a
+  // legacy vibekit/ install forward so `npx contextdevkit --update` just works.
+  const migration = await migrateLegacy(target, { dryRun: false });
+  if (migration.report.length) console.log('\n' + migration.report.join('\n') + '\n');
+
   const interactive = !args.yes && process.stdout.isTTY;
   let level = Number.isInteger(args.level) ? args.level : undefined;
   let name = args.name;
@@ -146,7 +159,7 @@ async function main() {
 
   // 5. Memory seeds: write only if missing. `.env.example` is seeded here so the
   //    user's edits survive re-install (ADR-0024 — media-gen credentials template).
-  for (const rel of ['memory/SESSIONS.md', 'memory/WORKSPACE.md', 'memory/GLOSSARY.md', 'memory/roadmap.md', 'memory/decisions/_TEMPLATE.md', 'memory/decisions/0000-record-architecture-decisions.md', 'memory/business-rules/_TEMPLATE.md', 'memory/predictions/.gitkeep', 'memory/sessions/.gitkeep', 'README.md', 'instrucoes.md', 'best-practices.md', 'behaviors.md', 'behaviors-examples.md', 'CLAUDE.child.md.tpl', 'squads/README.md', 'squads/_BRIEFING.md.tpl', '.env.example']) {
+  for (const rel of ['memory/SESSIONS.md', 'memory/WORKSPACE.md', 'memory/GLOSSARY.md', 'memory/roadmap.md', 'memory/decisions/_TEMPLATE.md', 'memory/decisions/0000-record-architecture-decisions.md', 'memory/business-rules/_TEMPLATE.md', 'memory/predictions/.gitkeep', 'memory/sessions/.gitkeep', 'README.md', 'instrucoes.md', 'best-practices.md', 'review-protocol.md', 'behaviors.md', 'behaviors-examples.md', 'CLAUDE.child.md.tpl', 'squads/README.md', 'squads/_BRIEFING.md.tpl', 'policy/complexity-rubric.json', '.env.example']) {
     const src = join(TPL, 'contextkit', rel);
     if (!existsSync(src)) continue;
     const wrote = await writeIfMissing(join(target, 'contextkit', rel), await read(src), args.force);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contextdevkit",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Portable, level-based AI-assisted development platform for Claude Code — hooks, slash commands, sub-agents, and durable project memory for any stack.",
   "type": "module",
   "bin": {
@@ -9,8 +9,8 @@
   "scripts": {
     "install:here": "node install.mjs --target .",
     "check": "node tools/selfcheck.mjs",
-    "test": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs",
-    "prepublishOnly": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs"
+    "test": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs && node tools/integration-test-migrate.mjs",
+    "prepublishOnly": "node tools/selfcheck.mjs && node tools/integration-test.mjs && node tools/integration-test-tooling.mjs && node tools/integration-test-tooling-pipeline.mjs && node tools/integration-test-tooling-agent-forge.mjs && node tools/integration-test-guards.mjs && node tools/integration-test-compozy.mjs && node tools/integration-test-migrate.mjs"
   },
   "files": [
     "install.mjs",

package/templates/CLAUDE.md.tpl

@@ -121,10 +121,11 @@ Setup: `/aidevtool-from0` (empty) · `/setupcontextdevkit` (existing). Daily: `/
 · `/log-session` · `/new-adr` · `/close-version` · `/context-refresh` · `/dev-start`
 · `/bug-hunt` · `/audit`. Multi-session: `/claim` · `/release` · `/worktree-new`.
 Quality: `/simulate-impact` · `/tech-debt-sweep` · `/analyze-code-ia-practices`
-· `/contract-check` · `/deps-audit` · `/deep-analysis` · `/test-plan` · `/scaffold-tests` · `/qa-signoff`. Product &
+· `/contract-check` · `/deps-audit` · `/deep-analysis` · `/validate-doc` · `/test-plan` · `/scaffold-tests` · `/qa-signoff`. Product &
 execution: `/roadmap` · `/pipeline` · `/ship` · `/retro` · `/context-stats`
 · `/distill-sessions` · `/distill-apply`.
 Structure & platform: `/squad` (squads) · `/git` (version control + remote)
+· `/draft-changelog` · `/gh-triage` · `/changelog-social` (OSS repo-ops)
 · `/claude-md` (scoped CLAUDE.md per module) · `/context-level` · `/context-config`
 · `/context-doctor`.
 

package/templates/claude/commands/README.md

@@ -32,7 +32,10 @@ templates/claude/commands/
 │   ├── git.md
 │   ├── claim.md
 │   ├── release.md
-│   └── worktree-new.md
+│   ├── worktree-new.md
+│   ├── draft-changelog.md           ← commits → Keep-a-Changelog skeleton (ADR-0030)
+│   ├── gh-triage.md                 ← GitHub issues → backlog, classified (ADR-0030)
+│   └── changelog-social.md          ← release → announcement copy, drafts only (ADR-0030)
 │
 ├── forge/                           ← agent-forge squad lifecycle
 │   ├── forge-new.md
@@ -55,7 +58,8 @@ templates/claude/commands/
 │   ├── tech-debt-sweep.md
 │   ├── analyze-code-ia-practices.md
 │   ├── contract-check.md
-│   └── seo-audit.md                ← SEO + AISO static analysers (ADR-0025)
+│   ├── seo-audit.md                ← SEO + AISO static analysers (ADR-0025)
+│   └── validate-doc.md             ← ADR/roadmap quality rubric (ADR-0030)
 │
 └── setup/                           ← installer + diagnostics
     ├── setupcontextdevkit.md

package/templates/claude/commands/audit/validate-doc.md

@@ -0,0 +1,37 @@
+---
+description: Quality gate for our own planning artifacts (ADRs / roadmap) — measurability, trade-offs, no placeholders. Advisory, never blocks.
+argument-hint: <path/to/doc.md> [--adr | --roadmap]
+---
+
+# 📋 Validate a planning document
+
+Run the document-quality rubric against **$ARGUMENTS** [ADR-0030]. This is the
+prose sibling of `selfcheck`: where selfcheck validates *code wiring*, this
+validates the *quality of the decision* an ADR or roadmap records — adapted from
+EVO-METHOD/BMAD's `steps-v` validation chain (MIT).
+
+1. Run the checker:
+   ```
+   node contextkit/tools/scripts/validate-doc.mjs $ARGUMENTS
+   ```
+   It auto-detects the rubric from the path (ADRs under `memory/decisions/`,
+   anything named `roadmap`), or force it with `--adr` / `--roadmap`.
+
+2. **What the ADR rubric enforces:**
+   - Required sections present (**Context**, **Decision**, **Consequences**).
+   - A valid **Status** (Proposed / Accepted / Superseded).
+   - No leftover template placeholders (`NNNN`, `YYYY-MM-DD`, `<who>`, …).
+   - Context that states the *forces* without already giving the answer (depth).
+   - Consequences that own a **trade-off / risk** — a decision with only upsides
+     is under-examined.
+   - Follow-ups noted (what the decision obligates next).
+
+3. **What the roadmap rubric enforces:** items read as **measurable** (a number,
+   date, or target), not aspirational.
+
+4. **Act on the output.** Errors (❌) are real gaps — fix the artifact. Warnings
+   (⚠️) are smells — judge each. This command is **advisory**: it never blocks a
+   commit or push (constitution §8 — report honestly, don't gate silently).
+
+> Tip: run it on a fresh ADR right after `/new-adr`, before you ask for the
+> `Accepted` flip — it catches thin Context and missing trade-offs early.

package/templates/claude/commands/bug-hunt.md

@@ -28,8 +28,16 @@ Symptom under investigation:
 6. **Only after root cause is confirmed**: propose the minimal fix, get approval, then implement.
    Add a regression test if the stack supports it.
 
-7. **Report + backlog.** Write a short root-cause report (symptom → root cause → fix →
-   regression test). Record the bug — and any *related* issues you surfaced — in the
+7. **Report + backlog (RCA writeup).** Write a structured root-cause analysis —
+   not just a one-liner [ADR-0030]:
+   - **Symptom** — what was observed, with the exact error/repro.
+   - **Root cause** — the single underlying defect (the *why*, not the *where*).
+   - **Trigger** — what conditions surfaced it (why now / why here).
+   - **Fix** — the minimal change that removes the root cause.
+   - **Prevention** — the regression test + any guard (a selfcheck/lint rule) so
+     this class of bug can't silently return.
+
+   Record the bug — and any *related* issues you surfaced — in the
    DevPipeline, point by point:
    ```
    node contextkit/tools/scripts/pipeline.mjs add --type bug --priority <P0-P3> \

package/templates/claude/commands/forge/forge-new.md

@@ -18,6 +18,12 @@ Package for **$ARGUMENTS** (or for the name the developer gives during the inter
    - `packager` assembles + stamps provenance.
 
 2. **Refuse to skip the interview.** Defaults are safe, not informed.
+   **Advanced elicitation** [ADR-0030]: don't just collect the answers to
+   `INTERVIEW_QUESTIONS` — probe the *unstated* edges that decide the package's
+   quality: the failure modes the agent must refuse, the cost ceiling, whether it
+   touches regulated data (run `complexity-rubric.mjs classify` on the role — an
+   LGPD/fintech domain pulls compliance requirements into the blueprint), and the
+   single hardest input it will face. Reflect assumptions back before the router runs.
 
 3. **Verify before writing** — show the dev:
    - The Agent Blueprint (YAML).

package/templates/claude/commands/pipeline/dev-start.md

@@ -27,35 +27,50 @@ You just entered **dev-start** mode with the objective:
    immutable rules + open backlog + recent ADRs) in a single call instead of
    opening each file. Open a full source only if the pack flags something to inspect.
 
-3. **Define IN-SCOPE / OUT-OF-SCOPE explicitly** from the objective. Show the user:
+3. **Right-size the work** [ADR-0030]. Classify the objective before committing
+   to a process — don't over-engineer a typo or under-plan a migration:
+   ```
+   node contextkit/tools/scripts/complexity-rubric.mjs classify "$ARGUMENTS"
+   ```
+   It returns a **tier** (trivial → no ADR/no story · feature → story · architectural
+   → `/new-adr` FIRST) and detects a **regulated domain**. If it flags a domain
+   (LGPD / fintech / healthcare …), **auto-route to the named agents** (e.g.
+   `@privacy-lgpd` + `@security`) and treat the work as architectural. The tier is
+   advisory, not a cage — state it and adjust with the user if it misreads.
+
+4. **Define IN-SCOPE / OUT-OF-SCOPE explicitly** from the objective. Show the user:
    ```
    ✅ IN-SCOPE: <what we will touch>
    ❌ OUT-OF-SCOPE: <what we will NOT touch, even if tempting>
    ```
    Ask for confirmation before proceeding if there is ambiguity.
 
-4. **Scope lock during the session**:
+5. **Scope lock during the session**:
    - Do NOT suggest refactors in files outside IN-SCOPE.
    - Do NOT "while we're here" rename/reorganize adjacent code.
    - Do NOT add new dependencies without asking.
    - If you spot a problem out of scope, **note it** and mention it at the END
      ("for next session: X, Y, Z") — do not act on it now.
+   - **Correct-course checkpoint** [ADR-0030]: if mid-session the work clearly
+     outgrows the agreed scope (a feature turns out to need a migration, a new
+     dependency, or an auth change), STOP and re-classify with the user before
+     continuing — don't silently let scope creep past the tier you agreed on.
 
-5. **Break the objective into 3–7 concrete tasks** and track them with TodoWrite.
+6. **Break the objective into 3–7 concrete tasks** and track them with TodoWrite.
 
-6. **Per-task scratch (optional)**: if you accumulate ephemeral notes while a
+7. **Per-task scratch (optional)**: if you accumulate ephemeral notes while a
    ticket is in `contextkit/pipeline/testing/`, drop them in a sibling file named
    `NNN-*.scratch.md` next to the ticket. The pipeline's `.gitignore` excludes
    `*.scratch.md` — scratches are local-only. At conclude time, summarise the
    useful parts into the ticket body and let the scratch be discarded.
 
-7. **Before opening a PR — re-check sync** [ADR-0026]. Run
+8. **Before opening a PR — re-check sync** [ADR-0026]. Run
    `node contextkit/tools/scripts/sync-check.mjs prepr` (or just use `/git pr`, which
    runs it): it re-confirms you are not behind `main` and that **no open PR
    already exists for this branch** before you create one. Don't duplicate a PR;
    push to update the existing one.
 
-8. **At the end**: offer `/log-session` (or `/new-adr` if an architectural decision was made).
+9. **At the end**: offer `/log-session` (or `/new-adr` if an architectural decision was made).
 
 ## Why this mode exists
 

package/templates/claude/commands/pipeline/pipeline.md

@@ -23,7 +23,11 @@ Act as the **manager** of this board based on **$ARGUMENTS**:
        --priority <P0-P3> --title "..." [--sla YYYY-MM-DD] [--roadmap P2.3]
   ```
   Then open the new file in `contextkit/pipeline/backlog/` and fill the context +
-  acceptance criteria.
+  acceptance criteria. **Right-size first** [ADR-0030]:
+  `node contextkit/tools/scripts/complexity-rubric.mjs classify "<title>"` — an
+  architectural tier means the task should reference (or trigger) an ADR; a
+  regulated domain means tagging the owning agents (`@privacy-lgpd`/`@security`)
+  in the acceptance criteria.
 - **move** — `node contextkit/tools/scripts/pipeline.mjs move <id> <backlog|testing|conclusion>`
   as work progresses (testing when you start; conclusion when accepted). For a
   concluded task, add a short outcome report to its file.

package/templates/claude/commands/pipeline/ship.md

@@ -30,7 +30,12 @@ State which mode you're running at the start.
    digest + immutable rules + recent ADRs in one call) and
    `node contextkit/tools/scripts/adr-digest.mjs --search "<objective keywords>"` for the
    ADRs relevant to the objective [ADR-0027] — open a full ADR only when needed.
-   Restate the objective; define IN/OUT-OF-SCOPE (as `/dev-start`).
+   Then **right-size the pipeline** [ADR-0030]:
+   `node contextkit/tools/scripts/complexity-rubric.mjs classify "$ARGUMENTS"`. A
+   **regulated domain** (LGPD / fintech / healthcare) makes the design + review
+   stages MANDATORY and pulls the named agents (e.g. `@privacy-lgpd`, `@security`)
+   into the squad; an **architectural** tier means the ADR in step 8 is required,
+   not optional. Restate the objective; define IN/OUT-OF-SCOPE (as `/dev-start`).
 2. **Design** — delegate to `architect`: options, trade-offs, recommended path,
    blast radius. If it crosses high-risk paths (L5), run `/simulate-impact` first.
    ◆ Checkpoint: confirm the design with the user.

package/templates/claude/commands/roadmap.md

@@ -25,8 +25,17 @@ Co-create it, don't dump a template. Ask, in a short adaptive round:
 - the product vision + primary user journey (reuse `contextkit/memory/product.md` if present);
 - the few **outcomes** that matter first, and roughly in what order;
 - any hard deadlines/constraints.
+
+**Advanced elicitation** [ADR-0030] — before drafting, surface what the user left
+*unstated*: the assumed target user, the success metric, the riskiest assumption,
+and what is explicitly OUT of scope for v1. Reflect these back as "here's what I'm
+assuming — correct me" rather than guessing silently. A wrong assumption caught
+here is worth ten reworked milestones.
+
 Then draft phases `P1, P2, …` with items `P1.1, P1.2, …` — each a user-facing
-capability + a one-line acceptance note. Show it, refine with the user, save.
+capability + a one-line **measurable** acceptance note (a number/date/target, not
+an aspiration — it's what `/validate-doc --roadmap` checks). Show it, refine with
+the user, save.
 
 ## from-existing — existing project
 1. If `roadmap.mjs find` listed a roadmap/PRD/spec file → read it and **import /

package/templates/claude/commands/vcs/changelog-social.md

@@ -0,0 +1,30 @@
+---
+description: Turn a finished CHANGELOG release into announcement copy (release notes + short social posts). Drafts only — never posts.
+argument-hint: [version | --unreleased]
+---
+
+# 📣 Changelog → announcement copy
+
+Turn a shipped release into human announcement copy [ADR-0030, OSS repo-ops].
+This **drafts text only** — it never posts anywhere. Publishing is always a
+deliberate human action (sending content to an external service is irreversible).
+
+1. **Read the source.** Pull the target section from `docs/CHANGELOG.md` — a cut
+   version (`[X.Y.Z]`) or `[Unreleased]` if `--unreleased`. If you need the raw
+   commit context, run `node contextkit/tools/scripts/draft-changelog.mjs`.
+
+2. **Draft three artifacts**, in order of shrinking length:
+   - **Release notes** (GitHub Releases / blog): a one-paragraph "why this matters",
+     then the highlights grouped by theme, then breaking changes + migration, then
+     a thank-you. Lead with user value, not commit nouns.
+   - **Short post** (~280 chars, X/Mastodon/LinkedIn): the single biggest win +
+     the version + a link placeholder `<release-url>`. No hashtag spam.
+   - **One-liner** (changelog RSS / Discord): `vX.Y.Z — <the headline change>`.
+
+3. **Tone rules.** Concrete over hype. Name the user benefit, not the internal
+   refactor. No invented metrics, no "revolutionary". If the release is mostly
+   chores, say "maintenance release" honestly rather than inflating it.
+
+4. **Hand back the drafts** for the user to review and post. Offer to save them to
+   a scratch file, but **do not publish** — no `gh release create`, no API calls,
+   unless the user explicitly asks in a follow-up.

package/templates/claude/commands/vcs/draft-changelog.md

@@ -0,0 +1,28 @@
+---
+description: Draft a [Unreleased] CHANGELOG skeleton from Conventional Commits since the last tag. Drafts only — never writes the file.
+argument-hint: [--since <tag>]
+---
+
+# 📝 Draft the changelog
+
+Build a `[Unreleased]` skeleton from the commits since the last release [ADR-0030].
+
+1. Run the drafter:
+   ```
+   node contextkit/tools/scripts/draft-changelog.mjs $ARGUMENTS
+   ```
+   It reads `git log <lastTag>..HEAD`, parses Conventional Commit subjects, and
+   groups them into Keep-a-Changelog sections (Added / Changed / Fixed / Removed /
+   Security / Documentation / Chores). `--since <tag>` overrides the range.
+
+2. **Review and humanise.** The output is a *skeleton*, not the final entry:
+   - Merge duplicate/noisy lines; drop pure-chore churn the reader won't care about.
+   - Promote any ⚠️ BREAKING change to the top and explain the migration.
+   - Reference the relevant ADR(s) where a line records a decision.
+
+3. **Paste into `docs/CHANGELOG.md`** under `[Unreleased]` yourself. This command
+   **never writes the file** — drafting is automated, the editorial call is yours.
+   To cut the version when ready, use `/close-version`.
+
+> Pairs with `/changelog-social` (turn the finished entry into announcement copy)
+> and `/close-version` (stamp `[Unreleased]` → `[X.Y.Z]` and tag).

package/templates/claude/commands/vcs/gh-triage.md

@@ -0,0 +1,41 @@
+---
+description: Triage open GitHub issues into the DevPipeline backlog — classify, prioritize, dedupe. Read-from-GitHub, write-to-backlog.
+argument-hint: [issue number | --all-open]
+---
+
+# 🗂️ GitHub issue triage
+
+Turn unstructured GitHub issues into actionable, prioritized backlog tasks
+[ADR-0030, OSS repo-ops]. This reads from GitHub and writes to the local
+DevPipeline — it does **not** close, label, or comment on issues without your OK.
+
+1. **Fetch.** Requires `gh` (the existing review provider — [ADR-0021]). If it's
+   missing or unauthed, say so and stop (rule 8 — skip, never fake):
+   ```
+   gh issue list --state open --json number,title,body,labels,createdAt,author
+   ```
+   For a single issue: `gh issue view <number> --json number,title,body,labels`.
+
+2. **Classify each issue** with the complexity rubric [ADR-0030]:
+   ```
+   node contextkit/tools/scripts/complexity-rubric.mjs classify "<issue title + gist>"
+   ```
+   - **Type** — bug / feature / chore / docs (from the body + labels).
+   - **Tier & domain** — architectural tier ⇒ flag that an ADR is needed; a
+     regulated domain (LGPD / fintech / …) ⇒ tag `@privacy-lgpd` / `@security`.
+   - **Priority** — P0 data-loss/security/broken build · P1 broken core path · P2
+     degraded · P3 cosmetic.
+
+3. **Dedupe.** Before adding, scan the existing board
+   (`node contextkit/tools/scripts/pipeline.mjs sync` then read the backlog) so you
+   don't create a duplicate of a task already tracked. Note the link instead.
+
+4. **Add to the backlog**, one per issue, cross-referencing the issue number:
+   ```
+   node contextkit/tools/scripts/pipeline.mjs add --type <bug|feature|chore> \
+     --priority <P0-P3> --source "gh#<number>" --title "<concise title>"
+   ```
+   Fill each new file's context + acceptance criteria from the issue body.
+
+5. **Report.** Summarise: triaged N issues → M new tasks (K duplicates skipped),
+   the priority spread, and any issue that needs a human decision before triage.

package/templates/contextkit/policy/complexity-rubric.json

@@ -0,0 +1,52 @@
+{
+  "version": 1,
+  "_note": "Per-task complexity rubric (ADR-0030, adapted from EVO-METHOD/BMAD domain-complexity + project-types CSVs, MIT). Deterministic lookup — NOT LLM judgment. `tiers` right-size the ceremony per task; `domains` auto-route regulated work to the owning agents and force the architectural tier. Editing a row is an ADR act (constitution §9) — it is reviewable policy, not data. Levels (L1-L7) and tiers are ORTHOGONAL: a level is the platform ceiling, a tier is the per-task ceremony.",
+  "tiers": {
+    "trivial": {
+      "signals": ["typo", "rename", "comment", "bump version", "bump dep", "lint", "format", "whitespace", "changelog entry", "fix link", "docstring"],
+      "ceremony": { "adr": false, "story": false, "review": "light" },
+      "summary": "One cohesive low-risk edit. No ADR, no story — just do it and log if it touched an important path."
+    },
+    "feature": {
+      "signals": ["add", "feature", "endpoint", "component", "screen", "page", "command", "field", "report", "export"],
+      "ceremony": { "adr": false, "story": true, "review": "standard" },
+      "summary": "A user-visible increment. Roadmap entry + story + standard review. No ADR unless a structural decision surfaces."
+    },
+    "architectural": {
+      "signals": ["migrate", "migration", "new dependency", "add dependency", "auth", "authentication", "authorization", "schema", "breaking", "rewrite", "refactor architecture", "replace", "protocol", "data model", "multi-tenant", "encryption", "rename public", "deprecate"],
+      "ceremony": { "adr": true, "story": true, "review": "deep" },
+      "summary": "A decision with blast radius. /new-adr FIRST, then a story, then deep review. /simulate-impact if it crosses a high-risk path."
+    }
+  },
+  "defaultTier": "feature",
+  "domains": {
+    "lgpd": {
+      "signals": ["cpf", "cnpj", "rg", "dados pessoais", "personal data", "dado pessoal", "lgpd", "consent", "consentimento", "titular", "data subject", "pii", "anonymiz", "anonimiz", "encarregado", "dpo"],
+      "complexity": "high",
+      "requiredAgents": ["privacy-lgpd", "security"],
+      "requiredSections": ["data-inventory", "legal-basis", "retention", "data-subject-rights"],
+      "note": "Brazilian personal-data handling (Lei 13.709/2018). High-risk by default."
+    },
+    "fintech": {
+      "signals": ["payment", "pagamento", "banking", "trading", "investment", "crypto", "wallet", "transaction", "kyc", "aml", "pci", "pix", "boleto", "charge", "subscription billing"],
+      "complexity": "high",
+      "requiredAgents": ["security", "privacy-lgpd"],
+      "requiredSections": ["compliance-matrix", "security-architecture", "audit-trail", "fraud-prevention"],
+      "note": "Money movement / financial data. Regional compliance + audit trail are load-bearing."
+    },
+    "healthcare": {
+      "signals": ["medical", "clinical", "patient", "paciente", "diagnostic", "diagnostico", "hipaa", "prontuario", "health record", "treatment", "therapy"],
+      "complexity": "high",
+      "requiredAgents": ["privacy-lgpd", "security"],
+      "requiredSections": ["clinical-requirements", "data-privacy", "safety-measures", "regulatory-pathway"],
+      "note": "Health data is sensitive personal data — privacy + safety are non-negotiable."
+    },
+    "general": {
+      "signals": [],
+      "complexity": "low",
+      "requiredAgents": [],
+      "requiredSections": [],
+      "note": "No regulated domain detected. Standard practices apply."
+    }
+  }
+}

package/templates/contextkit/runtime/config/paths.mjs

@@ -88,5 +88,7 @@ export function pathsFor(root = process.cwd()) {
     roadmap: at(`${MEMORY_DIR}/roadmap.md`),
     contractBaseline: at(`${MEMORY_DIR}/contract-baseline.json`),
     bestPractices: at(`${PLATFORM_DIR}/best-practices.md`),
+    policy: at(`${PLATFORM_DIR}/policy`),
+    complexityRubric: at(`${PLATFORM_DIR}/policy/complexity-rubric.json`),
   };
 }

package/templates/contextkit/tools/scripts/complexity-rubric.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * `/complexity` — per-task complexity classifier (ADR-0030).
+ *
+ * Deterministic lookup over `contextkit/policy/complexity-rubric.json`: classifies
+ * a task description into a CEREMONY TIER (trivial / feature / architectural) and
+ * detects a REGULATED DOMAIN (lgpd / fintech / healthcare / …) that auto-routes to
+ * the owning agents and forces the architectural tier. This is NOT LLM judgment —
+ * it is a signal-table match, so `/dev-start`, `/pipeline` and `/ship` can right-size
+ * the process the same way every time.
+ *
+ * Zero runtime deps (rule 1): JSON.parse + string matching only. Never throws —
+ * a missing/malformed rubric falls back to the embedded DEFAULT_RUBRIC so the
+ * classifier still works in a project that seeded nothing (mirrors load.mjs).
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/complexity-rubric.mjs classify "store user CPF + consent"
+ *   node contextkit/tools/scripts/complexity-rubric.mjs classify "fix typo" --json
+ *   node contextkit/tools/scripts/complexity-rubric.mjs show
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+/**
+ * Embedded fallback — kept deliberately minimal (lgpd + general + the three
+ * tiers). The shipped seed `policy/complexity-rubric.json` is the real rubric;
+ * this only guarantees classification never crashes when the seed is absent.
+ */
+const DEFAULT_RUBRIC = Object.freeze({
+  version: 1,
+  tiers: {
+    trivial: { signals: ['typo', 'rename', 'comment', 'bump version', 'lint', 'format'], ceremony: { adr: false, story: false, review: 'light' } },
+    feature: { signals: ['add', 'feature', 'endpoint', 'component', 'screen', 'command'], ceremony: { adr: false, story: true, review: 'standard' } },
+    architectural: { signals: ['migrate', 'new dependency', 'auth', 'schema', 'breaking', 'rewrite', 'encryption'], ceremony: { adr: true, story: true, review: 'deep' } },
+  },
+  defaultTier: 'feature',
+  domains: {
+    lgpd: { signals: ['cpf', 'dados pessoais', 'personal data', 'lgpd', 'consent', 'pii'], complexity: 'high', requiredAgents: ['privacy-lgpd', 'security'], requiredSections: ['data-inventory', 'legal-basis', 'retention', 'data-subject-rights'] },
+    general: { signals: [], complexity: 'low', requiredAgents: [], requiredSections: [] },
+  },
+});
+
+const COMPLEXITY_RANK = { low: 0, medium: 1, high: 2 };
+
+/** Reads the rubric for `root`, falling back to DEFAULT_RUBRIC on any failure. Never throws. */
+export function loadRubric(root = process.cwd()) {
+  const path = pathsFor(root).complexityRubric;
+  if (!existsSync(path)) return structuredClone(DEFAULT_RUBRIC);
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8').replace(/^/, ''));
+    return parsed && parsed.tiers && parsed.domains ? parsed : structuredClone(DEFAULT_RUBRIC);
+  } catch {
+    return structuredClone(DEFAULT_RUBRIC);
+  }
+}
+
+/** True when any signal occurs as a substring of the lowercased text. */
+function hasAny(text, signals) {
+  return Array.isArray(signals) && signals.some((s) => s && text.includes(String(s).toLowerCase()));
+}
+
+/**
+ * Pure classifier. Tier precedence is architectural → feature → trivial → default
+ * (higher ceremony wins on overlap — constitution §8, refuse-low by default). A
+ * high-complexity domain match FORCES the architectural tier.
+ *
+ * @param {string} input task description
+ * @param {object} [rubric] loaded rubric (defaults to the embedded fallback)
+ * @returns {object} classification with tier, domain, requiredAgents, needsAdr…
+ */
+export function classify(input, rubric = DEFAULT_RUBRIC) {
+  const text = String(input || '').toLowerCase();
+  const tiers = rubric.tiers || {};
+
+  let tier = rubric.defaultTier || 'feature';
+  if (hasAny(text, tiers.architectural?.signals)) tier = 'architectural';
+  else if (hasAny(text, tiers.feature?.signals)) tier = 'feature';
+  else if (hasAny(text, tiers.trivial?.signals)) tier = 'trivial';
+
+  // Domain detection — collect every regulated domain whose signals appear.
+  const matched = [];
+  for (const [name, def] of Object.entries(rubric.domains || {})) {
+    if (name === 'general') continue;
+    const hits = (def.signals || []).filter((s) => text.includes(String(s).toLowerCase()));
+    if (hits.length) matched.push({ name, hits: hits.length, def });
+  }
+  matched.sort((a, b) => b.hits - a.hits);
+
+  const domain = matched[0]?.name || 'general';
+  const complexity = matched.reduce(
+    (acc, m) => (COMPLEXITY_RANK[m.def.complexity] > COMPLEXITY_RANK[acc] ? m.def.complexity : acc),
+    matched.length ? 'low' : (rubric.domains?.general?.complexity || 'low'),
+  );
+  const requiredAgents = [...new Set(matched.flatMap((m) => m.def.requiredAgents || []))];
+  const requiredSections = [...new Set(matched.flatMap((m) => m.def.requiredSections || []))];
+
+  // A regulated (high-complexity) domain forces the architectural tier.
+  const forcedByDomain = complexity === 'high' && tier !== 'architectural';
+  if (forcedByDomain) tier = 'architectural';
+
+  const ceremony = tiers[tier]?.ceremony || { adr: tier === 'architectural', story: tier !== 'trivial', review: 'standard' };
+  const needsAdr = tier === 'architectural' || ceremony.adr === true;
+
+  return {
+    input: String(input || ''),
+    tier,
+    ceremony,
+    domain,
+    domains: matched.map((m) => m.name),
+    complexity,
+    requiredAgents,
+    requiredSections,
+    needsAdr,
+    forcedByDomain,
+  };
+}
+
+/** Human-readable report. */
+function formatHuman(r) {
+  const lines = [];
+  lines.push(`🧭 Complexity classification`);
+  lines.push('─'.repeat(56));
+  lines.push(`  Task        : ${r.input || '(empty)'}`);
+  lines.push(`  Tier        : ${r.tier}${r.forcedByDomain ? '  (forced by regulated domain)' : ''}`);
+  lines.push(`  Ceremony    : ADR=${r.ceremony.adr ? 'yes' : 'no'} · story=${r.ceremony.story ? 'yes' : 'no'} · review=${r.ceremony.review}`);
+  lines.push(`  Domain      : ${r.domain}${r.domains.length > 1 ? ` (+ ${r.domains.slice(1).join(', ')})` : ''} · complexity=${r.complexity}`);
+  if (r.requiredAgents.length) lines.push(`  Auto-route  : ${r.requiredAgents.map((a) => `@${a}`).join(', ')}`);
+  if (r.requiredSections.length) lines.push(`  Sections    : ${r.requiredSections.join(', ')}`);
+  lines.push('');
+  if (r.needsAdr) lines.push('  ⚠️  Run /new-adr BEFORE implementing (architectural tier).');
+  if (r.requiredAgents.length) lines.push(`  ⚠️  Regulated domain — bring in ${r.requiredAgents.map((a) => `@${a}`).join(' + ')} for this work.`);
+  if (!r.needsAdr && !r.requiredAgents.length) lines.push('  ✅ No special gate — proceed at the stated ceremony.');
+  return lines.join('\n');
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const wantJson = argv.includes('--json');
+  const cmd = argv[0] === 'classify' || argv[0] === 'show' ? argv[0] : 'classify';
+  const rubric = loadRubric(process.cwd());
+
+  if (cmd === 'show') {
+    const summary = {
+      version: rubric.version,
+      tiers: Object.keys(rubric.tiers || {}),
+      domains: Object.keys(rubric.domains || {}),
+    };
+    console.log(wantJson ? JSON.stringify(summary, null, 2) : `Tiers: ${summary.tiers.join(', ')}\nDomains: ${summary.domains.join(', ')}`);
+    return;
+  }
+
+  const text = argv.filter((a) => a !== 'classify' && a !== '--json').join(' ').trim();
+  if (!text) {
+    console.error('Usage: complexity-rubric.mjs classify "<task description>" [--json]');
+    process.exit(1);
+  }
+  const result = classify(text, rubric);
+  console.log(wantJson ? JSON.stringify(result, null, 2) : formatHuman(result));
+}
+
+// Only run the CLI when invoked directly (not when imported by selfcheck/tests).
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('complexity-rubric.mjs')) {
+  main();
+}