npm - contextdevkit - Versions diffs - 1.8.0 - Mend

contextdevkit 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (345) hide show

package/templates/contextkit/workflows/playbooks/seo-aiso.md ADDED Viewed

@@ -0,0 +1,288 @@
+# Playbook — SEO + AISO (the two index spaces)
+> Operational entry: `/seo-audit` runs both static analysers
+> (`seo-audit.mjs` + `aiso-audit.mjs`) and the
+> [`seo-specialist`](../../squads/_BRIEFING.md.tpl) agent reads this
+> page on every invocation. Refuse-on-unindexable is the load-bearing
+> rule; this playbook is what "indexable" means in practice.
+>
+> Authority: [ADR-0025](../../memory/decisions/0025-seo-and-aiso-posture.md). Freshness: AISO conventions dated **2026-06-02** — `llms.txt` + FAQ-schema effectiveness re-evaluated quarterly.
+## Two indexes, two rule sets
+A public page lives in two index spaces at the same time and is judged
+by different signals in each.
+| Index | Crawlers | What they reward | What kills you |
+|---|---|---|---|
+| **Classical SEO** | Googlebot, Bingbot, DuckDuckBot | server-rendered HTML, semantic tags, canonical URLs, sitemap, Core Web Vitals, JSON-LD entity markup | empty `<div id="root">`, JS-rendered titles, missing `<meta description>`, CLS > 0.1 |
+| **AISO (AI Search Optimization)** | GPTBot, ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot | `llms.txt`, FAQ schema, scannable Q&A headings, semantic HTML5, author + date schema | div-soup, JS-rendered content, no FAQ schema, no `llms.txt`, robots.txt blocking AI crawlers without user opting out |
+Most projects optimise the first and ignore the second. In 2026 the
+second is a measurable distribution channel — ChatGPT search, Claude
+with web search, Perplexity, Gemini — and the gap between "ranks on
+Google" and "appears in LLM answers" is a real conversion gap.
+## SEO — the floor (refuse if missing)
+### Server-rendered HTML
+The smell that kills indexability: `curl https://your-page` returns
+`<body><div id="root"></div></body>` and the rest is JS.
+The refusal is automatic on landing surfaces (ADR-0025 + ADR-0023).
+The fix is to pick a framework that ships SSR or SSG by default —
+Astro, Next App Router (RSC), Nuxt, SvelteKit. Plain Vite + React for
+a landing page is refused; use Astro.
+### Per-page meta
+- **`<title>`** — set server-side, descriptive, unique per route.
+  Length: 50–60 chars (Google may truncate longer ones in SERPs).
+- **`<meta name="description">`** — unique per route, 120–160 chars,
+  rewrites the page in a way that earns the click.
+- **`<link rel="canonical" href="https://...">`** — absolute URL,
+  one per page. Without it Google may pick a wrong canonical and your
+  internal links scatter ranking.
+### Site-wide files
+| File | Purpose | Smell |
+|---|---|---|
+| `sitemap.xml` | lists every public route Google should crawl | absent, or stale (missing recently-added routes) |
+| `robots.txt` | tells crawlers what to fetch and what to skip | `User-agent: * Disallow: /` left over from staging |
+| `humans.txt` | optional — credit the team | absent (not a refusal, but nice) |
+### Structured data (JSON-LD)
+For a marketing site, at minimum:
+- `Organization` — the brand entity. Name, logo, sameAs (linked
+  social), URL.
+- `WebSite` with `SearchAction` — enables Google's sitelinks search
+  box.
+- `BreadcrumbList` on internal pages — shows breadcrumbs in SERPs.
+- One per content type — `Product`, `SoftwareApplication`,
+  `Article`, etc — relevant to the page.
+The JSON-LD validator is at https://validator.schema.org/. Run it on
+the rendered HTML, not the source.
+### Images
+- Every `<img>` has `alt`. Empty `alt=""` is correct for decorative
+  images (better than absent — explicit no-text-needed signal).
+- `width` and `height` attributes set — prevents CLS.
+- Modern formats: AVIF or WebP with a JPEG/PNG fallback via
+  `<picture>`.
+- `loading="lazy"` on below-the-fold images; `loading="eager"` (the
+  default) on the hero.
+- `fetchpriority="high"` on the LCP image — measurable LCP
+  improvement.
+### Core Web Vitals (ranking signal since 2021)
+| Metric | Threshold |
+|---|---|
+| **LCP** (Largest Contentful Paint) | < 2.5 s |
+| **INP** (Interaction to Next Paint — replaced FID in 2024) | < 200 ms |
+| **CLS** (Cumulative Layout Shift) | < 0.1 |
+Measure with PageSpeed Insights (lab) + Plausible / Vercel Analytics
+(real users). Lighthouse CI on every PR catches lab regressions.
+## AISO — above the floor
+### `llms.txt` at the root
+A 2024-vintage convention (https://llmstxt.org) — the analogue of
+`sitemap.xml` for AI crawlers. Format is markdown, listing the
+canonical pages an LLM should cite.
+Minimum viable `llms.txt`:
+```
+# Project name
+> One-sentence description of what the project is.
+## Docs
+- [Page title](https://example.com/page): one-line description
+- [Another page](https://example.com/another): ...
+## Examples
+- [Example 1](https://example.com/example-1): ...
+```
+The LLM crawlers that honour it (early 2026: Anthropic, partial OAI,
+partial Perplexity) get a curated routing map instead of having to
+guess from the HTML.
+### FAQ schema — the load-bearing AISO move
+LLM answer engines cite `FAQPage` JSON-LD near-verbatim. A marketing
+page with 3–5 real Q&A pairs in `FAQPage` schema shows up in
+ChatGPT / Perplexity answers; a marketing page without one does not.
+The pattern:
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [
+    {
+      "@type": "Question",
+      "name": "What is [Product]?",
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": "One-sentence concrete answer. No marketing fluff. No 'leverage synergies'."
+      }
+    },
+    // 2–4 more
+  ]
+}
+</script>
+```
+Questions to pick: the **real** customer questions, in the customer's
+words. The same 5 questions sales answers on every demo. If the team
+does not know them, ask sales for a list — the 5 that come up most.
+### Semantic HTML5
+LLM extractors weight semantic tags. `<article>`, `<section>`,
+`<nav>`, `<main>`, `<aside>`, `<header>`, `<footer>`. Not divs
+everywhere with class names that describe the same thing.
+Bad:
+```html
+<div class="article">
+  <div class="header">
+    <div class="title">Why X matters</div>
+  </div>
+  <div class="content">...</div>
+</div>
+```
+Good:
+```html
+<article>
+  <header>
+    <h2>Why X matters</h2>
+  </header>
+  <p>...</p>
+</article>
+```
+The `aiso-audit.mjs` script flags pages with a low semantic-tag ratio
+(divs : semantic > 5:1).
+### Scannable Q&A headings
+LLM summarisers look for question-shaped headings. A page with
+`## What is X?` / `## How do I Y?` / `## When should I use Z?` is
+easier for an LLM to extract than the same content as flowing prose.
+The pattern is best for help / docs / "how it works" sections, not
+for the hero. Use it on the second half of the page.
+### Author + organization schema
+LLM rankers weight authored content over anonymous. Every public
+document carries:
+- `Organization` schema (brand-level — see SEO section).
+- `Person` schema for the author when the page has one.
+- `datePublished` and `dateModified` — LLMs care about recency.
+### Robots & AI crawlers
+`robots.txt` default for a marketing site:
+```
+User-agent: *
+Allow: /
+Sitemap: https://your-domain/sitemap.xml
+# AI crawlers — explicitly named. Opt out by changing Allow: / to
+# Disallow: / under the specific user-agent block.
+User-agent: GPTBot
+Allow: /
+User-agent: ClaudeBot
+Allow: /
+User-agent: PerplexityBot
+Allow: /
+User-agent: Google-Extended
+Allow: /
+User-agent: OAI-SearchBot
+Allow: /
+```
+The `aiso-audit.mjs` script flags a `robots.txt` that blocks any of
+these without a project-local ADR opting out explicitly.
+### Avoid JS-rendered content for cited material
+Most LLM crawlers in 2026 do not execute JS reliably. The pricing
+table, the FAQ, the documentation, the marketing copy — all in the
+HTML. Reserve JS for interactivity (open the modal, animate the
+chart, toggle the menu) — never for content the user wants cited.
+## Audit codes (what the scripts emit)
+`seo-audit.mjs` and `aiso-audit.mjs` emit findings:
+```json
+{ "file": "src/pages/index.astro", "line": 12, "code": "MISSING_DESCRIPTION", "severity": "high", "message": "..." }
+```
+### SEO codes
+| Code | Severity |
+|---|---|
+| `SPA_ENTRYPOINT` | critical (refusal) |
+| `MISSING_TITLE` | high |
+| `MISSING_DESCRIPTION` | high |
+| `MULTIPLE_H1` | high |
+| `MISSING_CANONICAL` | medium |
+| `MISSING_ALT` | medium |
+| `MISSING_SITEMAP` | high |
+| `MISSING_ROBOTS` | medium |
+### AISO codes
+| Code | Severity |
+|---|---|
+| `MISSING_LLMS_TXT` | high |
+| `MISSING_FAQ_SCHEMA` | high |
+| `MISSING_ORG_SCHEMA` | medium |
+| `DIV_SOUP` | medium |
+| `JS_RENDERED_CONTENT` | high |
+| `MISSING_AUTHOR_SCHEMA` | low |
+| `MISSING_DATE_STAMP` | low |
+| `BLOCKS_AI_CRAWLERS` | high |
+## When this playbook does NOT apply
+- **Internal admin tools / dashboards behind auth** — no indexability
+  expected. The override is a project-local ADR.
+- **Single-customer apps** — same posture as admin tools.
+- **API endpoints / JSON resources** — no SEO surface.
+The seo-specialist agent respects these overrides; do not re-litigate
+them.
+## Freshness protocol
+AISO conventions are young (2024–2026). This playbook's AISO section
+carries a date. When `llms.txt` adoption stalls or a new convention
+overtakes FAQ schema, the playbook is amended via an ADR. Re-evaluate
+quarterly.

