@yemi33/minions 0.1.2164 → 0.1.2165

package/docs/deprecated-process.md

@@ -0,0 +1,69 @@
+# Deprecation tracker — schema and audit process
+
+Source of truth: [`docs/deprecated.json`](./deprecated.json) — array of deprecation entries the `cleanup-deprecated` skill walks weekly.
+
+Each entry documents one deprecated symbol / config field / endpoint, why it
+exists, when (and under what signal) it is safe to remove, and which tests
+pin its contract until the removal lands.
+
+## Common fields
+
+The schema is loose — entries grow fields as their gating story matures. The
+following are all optional unless called out as required.
+
+- `id` — **required**, kebab-case unique identifier (e.g. `completion-fallback-parsers`).
+- `description` / `reason` — free-form prose explaining what is deprecated and why.
+- `file` / `location` / `code` — pointer(s) to the deprecated symbol(s). `code` is
+  the structured form: an array of `{ file, lines, note }` objects.
+- `lines` — comma-separated string of line numbers (drift-prone; cross-check before
+  acting).
+- `deprecated` / `targetRemovalDate` — calendar dates (YYYY-MM-DD) marking when
+  the entry was registered and when it may be removed. `targetRemovalDate: null`
+  signals a non-calendar gate (telemetry / signal-based).
+- `removalGate` — prose describing the signal that must clear before removal.
+- `notes` — free-form post-removal scope or rollout caveats.
+
+## Counter-gated entries (telemetry sentinels)
+
+When the removal gate is "this counter must read 0 across a sweep window," the
+entry uses these fields:
+
+- `telemetryGate` — string referencing the metrics counter that must read zero.
+- `sweepWindowDays` — positive integer (window length in days).
+- `sweepStartDate` — `YYYY-MM-DD` window start.
+- `enforcingTest` / `enforcingSweepWindowTest` — paths to the unit tests that
+  pin the gate contract.
+
+## Static call-site audit fields (P-c5d9e7b4)
+
+Counter-gated entries also opt in to the static call-site audit
+(`test/unit/deprecated-call-site-audit.test.js`). The audit enumerates live
+call sites of the entry's symbols across `engine/`, `dashboard/`, and the
+root-level `.js` files, then asserts every discovered call site is declared
+in either `removalSites` or `allowedCallers`.
+
+- `symbols` — **required for the audit to run**. Array of bare identifier
+  strings (e.g. `["parseStructuredCompletion", "parseCompletionFieldSummary"]`).
+  The audit builds a `\b<symbol>\s*\(` regex per name and skips matches that
+  sit immediately after the `function` keyword (i.e. it does not count the
+  definition itself as a caller). If `symbols` is missing or empty, the audit
+  fails the entry — there is no fallback parse of `description`.
+- `removalSites` — array of `{ file, line, symbol?, reason? }` objects listing
+  the call sites that WILL be removed when the deprecation gate clears (the
+  "expected, planned" callers). Paths are forward-slash relative to the repo
+  root.
+- `allowedCallers` — array of `{ site, reason }` objects (or
+  `{ file, line, reason }` — both shapes are accepted) listing call sites that
+  are intentionally preserved past the gate (e.g. a sibling deprecation that
+  will retire separately). Defaults to `[]` when absent.
+
+The audit assertion is `discoveredCallers ⊆ (removalSites ∪ allowedCallers)`.
+On failure, the assertion message names every unexpected `file:line` so the
+audit author can immediately classify each one as a new `removalSites` entry
+or a new `allowedCallers` entry.
+
+Entries WITHOUT a `telemetryGate` field are skipped by the audit — calendar-
+gated entries (e.g. `qa-json-sidecars`) and signal-gated entries that don't
+hang on a counter (e.g. `config-claude-binary-override`) don't carry the
+`symbols` / `removalSites` / `allowedCallers` triple and are not enforced by
+the static audit. Add them later if the gate evolves into a counter sentinel.

package/docs/deprecated.json

@@ -34,7 +34,14 @@
     "sweepRationale": "14 days matches the dead-code audit cadence (one full weekly audit cycle plus a buffer week). Window restarted on 2026-06-11 (= merge_date(P-a7b2c1d9) + 1 day, anchor commit eb544aa80dbd64c87b78ad08a17ca3560e627094 merged 2026-06-10T18:04:12Z) because the original 2026-05-27 window was invalidated: the engine/timeout.js caller of parseStructuredCompletion (commit 0f4b9787, 2026-04-30) predated the telemetry counter (commit cea61119, 2026-05-13), so the hidden caller was never instrumented and a zero reading proved nothing. P-a7b2c1d9 removed that hidden caller; the new window measures only callers that the counter actually instruments. Policy decision pending confirmation in open-question #1 of the 2026-05-27 Bug Audit Review meeting conclusion — if the human teammate prefers a different cadence, repin this field and the matching enforcingSweepWindowTest fixture.",
     "enforcingTest": "test/unit/completion-fallback-telemetry.test.js:217-234",
     "enforcingSweepWindowTest": "test/unit/completion-fallback-sweep-window.test.js",
-    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:3410, parseCompletionFieldSummary at :3608, and the gated fallback at :4675-4700) is dispatched separately once the window is observed clean."
+    "symbols": ["parseStructuredCompletion", "parseCompletionFieldSummary"],
+    "removalSites": [
+      { "file": "engine/lifecycle.js", "line": 4675, "symbol": "parseStructuredCompletion", "reason": "Gated fallback at engine/lifecycle.js:4675-4700 — removed in the same follow-up PR that drops the parser definitions." },
+      { "file": "engine/lifecycle.js", "line": 4676, "symbol": "parseCompletionFieldSummary", "reason": "Gated fallback at engine/lifecycle.js:4675-4700 — removed in the same follow-up PR that drops the parser definitions." }
+    ],
+    "allowedCallers": [],
+    "schemaRef": "docs/deprecated-process.md (see 'Static call-site audit fields')",
+    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:3410, parseCompletionFieldSummary at :3608, and the gated fallback at :4675-4700) is dispatched separately once the window is observed clean. The symbols/removalSites/allowedCallers triple is enforced by test/unit/deprecated-call-site-audit.test.js — see docs/deprecated-process.md for the schema."
   },
   {
     "id": "config-claude-binary-override",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2164",
+  "version": "0.1.2165",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"