From b53db60cc10642d01af06b42b774607a61c8242a Mon Sep 17 00:00:00 2001 From: Sutu Sebastian Date: Mon, 4 May 2026 15:10:47 +0300 Subject: [PATCH] docs(plans): open C.9 framework plugin layer plan PR (skeleton) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per the parallel-plan-PR shape locked in by the just-merged research note (PR #58, docs/research/non-goals-reassessment-2026-05.md § 5): this file iterates in parallel with (a) FTS5 + Mermaid shipping; impl unblocks when its slot arrives in the cadence (T+2w → +5w per the § 5 T-table). Skeleton captures: - 5 PRE-LOCKED DECISIONS (L.1-L.5) carried over from the research note, with cross-references to specific § 6 / § 3 / § 2.3 anchors so any future challenge to these decisions has to argue against the source, not just open them as "open" questions. - 9 OPEN DECISIONS (Q1-Q9) covering the design surface that needs to crystallise during plan iteration: contract shape, discovery mechanism, schema delta, reachability algorithm, bundled starters, conflict resolution, recipe composition, community-plugin API, backwards-compat default semantics. Each gets a Resolution subsection as it crystallises (mirrors the research-note § 6 resolved-vs-open pattern). - 3-piece HIGH-LEVEL ARCHITECTURE: plugin loader + indexer hook + reachability sweep. No CLI changes; no new verb. Recipes consume the substrate (moat-A clean per L.3). - 5 IMPLEMENTATION SLICES (tracer-bullets — schema delta first, reachability recipe second, plugin contract third, starter plugins fourth, agent rule lockstep update fifth per docs/README.md Rule 10). - TEST APPROACH grounded in existing infrastructure (golden queries per docs/golden-queries.md, fixture under fixtures/golden/c9-fixture/ reproducing the closed-dead-subgraph case). - 6-row RISKS / NON-GOALS table including the abandonment escape hatch (close as Status: Rejected per docs/README.md Rule 8 if needed; design surface captured either way). Plus docs/README.md File Ownership row updated for the plans/ entry — "Empty until the first plan lands" is no longer accurate after this file lands. Per docs/README.md Rule 4 (keep ownership tables current in the same PR as the doc-file change). --- docs/README.md | 2 +- docs/plans/c9-plugin-layer.md | 100 ++++++++++++++++++++++++++++++++++ 2 files changed, 101 insertions(+), 1 deletion(-) create mode 100644 docs/plans/c9-plugin-layer.md diff --git a/docs/README.md b/docs/README.md index 07192f7..1b26372 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,7 +21,7 @@ Each topic has exactly one canonical file. Other files cross-reference by relati | [fixtures/qa/](../fixtures/qa/) | [prompts.external.template.md](../fixtures/qa/prompts.external.template.md) — optional chat QA prompts for an external index (`*.local.md` gitignored). | | [packaging.md](./packaging.md) | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets; **`bun run version`** + oxfmt **`CHANGELOG.md`**). | | [roadmap.md](./roadmap.md) | Forward-looking [**Backlog**](./roadmap.md#backlog) and [**Non-goals**](./roadmap.md#non-goals-v1) (not a `src/` inventory). | -| [plans/](./plans/) | One `.md` per in-flight plan. Created on demand — don't add the `-plan` suffix; the folder provides context. Empty until the first plan lands. | +| [plans/](./plans/) | One `.md` per in-flight plan. Created on demand — don't add the `-plan` suffix; the folder provides context. Currently in flight: [`c9-plugin-layer.md`](./plans/c9-plugin-layer.md). | | [research/](./research/) | Dated, snapshot-style notes (e.g. competitive scans). Each note links shipped items back to canonical homes — see [research/competitive-scan-2026-04.md](./research/competitive-scan-2026-04.md). | --- diff --git a/docs/plans/c9-plugin-layer.md b/docs/plans/c9-plugin-layer.md new file mode 100644 index 0000000..4924921 --- /dev/null +++ b/docs/plans/c9-plugin-layer.md @@ -0,0 +1,100 @@ +# C.9 Framework plugin layer — plan + +> **Status:** open · plan iterating in parallel with **(a) FTS5 + Mermaid** shipping (per [`docs/research/non-goals-reassessment-2026-05.md § 5`](../research/non-goals-reassessment-2026-05.md#5-recommended-next-pick-under-the-new-framing)) +> +> **Motivator:** **closed-dead-subgraph case** — N-file packs where every file imports a sibling (non-zero `dependencies` fan-in for all) but none is reachable from a real entry point. Today's `untested-and-dead` recipe false-positives Next.js `app/**/page.tsx` files for the same reason: framework entry points aren't recognized as live without per-framework awareness. This plan proposes the smallest plugin contract that closes the gap. +> +> **Tier:** XL effort (per the research note's § 5 (b) row). Shipping cadence is sequential after (a) + (c); this plan iterates in parallel so impl is unblocked when its slot arrives. + +--- + +## Pre-locked decisions (from non-goals-reassessment grill) + +These are committed to v1. Questions opened against them must justify against the linked decisions. + +| # | Decision | Source | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| L.1 | **Entry-point hints only** (Shape A — `glob → is_entry: true` annotations on `files`). No arbitrary `dependencies` edge injection. | [§ 6 Q4 resolved](../research/non-goals-reassessment-2026-05.md#6-open-questions); [§ 2.3 caveat](../research/non-goals-reassessment-2026-05.md#23--no-static-analysis) | +| L.2 | **Static config only** — plugins describe rules in static config (globs, glob → annotation mappings). No JS evaluation at index time. | [§ 3 ergonomic floor "No JS execution at index time"](../research/non-goals-reassessment-2026-05.md#3-true-architectural-limits--preserve) | +| L.3 | **Moat-A clean** — recipes consume the new substrate via SQL; no new verdict-shaped CLI verbs. | [§ 3 Moat A](../research/non-goals-reassessment-2026-05.md#3-true-architectural-limits--preserve) | +| L.4 | **Moat-B aligned** — `is_entry` annotation IS substrate growth (richer extracted structure on `files`). New schema column or table. | [§ 3 Moat B](../research/non-goals-reassessment-2026-05.md#3-true-architectural-limits--preserve) | +| L.5 | **No edge injection in v1** — defer to v2 if a real recipe demands it; backwards-compat preserved (additive). Mirrors `query_baselines` deferral discipline. | [§ 6 Q4 resolved](../research/non-goals-reassessment-2026-05.md#6-open-questions) | + +--- + +## Open decisions (iterate as the plan converges) + +These are the design questions the plan-PR resolves before impl starts (per the parallel-plan-PR shape). Each gets a section below as it crystallises. + +- **Q1 — Plugin contract shape.** JSON schema (declarative)? Zod-validated TS module (typed)? Markdown-with-frontmatter (mirrors recipe-as-content registry per PR #37)? What fields beyond `entry_globs`? +- **Q2 — Plugin discovery mechanism.** npm peerDep registration (mirrors community-adapter pattern from [`roadmap.md § Strategy`](../roadmap.md#strategy))? Path-glob auto-discovery from `/.codemap/plugins/`? Config-listed (`codemap.config.ts` `plugins: [...]`)? Some combination? +- **Q3 — Schema delta.** `is_entry INTEGER DEFAULT 0` column on `files` (single boolean) vs separate `entry_annotations(file_path, plugin_id, reason)` table (multiple plugins can co-annotate; preserves provenance). The latter is moat-B-aligned but slightly more storage. +- **Q4 — Reachability sweep algorithm.** BFS from `is_entry` files over `dependencies`? Materialised `is_reachable` column (cheap reads, expensive write)? On-demand recursive CTE (no materialisation; might be slow on big graphs)? Cache invalidation strategy? +- **Q5 — Bundled starter plugins for v1.** Next.js (`app/**/page.tsx`, `pages/**/*.{ts,tsx}`, `app/**/layout.tsx`, etc.)? Vite (`vite.config.{ts,js}`, HTML `