package/templates/contextkit/workflows/playbooks/simulate-impact.md ADDED Viewed

@@ -0,0 +1,83 @@
+# Playbook — `/simulate-impact`
+> Operational spec: [`.claude/commands/simulate-impact.md`](../../../.claude/commands/simulate-impact.md).
+> This page explains **why** it exists, **when** to fire it, **how to read the
+> report**, and the common **anti-patterns**.
+## Why it exists
+Three frictions motivated L5:
+1. High-blast-radius changes land **silently** without prior analysis.
+2. "Architecture before syntax" is a posture; a posture with no executable mechanism
+   becomes drift.
+3. The squad was used in **serial** delegation — `/simulate-impact` is the first
+   feature to exploit **parallelism**, multiplying the squad's ROI.
+## When to fire it
+Use it when the objective crosses **≥ 2** high-risk surfaces, e.g.:
+- a data-model / schema change;
+- a change to a shared type or validation schema;
+- a change to a public route/endpoint signature;
+- the auth or crypto surface;
+- a new service/module on a critical path;
+- direct implementation of an accepted ADR.
+**When NOT to** (it wastes tokens):
+- a bug fix with the root cause already mapped (use `/bug-hunt`);
+- a refactor with scope locked by `/dev-start`;
+- a cosmetic / i18n / comment / internal-rename change.
+## How to read the Blast Radius Report
+- **`Risk overall`** = `max(per-agent risks)`, not the average. If **High**, do not
+  proceed without understanding *which* agent said High and why.
+- **`Affected paths (union)`** becomes `coveredPaths` in the ledger. The PreToolUse
+  gate authorizes edits against this set — **if a path isn't listed, the gate blocks
+  the edit** on high-risk paths. If the simulation missed a critical path, re-run
+  with a refined objective.
+- **`Per sub-agent`** — each speaks from its own view. **Disagreement is the
+  signal** — don't reconcile it mentally. (The data agent says "trivial"; the QA
+  agent says "no fixture exists" → the real risk is in tests, not the schema.)
+- **`Mitigations`** — each needs an owner: a feature TODO, a new ADR, or an explicit
+  discard.
+- **`Decision required`** — Proceed (with mitigations), Defer (too big without an
+  ADR), or Abort (mis-scoped — re-scope).
+## Prediction-file lifecycle
+```
+/simulate-impact "<obj>"  → contextkit/memory/predictions/<date>-<sid>-<slug>.md  (pending, coveredPaths)
+implementation in the same session (or discard)
+/predictions-review       → fills "Actual": paths changed, delta vs predicted, risk note
+       (auto-run by /log-session at session end)
+```
+This corpus calibrates future simulations.
+## Anti-patterns
+1. **Firing to validate a decision already made.** It's a search for disagreement,
+   not an approval checklist. If you already know the answer, you're burning tokens.
+2. **Implementing before showing the report.** L5 requires an explicit user decision
+   among the three outcomes.
+3. **Ignoring disagreement ("5 said Low, 1 said High → Low").** Risk is max, not
+   average; the lone High *is* the signal.
+4. **Running without reading active ADRs first.** Sub-agents get the objective + a
+   domain briefing, not the full project state — anchoring in ADRs is step 1.
+5. **Forgetting to mark the ledger.** Without `mark-simulation.mjs`, the PreToolUse
+   gate blocks the next edit. It's part of the contract, not cosmetic.
+## Calibration over time
+After 10+ predictions with "Predicted vs Actual" filled in, look for systematic
+patterns (an agent that underestimates risk; a path that's always collateral but
+actually central). Refine the command's prompts; if the pattern is architectural,
+make it an ADR.
+## Relation to other L5 components
+- **PreToolUse gate** — reads the ledger's `simulations[]`; no simulation on a
+  high-risk path → it blocks.
+- **`/tech-debt-sweep`** — independent; neither requires nor produces simulations.
+- **Contract-drift gate** — independent; may flag the very change the simulation
+  predicted.

