contextdevkit 1.8.1 → 1.9.0

package/docs/CHANGELOG.md

@@ -1,559 +0,0 @@
-# Changelog
-
-All notable changes to VibeDevKit are documented here.
-Format based on [Keep a Changelog](https://keepachangelog.com/).
-This project adheres to [Semantic Versioning](https://semver.org/).
-
-## [Unreleased]
-
-Add your changes here. Use sub-sections: Added / Changed / Fixed / Removed.
-
-### Added
-- **Token-economy digest layer IMPLEMENTED — [ADR-0027](../vibekit/memory/decisions/0027-token-economy-digest-layer.md)
-  (session 37, PR #41).** Shipped all 3 phases of the digest layer that lets commands
-  reason over compact output instead of raw markdown: `runtime/hooks/md-extract.mjs`
-  + `session-digest-core.mjs` (shared pure parsers) + `tools/scripts/session-digest.mjs`
-  (`/distill-sessions` + `/retro` rewired); `boot-context-readers.digestLatestSession`
-  shrinks the boot banner from 60 raw lines to a ~6-line digest with a raw fallback
-  (never empties), plus `context-pack.mjs` collapsing `/dev-start` + `/state` into one
-  call; `adr-digest.mjs` catalog + `--search` for `/ship` + `/new-adr` + `/deep-analysis`.
-  23 selfcheck assertions + a behavioural digest/raw-fallback test; `npm test` green.
-  ROADMAP items marked ✅ (PR #42). ADR-0027 Accepted; backlog 058–060 concluded.
-- **Token-economy digest layer (design) — [ADR-0027](../vibekit/memory/decisions/0027-token-economy-digest-layer.md)
-  (session 36).** Recorded the decision + plan to **reduce token consumption** by
-  pre-digesting deterministically in scripts so the AI reasons over compact output
-  instead of raw markdown. Audited the 65 commands + boot hook: the biggest
-  single-run cost is reading the **last ~10 session logs raw** (~13–16K input
-  tokens before reasoning); the highest-frequency cost is the boot banner injecting
-  60 raw lines every session. Proposed a `lib/digest/` shared extractor +
-  `session-digest.mjs` + `adr-digest.mjs` + `context-pack.mjs` + a boot rewire
-  (digest with raw fallback). New `docs/ROADMAP.md` section + `docs/token-economy-plan.md`
-  (per-command savings table ≈ **120–200K input tokens/week** on an active project,
-  5-phase rollout, guardrails) + DevPipeline backlog **058 / 059 / 060** (one per
-  phase). **No code shipped** — design/planning only (ADR-before-implementing).
-- **GitHub sync awareness in the dev flow — [ADR-0026](../vibekit/memory/decisions/0026-github-sync-awareness-dev-flow.md)
-  (session 35).** New zero-dep `templates/vibekit/tools/scripts/sync-check.mjs`
-  with two modes: `preflight` (run by `/dev-start` before coding — ahead/behind,
-  in-flight branches, and **open PRs with CI/review status**, flagging PRs
-  *awaiting status*) and `prepr` (run by `/git pr` before push — re-check
-  divergence vs the default branch and **detect a duplicate open PR** for the
-  current branch). `gh` is optional: absent/unauthed degrades to the git-only
-  half and reports the PR check as *skipped, never a pass* (Rule 8); offline ⇒
-  silent. PR queries stay **off** the SessionStart hot path (Rule 2); the script
-  is read-only. Wired into `pipeline/dev-start.md` + `vcs/git.md`; 8 selfcheck
-  assertions added.
-- **Landing-page + media generation + SEO/AISO — 3 ADRs (0023/0024/0025),
-  1 new agent, 2 playbooks, 5 scripts, 3 slash commands, 6 pipeline
-  tickets (052–057, session 34).** A coordinated drop addressing the user
-  request for "skills de UX e UI" for high-conversion landing pages,
-  Veo + Nano Banana integration, and an SEO specialist with AISO
-  (AI Search Optimization).
-
-  **ADRs (3).** [ADR-0023](../vibekit/memory/decisions/0023-landing-page-and-conversion-posture.md)
-  records the landing-page posture: fold rules (min 3 / ideal 5–7 / max 9),
-  anti-Lovable refusals (gradient hero, three feature cards, three-tier
-  pricing, testimonial slider, Inter font, Heroicons), dated package
-  recommendations (Astro recommended, Tailwind + tokens, Motion, Lucide,
-  Plausible, GrowthBook), performance budget (LCP < 2.5 s, INP < 200 ms,
-  CLS < 0.1). [ADR-0024](../vibekit/memory/decisions/0024-media-generation-veo-nano-banana.md)
-  records the media-generation adapter contract — five points
-  (no SDK, refuse-on-missing-creds, typed return, refuse-on-content-policy,
-  per-process cost cap) — and the deferred content-addressed cache
-  (ticket 056). [ADR-0025](../vibekit/memory/decisions/0025-seo-and-aiso-posture.md)
-  records the SEO + AISO posture, the audit-first stance, AISO as a
-  first-class concern (`llms.txt`, FAQ schema, semantic HTML5, author +
-  date stamps), and refuse-on-unindexable for landing surfaces (full
-  refuse-gate parked as ticket 057).
-
-  **Agent (1 new).** `templates/claude/agents/seo-specialist.md` —
-  design-team squad member. Audit-first; refuses unindexable SPAs;
-  refuses JS-rendered content for cited material; respects project-local
-  ADR overrides. Pairs with `landing-architect`, `ui-designer`,
-  `ux-designer`, `accessibility`, `code-reviewer`.
-
-  **Playbooks (2).** `templates/vibekit/workflows/playbooks/landing-page.md`
-  carries the anti-Lovable substitution table (editorial hero,
-  in-context testimonials, decision-tree pricing, inline FAQ for AISO)
-  and the package-recs table dated 2026-06-02. `templates/vibekit/workflows/
-  playbooks/seo-aiso.md` carries the SEO checklist (server-rendered HTML,
-  meta tags, sitemap, robots, structured data, images, CWV) + the AISO
-  checklist (`llms.txt`, FAQ schema, semantic HTML5, scannable Q&A
-  headings, author + date schema, robots.txt AI-crawler block detection).
-
-  **Media-gen system (5 files).**
-  `templates/vibekit/runtime/providers/media/_adapter.mjs` — contract +
-  `MediaProviderError` (7 codes: NO_CREDENTIALS, CONTENT_POLICY,
-  COST_CAP_REACHED, RATE_LIMIT, PROVIDER_ERROR, BAD_INPUT, IO) +
-  `validateAdapter` + `assertCredentials` + `noteCostOrThrow` (shared
-  per-process cost-cap tally read from `VIBEDEVKIT_MEDIA_MAX_USD`).
-  `nano-banana.mjs` — Imagen 3 image generation via `node:fetch`
-  (`POST /v1beta/models/imagen-3.0-generate-002:predict`, dated
-  2026-06-02). `veo.mjs` — Veo 3 video generation with the long-running
-  operation poll loop (`predictLongRunning` → poll until `done:
-  true` → download bytes or follow `uri`). `templates/vibekit/tools/
-  scripts/media-gen.mjs` — CLI entry with positional `image|video`,
-  `--prompt`, `--out`, `--provider`, `--aspect-ratio`, `--duration`,
-  `--model`, `--sample-count`, `--dry-run`, `--help`. New
-  `templates/vibekit/.env.example` template ships at the kit's vibekit
-  root; commented; `install.mjs` seeds it write-if-missing.
-
-  **Audit scripts (3 files).**
-  `templates/vibekit/tools/scripts/audit-shared.mjs` (~110 lines) —
-  `walkProject` (recursive walk skipping `node_modules`, `.git`, build
-  caches), `detectFramework` (Astro / Next / Nuxt / Remix / SvelteKit /
-  Gatsby / 11ty / `vite-react` / `null`), `lineOf`, `renderFindings`
-  (severity-grouped coloured terminal output), `exitCodeFor` (1 on any
-  `critical`). `seo-audit.mjs` (~125 lines) — 8 codes
-  (SPA_ENTRYPOINT critical; MISSING_TITLE/DESC/SITEMAP/MULTIPLE_H1 high;
-  MISSING_CANONICAL/ALT/ROBOTS medium); SPA-entry-point detection reads
-  `index.html` for `<div id="root\|app\|__next\|___gatsby"></div>` and
-  flags only when framework detection is `vite-react` or `null`.
-  `aiso-audit.mjs` (~130 lines) — 8 codes (MISSING_LLMS_TXT/
-  FAQ_SCHEMA/JS_RENDERED/BLOCKS_AI_CRAWLERS high;
-  MISSING_ORG_SCHEMA/DIV_SOUP medium; MISSING_AUTHOR/DATE low);
-  div-soup ratio threshold 5:1; AI-crawler block detection covers
-  GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot.
-
-  **Slash commands (3).** `/seo-audit` lands in the `audit/` pack (per
-  ticket 047's taxonomy). `/landing-page` + `/media-gen` at root
-  (utility commands, like `/dashboard` and `/watch`). `commands/README.md`
-  taxonomy updated to list the three new commands.
-
-  **Pipeline tickets (6).** 052 / 053 / 054 in `testing/` (shipped
-  this session). 055 (`.env.example` install integration follow-up) +
-  056 (media-gen cache) + 057 (SEO refuse-gate in `code-reviewer`)
-  parked in `backlog/` with explicit acceptance criteria, dependencies
-  declared via the ticket-040 DAG (`dependencies: ["053"]`, etc.) and
-  T-shirt complexity (S/M).
-
-  **Tests (rule 3).** 33 new selfcheck assertions covering every shipped
-  surface — every adapter export, every audit-code constant, every
-  playbook anchor, the `127.0.0.1`-only spirit (`/media-gen` is
-  network-only, no localhost binding involved; `assertCredentials` is
-  the equivalent guard). All 7 integration suites green.
-
-  **Smoke-tested end-to-end.** `seo-audit --json` against this repo
-  emitted truthful findings (no sitemap, no robots.txt, missing meta
-  description in the TanStack starter's `index.html`). `aiso-audit
-  --json` flagged no `llms.txt` and the missing FAQ schema in the
-  starter. `media-gen image --prompt "test" --out tmp.png --dry-run`
-  detected nano-banana as the image adapter and showed
-  `GOOGLE_AI_API_KEY ✗ missing` — the refuse-on-missing-creds path
-  works without making any network call.
-
-- **Backlog sweep — 5 Compozy follow-through tickets shipped (session 33,
-  `main`).** Single `/dev-start` resolved the remaining open backlog from
-  ADRs 0018–0022; one worktree + one PR per ticket, squash-merged on green
-  CI (Node 18/20/22). **PR #29 ticket 040** (commit `42ed8c8`) — task
-  metadata v2: `dependencies: []` (strict DAG, no cycles), `complexity:
-  S\|M\|L\|XL`, extended `type` enum with `spike` + `docs`, new
-  `pipeline validate` subcommand, board `↘ blocked by N` hint, new
-  `pipeline-validate.mjs` sibling. **PR #30 ticket 047** (`9787969`) — 39
-  of 58 slash commands moved into `qa/ vcs/ forge/ pipeline/ audit/
-  setup/` subfolders (daily 20 stay at root); new `commands/README.md`
-  documents the taxonomy; selfcheck walk made recursive + new
-  basename-collision invariant. Claude Code resolves by basename →
-  invocations unchanged. **PR #31 ticket 046** (`c54b6bb`) — new
-  `/resume` re-binds the current session to an unregistered drift
-  ledger via `resume.mjs` (reads `listAllLedgers` from the runtime,
-  single-sourced); three rule-8 refusal paths (unknown id / already
-  registered / cross-session claim conflict); atomic `.last-touched`
-  rewrite. **PR #32 ticket 043** (`bb5c132`) — new `distill-detect.mjs`
-  scans the just-written session narrative for 10 Tier-1 rule-like
-  patterns ("we decided" / "from now on" / "always" / "never" /
-  "convention:" / "lesson learned"); proposal-only (never auto-invokes
-  `/distill-sessions`); skips headings + blockquotes to dodge false
-  positives; wired into `/log-session` as step 6. **PR #33 ticket 041**
-  (`8dd35a3`) — new `/workflow` macro chains roadmap → ADR → pipeline →
-  ship via a per-slug breadcrumb in `vibekit/memory/workflows/<slug>.md`;
-  `new` / `advance` / `status` subcommands; each phase is an explicit
-  user action (rule 9, no silent chaining). **Plus:** new
-  `tools/integration-test-compozy.mjs` sibling extracted from
-  `integration-test-guards.mjs` (responsibility seam — guards stays
-  input-rejection-focused; lifecycle tests for 041 / 043 / 046 live in
-  the sibling). +24 selfcheck behavioural asserts + 16 integration
-  lifecycle asserts across the five PRs. All 7 test suites green;
-  tech-debt CI gate: 0 RED-zone findings across 138 files. **049
-  (Extension SDK) and 050 (Run dispatcher) remain in `backlog/`** —
-  confirmed rule-9 parking tickets (type `spike`, P4, `sla:` empty,
-  explicit trigger conditions per ADR-0018 / ADR-0022). Bug **038**
-  (install in worktree) was also closed earlier in the same conversation
-  (PR #27, commit `4c3ed59`).
-- **`/dashboard` — visual project state in HTML, snapshot or live
-  (ticket 051, session 33)**. Zero-dep, pure `node:` stdlib. Two modes
-  from one entry: `node vibekit/tools/scripts/dashboard.mjs` writes a
-  self-contained `dashboard.html` (inline CSS + vanilla JS, no external
-  assets — opens by double-click, works offline); `--watch` spawns a
-  tiny `node:http` server bound to **127.0.0.1 only** (default port
-  `4242`, override via `--port=N` or `VIBEDEVKIT_DASHBOARD_PORT`) that
-  serves the page plus a `text/event-stream` endpoint on `/events`. An
-  `fs.watch` on the platform dir (200 ms debouncer) rebuilds the data
-  object and pushes it; the page reconnects on disconnect and patches
-  the DOM in place. Heartbeat every 15 s on idle. Four modules, each
-  under the 280-line budget: `dashboard-data.mjs` (~160 lines —
-  single owner of "read project state": pipeline lanes, ADRs,
-  sessions, roadmap, `[Unreleased]` CHANGELOG; single-sources
-  `PLATFORM_DIR` via `paths.mjs` per rule 4; exports
-  `parseFrontmatter` so other scripts can reuse the YAML reader);
-  `dashboard-html.mjs` (~180 lines — purely functional renderer with
-  `escapeHtml` everywhere, CSS Grid for the 4-column kanban,
-  `prefers-color-scheme` light/dark, type/priority/ADR-status colour
-  badges); `dashboard-server.mjs` (~115 lines — `startDashboardServer`
-  + `resolvePort` exports; defensive everywhere — `fs.watch`
-  failures log and continue; SSE clients tracked in a `Set` and
-  cleaned up on `req.close`); `dashboard.mjs` (~110 lines — CLI
-  dispatch, `--help`, clean SIGINT). New
-  `templates/claude/commands/dashboard.md` documents both modes and
-  the non-goals (read-only, no remote access, no JS framework, no
-  persistent state). 11 new selfcheck assertions covering every
-  shipped surface including the `127.0.0.1`-only bind. Smoke-tested
-  both modes: snapshot writes a 68 KB self-contained file; live mode
-  serves 69 KB on `127.0.0.1:14242` with the SSE client-script
-  appended.
-- **`home.mjs` — single owner of `~/.vibedevkit/` resolution + atomic
-  write contract (ticket 048 → testing; ADR-0020 follow-up)**. New
-  `templates/vibekit/tools/scripts/home.mjs` (~95 lines, zero-dep)
-  exports three functions: `resolveHome()` honours `VIBEDEVKIT_HOME`
-  with lazy directory creation; `readHomeFile(name)` returns `null`
-  on absent/malformed/wrong-version files (an *explicitly unknown*
-  `version` triggers a timestamped `.bak.<ms>` and a fresh start —
-  absent `version` is treated as legacy and adopted, so existing
-  `fleet.json` is not destroyed on first read); `writeHomeFile(name,
-  data)` writes atomically via `tmp.<pid>` + `renameSync`, stamping
-  `version: 1` when absent. `fleet.mjs` migrated to delegate to the
-  helper — `VIBE_FLEET_FILE` (used by the integration test as a path
-  override) keeps its precedence, so existing tests continue to pass
-  without changes. 6 new selfcheck assertions
-  (`resolveHome` / `readHomeFile` / `writeHomeFile` exports,
-  `renameSync(tmp, path)` atomic-write pattern, `VIBEDEVKIT_HOME`
-  honoured, `fleet.mjs` imports the helper). Smoke-tested end-to-end
-  with `VIBEDEVKIT_HOME=<tmpdir>`: list → add → list round-trip works
-  and the persisted file carries `"version": 1`. ADR-0020 promised
-  "any next home-scoped consumer (preferences, telemetry cache)
-  inherits the contract for free" — that promise is now real.
-- **5 new ADRs + 11 pipeline tickets from the Compozy comparison pass**
-  (session 30, `feat/tanstack-support`). Compared VibeDevKit against
-  `D:\compozy-main` and extracted what fits the constitution. Five **ADRs**
-  land the architectural decisions: **ADR-0018 — Extension SDK** (subprocess
-  JSON-RPC contract sketched; *implementation deferred* until a first external
-  author signals interest; rule-9-driven refusal of the speculative half),
-  **ADR-0019 — MCP injection in squads** (optional `mcpServers:` field in
-  agent frontmatter with required `rationale`; `optional: true` default
-  means the agent loads without the server; no shipped agent declares one
-  yet — convention only), **ADR-0020 — Workspace registry global**
-  (formalises `~/.vibedevkit/` with `VIBEDEVKIT_HOME` override, lazy
-  creation, plain JSON + `version` field, atomic tmp+rename; lists what
-  belongs there and what does *not* — no ADRs, no sessions, no SQLite, no
-  daemon), **ADR-0021 — Provider strategy for review/QA** (thin adapter
-  contract at `templates/vibekit/runtime/providers/review/` with `gh` as the
-  shipped seed; missing CLI is a refusal not a fallback — rule 8;
-  `/git` and `/qa-signoff` keep calling `gh` directly until the next
-  consumer justifies the rewrite), **ADR-0022 — Run dispatcher** (direction
-  accepted; implementation deferred behind three explicit trigger
-  conditions; locks the `dependencies: []` DAG semantics for ticket 040
-  so the future implementation does not retrofit free-text). **Three green
-  items** implemented this session: (a) **two-tier memory** via
-  `templates/vibekit/pipeline/.gitignore` excluding `*.scratch.md` +
-  one-line addition to `/dev-start` describing the per-task scratch
-  convention (ticket 042 → testing); (b) **review providers adapter
-  scaffold** — `_adapter.mjs` (contract + `ProviderError` + `validateAdapter`),
-  `detect.mjs` (`resolveAdapter` resolves from `vibekit/config.json` →
-  origin auto-detect → refusal; single-sources `PLATFORM_DIR` from
-  `paths.mjs` per rule 4), `gh.mjs` (thin `spawnSync` wrapper around
-  `gh pr create / api / pr comment`; throws typed `ProviderError` codes
-  `CLI_MISSING | AUTH | NOT_FOUND | REMOTE_REJECTED | BAD_INPUT | PARSE`)
-  (ticket 044 → testing); (c) **`/watch` slash command** —
-  `templates/vibekit/tools/scripts/watch.mjs` reuses
-  `readMostRecentLedger` from the runtime (single-sourced session
-  resolution), default prints the ledger and exits, `--follow` re-polls
-  every 500ms and exits cleanly on SIGINT, never prints "0 entries" as
-  soft success (refused-silently-to-false-negative) (ticket 045 →
-  testing). **One yellow seed**: `templates/claude/agents/_TEMPLATE.md`
-  gains a commented-out `mcpServers:` block pointing to ADR-0019 — new
-  agents read the convention without any shipped agent using it yet.
-  **Eleven pipeline tickets** (040–050) scaffolded: 040 metadata v2
-  (dependencies DAG + complexity + spike/docs types), 041 `/workflow`
-  macro, 042 two-tier memory (testing), 043 auto memory compaction at
-  `/log-session`, 044 review providers seed (testing), 045 `/watch`
-  (testing), 046 `/resume` for interrupted sessions, 047 skill packs by
-  domain (commands subfolders), 048 `home.mjs` helper for ADR-0020,
-  049/050 are the trigger-watch tickets parking ADR-0018 and ADR-0022
-  behind explicit conditions. **13 new selfcheck assertions** in
-  `tools/selfcheck-source.mjs` covering every shipped surface: agent
-  template documents `mcpServers` + `rationale`; the three adapter
-  module exports; the `/watch` `parseLedgerEntry` export + command
-  file; the pipeline `.gitignore` rule; `/dev-start`'s scratch line.
-  `npm test` green end-to-end (selfcheck + 5 integration suites).
-- **agent-forge — Fase 6: declarative pipeline DSL + dry-run engine shipped
-  on a worktree** (session 30, commit `eae2fee` on
-  `feat/agent-forge-fase6-pipeline-dsl`). Closes ADR-0015 Part A — the
-  forge orchestration becomes a diffable, simulate-impact-mappable plan.
-  New `templates/vibekit/squads/agent-forge/pipeline.yaml` declares 9
-  steps with one bounded retry loop (eval-gate → generate-prompt,
-  max_cycles: 3) and two conditional steps (`generate-tools` when
-  `blueprint.tools.length > 0`, `generate-rag` when
-  `capabilities.rag == true`). New engine
-  `templates/vibekit/tools/scripts/squad-pipeline.mjs` (252 lines) parses
-  via `lib/yaml.mjs` (ADR-0013 dynamic import); **refuses on missing
-  `yaml` with exit 0 + informative message** — pipelines are opt-in, not
-  hot-path. Sibling `squad-pipeline-condition.mjs` (192 lines) is the
-  whitelisted parser — only `<id>(.<id>)* <op> <literal>` and `…length
-  <op> <int>` (no function calls, no boolean chaining, no arithmetic, no
-  type coercion). `--dry-run` walks the graph against empty ctx and
-  prints `✓ / ⊘ / ↺` markers. `max_review_cycles` is a hard cap (engine
-  exits "manual escalation required" rather than looping). Vendor model
-  names are refused in YAML — only `model_tier: fast|powerful|reasoning`
-  (router stays the single resolver). Canonical spec
-  `docs/SQUAD-PIPELINE-FORMAT.md` (258 lines). 2 new selfchecks
-  (`checkConditionParser` + `checkSquadPipeline`, 8 asserts) +
-  4 new integration asserts. agent-forge ROADMAP Fase 6 → ✅. **NOT
-  shipped this turn** (deferred to tasks 040/039 in the worktree
-  backlog): `state.json` per run, DevPipeline `working/` stage,
-  cross-session task ownership.
-- **ADR-0017 — TanStack stack recognition: detection + curated playbook +
-  opt-in empty starter** (session 29). `templates/vibekit/tools/scripts/
-  detect-stack.mjs` `known` list extended with the TanStack family
-  (`@tanstack/react-query`, `react-router`, `react-table`, `react-form`,
-  `react-virtual`, `start`, plus `solid-query`/`vue-query`) — existing
-  projects on TanStack are no longer invisible to `/setupvibedevkit`. New
-  `templates/vibekit/workflows/playbooks/tanstack.md` (165 lines) is the
-  curated *why/when/how*: the family table (pick by concern), the **Core
-  conventions** block injected into the user's `CLAUDE.md` (server state in
-  Query never `useState`, `queryOptions` as the unit of reuse, hierarchical
-  cache keys, typed Router params, deliberate `staleTime`, minimum-key
-  invalidation), the anti-patterns review will catch, the explicit
-  Next/Nuxt/Remix conflict ("don't stack two routers"), and the freshness
-  protocol. `/aidevtool-from0` Phase 3 references the playbook when the
-  architect proposes TanStack; `/setupvibedevkit` Phase 4 inherits the
-  conventions block on detection. New `templates/vibekit/starters/tanstack/`
-  (10 files, 165 lines total) is a Router + Query + Vite skeleton offered
-  opt-in by `/aidevtool-from0` Phase 6 — **no invented domain** (one
-  placeholder route), no CSS framework, no backend choice, no example
-  query, copy-and-step-aside (no upgrade path). TanStack Start documented
-  as an upgrade path rather than shipped (Start's tooling has been evolving
-  fast; pinning to a moving target would ship fragility). `install.mjs`
-  now `copyTree`s `vibekit/starters/` on every install. Selfcheck
-  (`tools/selfcheck-source.mjs`) gains seven cases asserting detection
-  pattern, playbook presence, starter deps (`react-router` + `react-query`),
-  wiring (`QueryClientProvider`, `RouterProvider`), and installer copy —
-  without prescribing version numbers (owned by the playbook's freshness
-  protocol).
-
-- **ADR-0016 — Best-practices restructured: 2-tier rubric, split into rubric
-  + protocol, stack-agnostic, security routed out** (session 25). The
-  rubric was 69 lines, flat, hygiene-only; the auditor led with line counts
-  instead of architecture. Now: `templates/vibekit/best-practices.md`
-  (323 lines) carries the rubric — risk model, **Tier 1 System &
-  architecture** (S1 dependency direction, S2 boundaries, S3 coupling/cycles,
-  S4 state location), **Tier 2 Module & function hygiene** (H1–H7) — each
-  rule with the **Principle / Smells / Fix / Don't over-apply** shape that
-  calibrates the auditor against false positives. New companion
-  `templates/vibekit/review-protocol.md` (214 lines) carries the protocol —
-  severity vocabulary `BLOCKER`/`HARD`/`CANDIDATE`/`NIT` mapped onto the
-  scanner's existing 1..5 scale, scope clauses (Tier 2 relaxed for spikes),
-  the run-the-analysis steps, the report shape, and an honest **Scanner
-  Map** listing only the four detectors that actually exist
-  (`detectLineBudget`, `detectSrpAnd`, `detectReactStateLoop`,
-  `detectTodoMarkers`) plus the `vibekit/detectors/*.mjs` plug-in slot.
-  Deliberately rejected (recorded in the ADR): a Tier 2 — Security
-  (duplicates `code-security`/`security`/`infra-security` and
-  `/audit`/`/deps-audit`/`/security-setup` — routed out via *Adjacent
-  concerns* instead); stack-coupled examples (Supabase/RLS/zod/NEXT_PUBLIC,
-  rule 9); a `// vibe-allow §ID` pragma (not implemented); promised but
-  absent detectors (cycles, secrets, `any`-counter); a parallel severity
-  scale (would drift from the `--ci` gate). Dogfood install mirrored.
-
-- **ADR-0015 — Pipeline DSL, `working/` stage, and multi-session work-claims**
-  (session 24, proposed). One ADR opens two adjacent moves, sharing one
-  substrate (`state.json` per in-flight item). **Part A:** declarative
-  `pipeline.yaml` per squad (steps + `condition` + `on_reject` +
-  `max_review_cycles` + `model_tier` + `type: checkpoint`) with a `squad-
-  pipeline.mjs` engine — opt-in per squad, parses via `lib/yaml.mjs`
-  (ADR-0013 dynamic import), refuses on missing `yaml` with a clear message,
-  whitelisted `condition` grammar (no arbitrary expression eval), no vendor
-  model names in YAML (the router stays the single resolver), dry-run is a
-  first-class mode. **Part B:** a `working/` stage in the DevPipeline that
-  holds *only WIP*, leaving `testing/` for QA sign-off; `/pipeline start
-  <id>` and `/pipeline stop <id>` attach/detach the task to the workspace
-  record (`.claude/.workspace/<sid>.json` gains a `tasks[]` array), the
-  dashboard surfaces which session owns which task, stale auto-eviction
-  defaults to 90m without a heartbeat. **Part C:** canonical `state.json`
-  schema covers both task-in-flight and pipeline-run; future `/runs` lists
-  the last N across squads. Inspired by a read of opensquad's declarative
-  pipeline, *not* a copy — the kit's zero-dep + model-router + simulate-
-  impact invariants reshape the grammar. Roadmap markers updated:
-  agent-forge ROADMAP gains Fase 6 (task 036, 📋); `docs/ROADMAP.md` gains
-  a "Next" block before the design invariants; agent-forge ROADMAP "Net
-  additions" lists 5 new ADR-0015-driven net additions. No code touched
-  this turn — only the ADR + roadmap + this entry.
-
-### Added
-- **PR [#19](https://github.com/reiTavares/VibeDevKit/pull/19) merged to
-  `main`** (session 27, rebase strategy — individual commits preserved).
-  Ships agent-forge Fases 1–5 (ADR-0012), ADR-0015 roadmap markers,
-  ADR-0016 tiered rubric + companion review-protocol + rewritten
-  `/analyze-code-ia-practices`, and the first BLOCKER cleared by the new
-  rubric (task 036, integration-test-tooling split). 10 commits land on
-  main; local `main` fast-forwarded.
-
-### Changed
-- **selfcheck-checks.mjs split by invariant category + checkLevelsAndSchema
-  SRP split** (session 28, task 037, **PR [#20](https://github.com/reiTavares/VibeDevKit/pull/20)
-  merged to `main`** as `db0632c`) — second pair caught by the ADR-0016 rubric. The 253-line yellow-zone file carried 5 distinct
-  invariant categories under one umbrella; the rubric's H1 and H2
-  (`checkLevelsAndSchema` SRP-and) drove a split by responsibility into
-  three siblings: `tools/selfcheck-runtime.mjs` (113 — boot readers,
-  atomic I/O, sid sanitization, squad meta), `tools/selfcheck-config.mjs`
-  (80 — level taxonomy and zod schema, with `checkLevelsAndSchema` itself
-  split into `checkLevels` + `checkSchema`), `tools/selfcheck-source.mjs`
-  (123 — source-level patterns, rule 4 enforcement, SHA-pinned workflows;
-  hosts the shared `listMjs` walker). The orchestrator `tools/selfcheck
-  -checks.mjs` was deleted (no compatibility shim — rule 9). `tools/selfcheck
-  .mjs` now imports + dispatches the three new runners plus the two
-  pre-existing agent-forge ones; gained a cohesion note (241 lines, in the
-  ~308 tolerance band). `tools/selfcheck-agent-forge.mjs` updated to import
-  `listMjs` from the new source module. All five integration suites pass;
-  tech-debt scan emits zero severity-5 findings; SRP-and finding cleared.
-- **integration-test-tooling.mjs split by responsibility** (session 26, task
-  036 — first BLOCKER caught by the new ADR-0016 rubric). The file was 321
-  lines (> 308 RED) carrying ~23 subsystems. Extracted the internally-coupled
-  DevPipeline chain (add → ingest → idempotent → prioritize → wsjf → bugs,
-  ~39 lines) into a focused sibling `tools/integration-test-tooling-pipeline.mjs`
-  with its own fixture + reporter (one extra L5 install — cost paid for
-  isolation). Updated `tools/it-helpers.mjs` header to list all four
-  integration files; added the new sibling to `npm test` and `prepublishOnly`
-  scripts. The remaining tooling file is 285 lines (yellow zone) with a
-  documented cohesion note ("one fixture install, many tool scripts") and a
-  flagged next seam (agent-forge round-trip) for when budget pressure
-  returns. All 4 integration suites pass; `tech-debt-scan --ci` no longer
-  reports a RED-zone finding.
-- **`/analyze-code-ia-practices` rewritten + factual fix** (session 25,
-  ADR-0016). Command now reads both rubric files
-  (`best-practices.md` + `review-protocol.md`), walks Tier 1 (judgment, no
-  scanner help) before Tier 2 (scanner findings), routes adjacent concerns
-  (security, a11y, privacy, deps) to specialist agents instead of absorbing
-  them. Also corrected a long-standing factual drift: the command
-  previously claimed the scanner produced `missing-doc` findings — a
-  detector that has never existed in `tech-debt-detectors.mjs` — and
-  omitted `todo-marker` which does exist. Replaced with the four real
-  detectors and their actual severities.
-- **Distillation cycle 1 — refuse-by-default + defer-to-demand promoted to the
-  constitution** (session 23, ADR-0014). After agent-forge Fases 0–5 closed,
-  the 25 net additions on the squad ROADMAP surfaced two recurring postures
-  the constitution didn't have written down. `CLAUDE.md` rules 8 + 9 added
-  (refuse-over-rubber-stamp + build-what-is-asked); rule 1 refined with a
-  positive-split criterion. 140 → 170 lines (under the 200-line nudge). No
-  code touched — the cycle codifies patterns already practiced.
-
-### Added
-- **agent-forge — Fase 5: RAG designer + Go runtime + L5 gate + /fleet Forge
-  Stats** (session 22, task 035). Closes the original blueprint. New
-  `lib/rag-designer.mjs` (multilingual-vs-english embedding from
-  `intent.domain`, pgvector vs qdrant from residency, recursive chunking
-  tightened for extraction, `top_k` by complexity, hybrid + reranker on by
-  default). Packager writes 5 `rag/` files when `capabilities.rag: true` and
-  stamps the Go adapter (`go.mod` + `{{MODULE_PATH}}`). `defaults.l5.
-  highRiskPaths` now ships with `agent-packages/**` — every forged-agent edit
-  triggers the simulate-impact gate. `fleet.mjs cmdStats` aggregates per-repo
-  Forge Stats + a fleet total line. Selfcheck split by responsibility: build
-  pipeline stays in `selfcheck-agent-forge.mjs` (225 lines), ops checks moved
-  to `selfcheck-agent-forge-ops.mjs` (107 lines). New `rag-designer.md`
-  briefing — refuses pinecone-under-no-cloud and `top_k < 4`. **All Fases
-  0–5 are ✅; backlog is 0.**
-- **agent-forge — Fase 4: production maintenance + Forge Stats + docs**
-  (session 21, task 034). 13 new `/forge-*` slash commands (list/show/doctor/
-  policy/budget/audit/eval/redteam/route/fallback-test/refresh-matrix/
-  killswitch/deprecate) wired through 3 CLI modules + `lib/package-ops.mjs`.
-  Node runtime adapter ships a `createShadowEval` scaffold. `/vibe-stats`
-  gains a Forge Stats section. New reference docs `docs/SQUADS/agent-forge.md`
-  + `docs/AGENT-PACKAGE-FORMAT.md`. Selfcheck `checkPackageOps` + 19
-  inventory entries. ROADMAP Fase 4 ✅.
-- **agent-forge — Fase 3: governance + eval gate** (session 20, task 033). The
-  refuse-to-ship layer. Three new pure zero-dep modules: `lib/eval-designer.mjs`
-  (`designEvalSet` — seed golden by intent.category + universal red-team + rubric
-  + thresholds derived from blueprint privacy/sla/cost; PII-leak block rate forced
-  to 1.0 when `pii_present`), `lib/eval-runner.mjs` (`runEvalSuite` —
-  provider-agnostic; mock for CI, real adapter for prod; supports `exact` /
-  `exact_set` / `numeric_tolerance:N` / `semantic_similarity:>=N`; aggregates p95
-  latency + cost), `lib/governance-officer.mjs` (`attachGovernance` populates 3
-  pillars from blueprint + fallback chain from router decision; `validateGovernance`
-  refuses on missing sections OR `{{TOKEN}}` placeholders; **throws**). Packager
-  now calls `attachGovernance` first (throws before any I/O), writes 4 populated
-  governance YAMLs + 4 populated eval files, and stamps `provenance.eval_passed_at`
-  only when `opts.evalResult.verdict === 'pass'`. `forgeNew` gains opt-in
-  `runEval = { provider, semantic }` that runs the gate before packaging. Two
-  agent briefings ship: `eval-designer.md` + `governance-officer.md`. 11
-  behavioural selfchecks + 6 integration asserts. ROADMAP §6/§7 ✅; Fase 3 ✅.
-- **agent-forge — Fase 2: multi-provider + Python runtime** (session 19, task 032).
-  All five providers now flow end-to-end: Gemini (`systemInstruction` body +
-  safetySettings note; `functionDeclarations` adapter strips JSON-Schema fields the
-  parser rejects), DeepSeek (OpenAI-compat + explicit CoT cue prepended to Rules),
-  Ollama (Markdown body, per-model `chat_template` applied by the host).
-  `packager.mjs` writes the full 5 prompts + 5 tool adapters every package and
-  stamps `{{AGENT_NAME}}` / `{{SEE_LICENSE}}` into Node `package.json` + Python
-  `pyproject.toml` (and their READMEs) when those runtimes are requested.
-  `runtime_adapters` is now a first-class blueprint field (`enum-multi` over
-  `[node, python, go]`, default `[node]`) — `validateBlueprint` rejects unknown
-  entries; `assembleManifest` stamps `spec.runtime_adapters` straight from the
-  blueprint. Integration test gains 7 new asserts. ROADMAP §5 prompt/tool generators
-  flipped ✅. Suite green.
-- **agent-forge — Fase 1, the model-router engine** (session 18, ADR-0012 §5).
-  `lib/router.mjs` (`routeAgent`, pure zero-dep) + `router/decision-rules.json` (13
-  rules, cap 15, shortlists only — no hardcoded quality claims). Filters candidates by
-  capability + residency, enforces a cross-provider fallback, throws on
-  `abort_if_no_candidate`, emits the canonical Model Selection Rationale with the
-  eval-as-authority disclaimer. New `checkRouterEngine` behavioural test (typical +
-  on-prem blueprints). **Refactor**: agent-forge selfchecks moved to
-  `tools/selfcheck-agent-forge.mjs` (real responsibility seam; `selfcheck-checks.mjs`
-  back to 251 lines). Squad ROADMAP §4.3 / §4.4 / §12 → ✅. Task 031 now 2/7.
-- **agent-forge — Fase 0 foundations** (session 17, ADR-0012). New optional L4+
-  *factory* squad that forges portable, multi-provider Agent Packages for projects
-  outside the kit. Added the squad scaffold (`vibekit/squads/agent-forge/` README +
-  `best-practices.md`), a dated/ADR-gated `capability-matrix.json` with a parse/id
-  selfcheck guard, and the full APF v1 template tree (45 files). Agents + `/forge-*`
-  commands land in Fases 1–5 (031–035). PR #18.
-- **DevPipeline backlog cleared (all 25 tasks)** — session 16. Fixed: git-call
-  timeouts (007), boot truncation/tie-break (009/010), partial-preset crash (013),
-  atomic writes + collision-safe ids (011), live-ledger race (008). Security:
-  sanitizeSid everywhere (012), SHA-pinned Actions + least-privilege CI (019/020),
-  README trust section + installer hook backup (021/022). Added: guards test suite
-  (014–018), detectors seed (026). Changed: single-source level taxonomy + passthrough
-  schema [ADR-0010] (024/025), single-source paths via pathsFor [ADR-0011] (023),
-  shared readJsonSafe/squadOf (027/028), line-budget cohesion + nits + selfcheck split
-  (005/006/029). No public API removed.
-- Released: **v1.4.0 (npm + GitHub)** — onboarding defaults + level-cap fixes.
-- Changed: **recommended start level by project type** (ADR-0009) — installer auto-picks
-  **L3** (greenfield) / **L7** (existing) instead of always L2; docs retagged (LEVELS.md
-  now has L6/L7 sections + "Where to start"; both instrucoes; README quickstart).
-- Fixed: **level cap stuck at 6** — `install.mjs` downgraded `--level 7`→2 and `doctor.mjs`
-  flagged L7 as out of range; both accept 1–7 now. Stale 1-5/1-6 range hints corrected.
-- Released: **v1.3.0 (npm + GitHub)** — launches the **L7 "Ecosystem & Scale"** tier
-  (`/vibe-level 7`, capability tier, no new hook) + all post-1.2 capabilities.
-- Added: **L7 as a real level** — `getLevel` 1→7, labels, `--level 1-7`, `vibe-level 7`,
-  selfcheck/integration coverage. [ADR-0008]
-- Added: **Diverse & visual testing harness (MVP)** — `/visual-test` + `visual-test.mjs`
-  scaffold Playwright (JS + Python) starters; wired into scaffold-tests/qa-signoff/ship.
-  [ADR-0007]
-- Added: **Fleet mode (MVP)** — `/fleet` + `fleet.mjs`: a control plane over many
-  repos (registry at `~/.vibedevkit/fleet.json`; aggregate `stats`/`audit`; detect
-  CLAUDE.md rule drift). Roadmap #2.
-- Added: **Outcome-driven agent tuning (MVP)** — `/tune-agents` + `agent-tuning.mjs`
-  propose briefing refinements (applies nothing). Roadmap #3.
-- Added: **Editor/CI surfaces (MVP)** — status-line widget (`statusline.mjs`) +
-  `quality.yml` CI workflow (contract-drift + tech-debt gates). Roadmap #4.
-- Added: **Pluggable detectors & stack presets (MVP)** — `vibekit/detectors/*.mjs`
-  drop-ins + `install.mjs --preset next|go|python`. Roadmap #5.
-- Changed: **Split two RED-zone files** off the constitution gate — `integration-test.mjs`
-  (→ core + tooling + `it-helpers.mjs`) and `session-start.mjs` (→ `boot-signals.mjs`);
-  behaviour-identical, gate green.
-- Added: **`code-security` agent** — security-team sub-specialist for the code's
-  external surface (integration code, dependency provenance/SBOM, SAST/CodeQL).
-- Added: **GitHub-native security** — `.github/dependabot.yml` + an advisory
-  `security.yml` workflow (dependency-review + deps-audit + CodeQL), `gh-alerts.mjs`
-  (Dependabot/code-scanning alerts → DevPipeline backlog), and a `/security-setup` command.
-- Changed: **`/deps-audit` grown into a dependency policy** — license allow/deny,
-  CycloneDX SBOM (`--sbom`), lockfile-drift, driven by a new `deps` config block.
-- Added: ROADMAP "supply-chain & code security" section (shipped) + a roadmap
-  **status convention** (`⏳ in progress` alongside `✅`/`📋`/`🟡`) in `docs/ROADMAP.md`
-  and the installed-project template `templates/vibekit/memory/roadmap.md`.
-- Added: VibeDevKit context platform scaffolded (2026-05-22).