package/templates/contextkit/workflows/playbooks/tanstack.md ADDED Viewed

@@ -0,0 +1,164 @@
+# Playbook — TanStack
+> Operational entry points: `/aidevtool-from0` Phase 3 (proposing the stack),
+> `/setupcontextdevkit` Phase 4 (writing rules when detected), and the opt-in
+> starter under `templates/contextkit/starters/tanstack/`. This page is **why**
+> TanStack, **when** to pick it, **how** to live with it, and the
+> **anti-patterns** we will not write.
+>
+> Authority: [ADR-0017](../../memory/decisions/0017-tanstack-stack-recognition-and-opt-in-starter.md).
+## Why TanStack as a curated option
+TanStack is a family of headless, type-safe libraries with overlapping ergonomics
+(Query / Router / Table / Form / Virtual) and one full-stack frame (Start). The
+kit treats it as a curated option because three properties match its own
+constitution:
+- **Type safety as a first-class invariant.** Router params, Query data, and
+  Table columns are typed end-to-end — drift between intent and runtime is
+  caught by `tsc`, not by a regression. The kit's "fail fast at the boundary"
+  posture (constitution §4) inherits this for free.
+- **Headless by default.** No design-system bundled — the user owns the visual
+  layer. Matches constitution rule 9 (no invented domain content) at the
+  library level.
+- **Cache & invalidation as explicit primitives.** Query forces `queryKey` +
+  `staleTime` to be deliberate choices, not defaults. That is the same posture
+  the kit takes for ledger paths and high-risk zones: refuse by default
+  (rule 8), opt in to permit.
+## When to pick TanStack (and when not to)
+Pick it when:
+- the project is a **type-safe React** (or Solid / Vue) app and the team values
+  end-to-end inference over framework lock-in;
+- routing needs to be **co-located with the data fetching contract** (Router
+  loaders + Query) rather than scattered across page components;
+- a future migration off a backend host (BFF, edge, serverless) is plausible —
+  TanStack Start's adapter model is friendlier than baking a single host
+  assumption into routes.
+**Don't pick it (or pick a smaller subset) when:**
+- the project already commits to a full-stack framework whose router is
+  load-bearing (Next/Nuxt/Remix/SvelteKit) — adding TanStack Router on top
+  creates two routing systems; use TanStack Query *with* the framework's
+  router instead, that combination is the common case;
+- the team is new to React patterns generally — TanStack rewards developers
+  who already know what a query key, a stale time, and a suspense boundary
+  *are*. Pair it with a senior, or pick a more opinionated frame first;
+- the app is mostly **forms + CRUD on a single backend you own** — a single
+  framework router + plain `fetch` may stay simpler than wiring Query + Router
+  + Form for the same outcome.
+## The family — pick by concern, not by reflex
+| Concern | Sub-library | When to add |
+| --- | --- | --- |
+| Server state (fetching, caching, invalidation) | `@tanstack/react-query` | Any app that talks to a server. Add first. |
+| Type-safe routing | `@tanstack/react-router` | When routes carry typed params/search and loaders. Skip if the host framework already owns routing. |
+| Headless tables (sorting, filtering, virtualization-ready) | `@tanstack/react-table` | A data-heavy table with custom UI. Don't add for a simple list. |
+| Headless forms | `@tanstack/react-form` | Complex multi-step forms or strict validation. Plain `useState` + zod is fine for a contact form. |
+| Virtualized lists/grids | `@tanstack/react-virtual` | List > 200 items rendered concurrently. Premature for short lists. |
+| Full-stack frame | `@tanstack/start` | New project that wants TanStack Router + a sanctioned server story. Not for grafting onto an existing Next/Nuxt app. |
+Solid and Vue users substitute `@tanstack/solid-query` / `@tanstack/vue-query`;
+the Query conventions below are identical.
+## Core conventions (these go into the user's CLAUDE.md)
+When TanStack is detected (or chosen on greenfield), `/setupcontextdevkit` /
+`/aidevtool-from0` writes the following block into the project's `CLAUDE.md`
+under "Stack" or "Immutable rules":
+1. **Server state lives in Query, never in `useState`/Redux.** Fetch + cache +
+   invalidation are Query's job. Cross-component server data is read with
+   `useQuery` against the same `queryKey`, not propagated by hand.
+2. **`queryOptions` is the unit of reuse.** Every cross-component query is
+   declared via `queryOptions({ queryKey, queryFn, staleTime })` and consumed
+   by both `useQuery(queryOptions(...))` and `queryClient.prefetchQuery` /
+   `ensureQueryData`. No copy-pasted `queryKey` literals across files.
+3. **Cache keys are arrays, hierarchical, stable.** Shape: `['domain', 'list', filters]`
+   or `['domain', id]`. Filters are serializable. Never a stringified JSON
+   blob; never an unstable object literal in the render path.
+4. **Router params are typed via the route definition.** `Route.useParams()` /
+   `Route.useSearch()` only — never `useParams()` from a generic hook on top
+   of `window.location`. Add a `validateSearch` to anything that takes search
+   params from a URL.
+5. **`staleTime` is set deliberately on data with a known lifetime.** The
+   default `0` (always stale) is correct for dashboards; a known-static lookup
+   (countries, role list) sets `staleTime: Infinity` and invalidates on the
+   event that actually changes it.
+6. **Mutations invalidate the smallest viable key.** Don't invalidate
+   `['domain']` after a single-row update; invalidate `['domain', id]` and the
+   list keys that include it. The convention is one line of comment naming
+   the invariant the invalidation preserves.
+## Anti-patterns (caught in review)
+1. **`useState(server data)` + a manual `useEffect` to refetch.** That is
+   Query's job. Even one such pattern in the codebase signals that the team
+   has not internalized the boundary; refactor before adding more.
+2. **Untyped Router params.** `useParams<{ id: string }>()` cast at the call
+   site instead of `Route.useParams()`. The Router's whole value proposition
+   is that the route owns the type.
+3. **`data: any` in a Query result.** The whole pipeline is generic; `any`
+   defeats inference. Either give `queryFn` an explicit return type or use a
+   zod parser to narrow at the boundary.
+4. **`queryKey: [JSON.stringify(filters)]`.** Cache keys must be arrays of
+   plain values; stringification hides drift and breaks invalidation.
+5. **One giant `queryClient` configured per route.** Configure
+   `defaultOptions` once at the provider; route-specific overrides go on the
+   individual `queryOptions`. Multiple clients fragment the cache.
+6. **Adding `@tanstack/react-router` on top of Next/Nuxt/Remix.** Two routing
+   systems = two source-of-truth disputes. Pick one.
+7. **Starting from a copy-pasted "examples/" repo with a fake `Pokemon` or
+   `TodoList` domain.** Delete the fake first, then build. The opt-in starter
+   ships nothing of the sort precisely so this anti-pattern doesn't enter the
+   codebase.
+## The opt-in starter
+`templates/contextkit/starters/tanstack/` is a **minimal wiring scaffold** the
+user explicitly accepts during `/aidevtool-from0` Phase 6. It contains:
+- `package.json` with the TanStack family chosen for the project (Start +
+  Router + Query by default; user can drop subsets);
+- `src/main.tsx` with the `QueryClient` provider mounted once;
+- `src/router.tsx` with one route (`/`) that renders a placeholder asking the
+  user to wire their first real route;
+- a `README.md` pointing back to this playbook and the user-project's ADR-0001
+  recording the choice.
+What the starter **does not** ship: a fake domain, a CSS framework, an auth
+provider, a backend client, or example queries. See ADR-0017 for the five
+constraints that govern any future stack-starter under
+`templates/contextkit/starters/`.
+`/setupcontextdevkit` (existing projects) **never** copies the starter — it
+detects, writes rules, and stops.
+## Freshness
+TanStack is moving fast — especially Start. This playbook reflects conventions
+as of **2026-05**. Before relying on a specific API named here:
+1. Run `npm view @tanstack/start version` (or the sub-lib you care about) and
+   compare against the starter's `package.json`.
+2. If a major has shipped since this playbook's date, open `/new-adr "Refresh
+   TanStack playbook against vX.Y"` in the **kit** repo before changing the
+   user-project — the playbook is shared infrastructure.
+## Relation to other parts of the kit
+- **Detection** — `templates/contextkit/tools/scripts/detect-stack.mjs` surfaces
+  any `@tanstack/*` dep in `frameworks`. Consumers branch on
+  `frameworks.some(f => f.startsWith('@tanstack/'))`.
+- **CLAUDE.md scoping** — when the kit detects TanStack inside a sub-app of a
+  monorepo, the *scoped* `CLAUDE.md` for that app carries these conventions,
+  not the root one (`/claude-md scaffold` + per-app fill).
+- **QA squad** — Query-heavy apps benefit from `qa-integration` against a real
+  backend (the cache is part of the contract); `qa-fuzzer` against
+  `validateSearch` schemas catches Router parser drift.
+- **`/contract-check`** — exported `queryOptions` factories are part of the
+  public contract of a module; renaming `userListQueryOptions` is a breaking
+  change for every consumer.

package/templates/contextkit/workflows/playbooks/tech-debt-sweep.md ADDED Viewed

@@ -0,0 +1,77 @@
+# Playbook — `/tech-debt-sweep`
+> Operational spec: [`.claude/commands/tech-debt-sweep.md`](../../../.claude/commands/tech-debt-sweep.md).
+> This page is **why** the board exists, **how to read it**, and the **anti-patterns**.
+## Why it exists
+The constitution defines rules (file size, SRP, JSDoc) but the audit used to be
+manual and disposable. Without a persistent artifact, debt grows unseen, nobody sees
+the trend, and each session re-discovers the same problem.
+The debt board is the pulse of code health:
+- **versioned** — it shows up in PR review, the boot context, and `git log -p`;
+- **sectioned by bounded context** — product code vs the platform (`contextkit/`);
+- **trended** — red/yellow/info counts let you see the delta between sweeps.
+## The detectors (deterministic, regex-based)
+| Detector | Severity | Trigger |
+| --- | --- | --- |
+| **line-budget** | 🔴 above the hard limit / 🟡 in the yellow zone | File line count vs the constitution's budget. |
+| **srp-and** | 🟡 | A function/const named `doXAndY` — an "And"/"Or" responsibility smell. |
+| **jsdoc-orphan** | 🟡 | JSDoc declares N `@param` but the signature has M ≠ N. |
+| **state-loop** | 🟡 | A UI component with many state hooks + an effect (logic that belongs in a hook/helper). |
+Detectors are regex-based — **false positives are expected**. The board is input for
+human review, not a verdict.
+## How to read it
+- **Header** — last sweep time, profile, files scanned, findings by severity. If
+  `files scanned` drops sharply with no `git rm`, the scan is skipping paths — check
+  the ignored-dirs list in `tech-debt-scan.mjs`.
+- **Zero red is the goal.** Yellow is negotiable (a cohesion note can justify the
+  +10% tolerance). Info is a nit — optional.
+- **Bounded contexts** — product code takes priority; the platform tolerates a bit
+  more. A file in the yellow zone with a documented cohesion reason is expected, not
+  real debt.
+- **Each finding** has a severity icon, a clickable `path:line`, an objective
+  message, and a snippet.
+## Lifecycle
+```
+/tech-debt-sweep [profile]
+  → node contextkit/tools/scripts/tech-debt-scan.mjs --profile=X --write
+     → regenerates the board
+        → commit with the feature, or as "chore: refresh tech-debt board"
+Resolution:
+/dev-start "refactor: split <path>"  → read board → split → re-run sweep → expect a drop
+```
+## Anti-patterns
+1. **Treating findings as a bug queue ("I'll fix all 10").** A sweep is an audit,
+   not a backlog. Resolve one finding per focused `/dev-start` session.
+2. **Silencing a false positive by editing the detector.** First add a top-of-file
+   note explaining why JSDoc looks divergent, or fix the signature, or accept the
+   nit. Touching the detector is the last resort (separate PR, new code + test).
+3. **Letting the yellow zone grow "because there's a cohesion note".** The +10%
+   tolerance is for specific cases; beyond the budget without a reason is debt.
+4. **Disabling the `security` profile "because it's rare".** That profile is exactly
+   what catches auth/crypto changes when they happen — keep it configured.
+5. **Hand-editing the board.** Manual edits drift from the scan output and break
+   future diffs. Always re-run the sweep.
+## Cadence & configuration
+Profiles and cadence come from `contextkit/config.json`. Edit via `/context-config set`,
+never by hand. Add a custom profile under the sweep config the same way.
+## Relation to other L5 components
+- **`/simulate-impact`** — independent (ledger vs source code).
+- **Contract-drift gate** — complementary: the sweep measures internal health, the
+  contract gate measures external commitments.
+- **`/distill-sessions`** — can use recurring findings as a pattern signal.

package/templates/docs/CHANGELOG.md.tpl ADDED Viewed

@@ -0,0 +1,11 @@
+# Changelog
+All notable changes to {{PROJECT_NAME}} 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: ContextDevKit context platform scaffolded ({{DATE}}).

package/templates/gitattributes ADDED Viewed

@@ -0,0 +1,3 @@
+# ContextDevKit — keep engine scripts and git-hook wrappers LF on all platforms.
+contextkit/**/*.mjs text eol=lf
+.claude/**/*.json text eol=lf

package/templates/github/ISSUE_TEMPLATE/bug_report.md ADDED Viewed

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Something isn't working
+title: 'fix: '
+labels: bug
+---
+## What happened
+<!-- Clear description of the bug. -->
+## Steps to reproduce
+1.
+2.
+3.
+## Expected vs actual
+- **Expected:**
+- **Actual:**
+## Evidence
+<!-- Error message, stack trace, logs, screenshot. The more exact, the faster the fix. -->
+## Environment
+- OS / runtime version:
+- App version / commit:

package/templates/github/ISSUE_TEMPLATE/feature_request.md ADDED Viewed

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Propose a change or new capability
+title: 'feat: '
+labels: enhancement
+---
+## Problem
+<!-- What's the user/business problem? Not the solution yet. -->
+## Proposed solution
+<!-- What you'd like to happen. -->
+## Alternatives considered
+<!-- Other approaches and why they're worse. -->
+## Does this need an ADR?
+<!-- If it changes stack/library/pattern, it likely deserves /new-adr before work starts. -->