docs: close out the plugin-philosophy program (PLAN final state, slice pruned) - #319
Merged
Conversation
Cross-PR continuity and durable outcomes now live on the tracker: epic #313 with wave sub-issues #314-#318. The PLAN's final state is pasted into the PR description. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01M1owJj9ZzkV36V3C1CyX4a
Contributor
|
Claude finished @kyle-sexton's task in 3m 0s —— View job PR #319 Review
This is a zero-diff close-out PR by design. The branch committed the PLAN's final state (all 7 phases DONE, 3 empirical verdicts recorded), then pruned the contract slice per the topic-docs lifecycle the program itself shipped — resulting in a net-zero diff on merge. I verified the program's durable deliverables are all present and correct on main. Deliverable verification
Security (REVIEW.md)No concerns. Zero net diff means no tracked-file additions. All REVIEW.md blocking checks (secrets in tracked source, injection, authorization) are vacuously satisfied; nothing new to analyze. One minor observationThe Phase 1 sanity check SummaryClean close-out. The program's durable state lives in the tracker (#313–#318, epic #313) and in the squash commit message / PR description; the branch contributes exactly zero net change to main files. The self-referential elegance — pruning the contract slice using the lifecycle the program shipped — is intentional and correct. |
kyle-sexton
added a commit
that referenced
this pull request
Jul 25, 2026
…1323) ## What this PR lands One file: `docs/adr/0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md`. The branch carried the full contract slice for this effort while the work was in flight — 13 blind section digests, the ratified decision set, the collision register, the agent brief, and the source article, all under `docs/topics/context-engineering-rightsizing/`. Per `docs/conventions/topic-docs/README.md:290-309` that slice is task-branch-only: durable outcomes graduate, follow-ups route to the tracker, and a final commit prunes the slice. That lifecycle is now complete on this branch: - **Graduated** — the ratified decision set, the execution errata, the conflict definition D-4 ships against, and the incumbent-gate blind spot are promoted into ADR 0004. - **Routed** — the D-6 fable-5 follow-up is filed as #1324. - **Pruned** — `22744fd664` removes the contract slice. `git diff --name-only main...HEAD` returns exactly the one ADR path, satisfying the enforcement rule at `README.md:305-309`. ## The digests were produced blind Thirteen agents each read one section of the source article with no sight of the others' output and no sight of this repository's prior conclusions. All thirteen reported clean fences. The convergences between them are therefore independent measurements rather than echoes, which is what makes the repeated findings load-bearing — and what the ADR's "Context" section rests on. The digests themselves are working material, not durable knowledge, so they prune rather than graduate. What survives is the arbitration posture they converged on (D-15) and the incumbent-first gate (D-1) that the pass proved was worth paying for. ## Three decisions were refuted by measurement — recorded, not executed The ratified text of all nineteen decisions is preserved verbatim in the ADR. Where first-hand measurement contradicted a decision's supporting evidence, the correction sits beside it as errata and the lane **stopped rather than re-deciding**: - **D-12** — its cited 2 ms control never ran; both comparators failed at launch. The directive (fix the root cause) stands and only the citation is corrected. The real defect is worse than the decision assumed: the guards are substantially fail-open. - **D-13** — **deferred, not executed.** The removal set is empty. All ten zero-invocation seeded plugins are hook plugins, for which zero transcript invocations is the expected reading of a correctly functioning one. - **D-17** — **deferred, not executed.** Diagnosis confirmed, prescription unexecutable: the move aborts `chezmoi apply` fleet-wide with a hard template error. Both deferrals await operator re-decision. Nothing was committed on their behalf in any repository. ## Deliberate, disclosed collision Branch `docs/context-engineering-claude-5-topic` (PR #1322) covers the same source article and is worked by a parallel session. The operator ruled that this pass runs independently and that the collision is resolved at merge, not by folding. The ADR records this as a standing constraint rather than as a register entry, because the register was working material and prunes with the slice. ## What the pruned register taught, and why only the lesson survives The collision register presented three writers on `dot_claude/CLAUDE.md` as the complete set when there were four (dotfiles PR #319, open and editing that file mid-pass). The missing row cost nothing — it merged before colliding — but the false completeness is the finding, and two lanes were dispatched trusting it. The register is not preserved; the generalizable lesson is, in the ADR: re-derive collisions from `gh pr list` at the moment of acting rather than trusting a snapshot. ## Verification Gates run locally on the changed slice before pushing: `markdownlint-cli2`, `typos`, `editorconfig-checker`, `lychee`, `gitleaks`, and `scripts/check-docs-only.sh`. All clean, nothing suppressed. No machine-specific paths, no `.work/` citations, and no shell or shebang files in the committed result. ## Related **No linked issue** — this PR closes nothing. It lands the durable design record; the execution lanes it dispatched carry their own issues and PRs. Refs #1324 — the D-6 follow-up covering `plugins/playbooks/skills/fable-5/**`, excluded from this pass while PR #1261 rewrote it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Plugin-philosophy program close-out (PR D)
Final PR of the plugin-philosophy program chain: PR A #257 (doctrine + official-docs index), PR B #292 (topic-docs contract 2.0.0), PR C #310 (marketplace metadata wave), and this close-out. Net diff is intentionally zero: the branch carries the PLAN's final state (all seven phases DONE, all three empirical verdicts recorded) and then prunes the contract slice per the topic-docs lifecycle this very program shipped. The PLAN's durable outcomes have graduated to the work-item tracker.
No linked issue.
Related
sensitiveplaintext verdict (blocked-upstream), deferred CI-gate backlog.Program outcome
worktree.baseRef: "head",.worktreeinclude, by-value returns, tracker index) with the repo's own R1/R2 files landed and the Versioning rule amended honestly.versionverified absent from every entry.sensitivestorage = plaintext (secrets excluded from the userConfig wave, blocked upstream).PLAN.md — final state (contract slice, pruned in this PR per its own lifecycle)
plugin-philosophy
Brief
TLDR
Extend the plugin doctrine to the full current component surface (13 component types, official docs
fetched 2026-07-17), lock a native-first principle with a maturity gate, fix the topic-docs two-tier
convention's visibility seams with native mechanisms, ship a complete official-doc link index, adopt
marketplace metadata maximally — then run a fanout conformance audit of all 47 plugins whose findings
graduate to tracker-managed remediation waves.
Goal
Every plugin measurably conforms to an extended, freshness-guarded doctrine; no custom mechanism
exists where a fitting native one does; every cross-plugin convention has exactly one registered
owner doc; the remediation program lives on the work-item tracker where any session or machine can
resume it.
Locked decisions
dependenciesreserved for hard requires (plugin genuinely broken without collaborator) — none exist today; the{name}--v{version}git-tag release step lands with first use. Optional collaboration stays presence-gated with documented fallbacks; artifact protocol unchanged (data handoff, which dependencies don't cover).paths,context: fork,arguments, skill-scopedhooks/once— adopted case-by-case);commands/prohibited (officially legacy); agents, MCP, LSP, output styles,bin/= adopt-on-need (bin/requires collision-safe prefixed names; doctrine notes plugin agents ignorehooks/mcpServers/permissionMode); pluginsettings.jsonagent(main-thread takeover) prohibited by default, exception needs documented justification; monitors, themes, channels = wait (experimental/immature), re-verified against current docs before each audit; dependencies per D5. Hooks addition: exec-form (args) mandatory wherever${user_config.*}appears (v2.1.207), else theCLAUDE_PLUGIN_OPTION_<KEY>env mirror.type,defaultpreserving zero-config behavior,requiredonly where truly blocking,sensitive: truefor secrets,claude plugin install --configdocumented in each setup skill for headless use. Shell consumers read the nativeCLAUDE_PLUGIN_OPTION_<KEY>mirror; custom env vars retired. Ownership table otherwise unchanged. GuardrailsHOOK_<NAME>_ENABLEDtoggles = flagship migration (userConfig booleans,default: true).setup,disable-model-invocation: true,check(read-only inspect/verify) +apply(idempotent configure) actions, complete-args non-interactive path. Formatter/linter plugins gain thin check-centric setups. NativeSetuphook event = sanctioned headless/CI init surface; SessionStart +${CLAUDE_PLUGIN_DATA}manifest-diff = sanctioned runtime-dependency idiom.lib/hook-utils.shsync, report vocabularies, artifact protocol, seam phrasing); registry names and points, never restates; audit rule = per-row conformance; a new convention lands in an owner doc before a second plugin adopts it.docs/topics/name (contents are transient topic-scoped contract docs;docs/specs/is already the durable vault target — renaming would conflate tiers).worktree.baseRef: "head"in committed repo settings so worktree-isolated spawns carry task-branch state; R2.worktreeincludewith targeted memory-tier patterns (stage ledgers, EXPLORE/RESEARCH — not baselines/raw scratch; one-way creation-time copy documented); R3 pointer discipline — durable surfaces (tickets, committed PLAN) never point at prunable or gitignored paths (decompose cites the PR, not the contract path; PLAN records distilled baseline values only); R4 isolated workers return results by value, the orchestrator writes both tiers in the parent checkout; R5 the work-item tracker is the cross-lane awareness/index layer (branch files stay lane-local; markdown-in-tickets as primary artifact store rejected — not diffable, drifts from code); R6 topic-docs convention doc corrected (worktree-visibility rationale, context×tier visibility matrix, mechanisms named) — a major contract version adopted by all implementers in one wave.docs/OFFICIAL-DOCS.md— complete categorized map of plugin-relevant official pages with a component→doc-page table, per-row verified-dates, the D7 staleness disclaimer, andhttps://code.claude.com/docs/llms.txtnamed as the authoritative self-updating master list. CLAUDE.md keeps its lean canonical table plus one pointer row to the index.relevancesignals wherever meaningful (audit criterion per plugin),defaultEnabled: falsefor personal/niche-category plugins,displayNamewhere it genuinely clarifies, complete descriptive metadata. Consumer-facing doc section on org enablement of suggestions (pluginSuggestionMarketplaces+ source declaration in managed settings). Hard rule:versionlives in plugin.json only, never in marketplace entries (silent-precedence trap).Constraints
wave; this Brief's doc facts were verified 2026-07-17.
docs/plugin-philosophy; PRs required, squash merge, PR titleper Conventional Commits.
in the same release wave (the contract carries no compatibility machinery).
defaultvalues (guardrails toggles defaulttrue).Acceptance criteria
adoption gate (D3/D4), convention registry (D11), config ownership updated (D8 criterion, exec-form
rule, version-placement rule), setup criteria (D9), prerequisite-visibility rule (D10).
touchpoints).
docs/OFFICIAL-DOCS.mdexists: complete categorized page map, component→doc table, verified-dates,staleness disclaimer, llms.txt master pointer; CLAUDE.md carries the pointer row and stays lean.
.worktreeinclude, and R3 skill pointer fixes (decompose ticket provenance, architect baselinerecording) landed; the three flagged execution-time verifications resolved empirically and
recorded.
claude plugin validate .passes.47-plugin row scored; raw details in the memory slice.
Captured assumptions
clients degrade per official behavior, not worked around.
org-agnostic (no solo-consumer scoping).
Out-of-scope (deferred with triggers)
the fleet-sync skill.
future doc re-verification (D6 wait rows).
music→creative, deployment category, and other plugin-organization deferrals remain owned bythat Brief.
Deferred questions
sensitiveuserConfig storage behavior (docs silent on Windows keychain) — empiricalverification during audit, before any secret migrates. Arbiter:
/architect(execution evidence).--bgsession worktree base semantics;worktree.baseRefhonored at project-settings scope — empirical smoke tests during D13 execution.Arbiter:
/architect.relevancesignal quality (which signals are genuinely helpful vs noise) — decidedper-plugin during the metadata wave. Arbiter:
/architect.Plan
Seven phases. Doctrine docs land first (D16 ordering), the topic-docs contract major version ships as
one wave, marketplace metadata follows, and the fleet audit runs last against the landed doctrine.
The fresh-docs mandate is embedded as the first work item of every phase that states platform
facts — never a standalone phase, never skipped.
The three flagged empirical verifications resolve at their Brief-assigned execution points:
worktree-semantics smoke tests → Phase 4 (gates Phase 5 R1/R2); per-plugin
relevancequality →Phase 6 (per-plugin, during the metadata wave); Windows
sensitiveuserConfig storage → Phase 7(before any userConfig-wave issue touching secrets is filed).
Phase 1: PLUGIN-PHILOSOPHY.md doctrine revision [DONE]
Covers D3, D4, D6, D7, D8, D9, D10, D11.
Work items:
plugins,plugins-reference,skills,hooks,settings,plugin-dependenciespages; re-verify the 13 component types and the D6 stance facts (skill frontmatter additions,
commands/legacy status,bin/rules, agent field limitations, monitors/themes/channelsmaturity, v2.1.207 exec-form rule). Any drift from the Brief's 2026-07-17 facts is recorded in
the memory slice and the stance table reflects current reality. The verified component-type
count (N, expected 13) is written to
.work/plugin-philosophy/component-count.txt— Phases 1and 3 sanity checks assert against N, not a hard-coded 13.
official-doc link (D7 rider), and the D7 staleness disclaimer heading the table.
schema fields,
CLAUDE_PLUGIN_OPTION_<KEY>mirror, retirement of custom env channels), exec-formhooks rule, version-placement rule (
versionin plugin.json only).uniform
setupskill contract,Setuphook event and SessionStart manifest-diff idioms).visibility, OTel as candidate channel, no black boxes).
(topic-docs binding, skill layout + evals schema,
lib/hook-utils.shsync, report vocabularies,artifact protocol, seam phrasing); registry names and points, never restates.
Sanity Check:
grep -c "Verified 2026" docs/PLUGIN-PHILOSOPHY.md≥ N (one rider per stance row; N fromcomponent-count.txt).grep -n "Convention registry\|Native-first" docs/PLUGIN-PHILOSOPHY.mdreturns both sections.npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/PLUGIN-PHILOSOPHY.mdexit 0 (CI'spinned action is authoritative; local run uses the repo config).
Phase 2: MIGRATION-PLAYBOOK.md consistency pass [DONE]
Depends on Phase 1 (doctrine wording is SSOT; playbook points, never restates).
Work items:
exec-form hook rule — each as a pointer to the philosophy doc section plus playbook-specific
procedure only.
sensitiveuserConfig handling,bin/collision-safe naming, pluginsettings.jsonagentprohibition check.tables).
Sanity Check:
grep -n "PLUGIN-PHILOSOPHY" docs/MIGRATION-PLAYBOOK.mdshows pointer citations in the gate andsecurity-review sections.
both
ComponentandStancecolumns (Read assertion — pointers naming the section are fine).npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/MIGRATION-PLAYBOOK.mdexit 0.Phase 3: docs/OFFICIAL-DOCS.md index + CLAUDE.md pointer [DONE]
Covers D14. Parallel-safe with Phase 2 (disjoint files); component list comes from the Brief/Phase 1
stance table.
Work items:
https://code.claude.com/docs/llms.txt; enumerate every plugin-relevant page.docs/OFFICIAL-DOCS.md: categorized page map, component→doc-page table, per-rowverified-dates, D7 staleness disclaimer, llms.txt named as the authoritative self-updating
master list.
verified component list (
component-count.txt+ stance table) before PR A — parallel work offthe Brief snapshot must converge on Phase 1's fresh-fetched reality.
Sanity Check:
test -f docs/OFFICIAL-DOCS.md&& component table has N rows (N fromcomponent-count.txt).grep -n "llms.txt" docs/OFFICIAL-DOCS.mdandgrep -n "OFFICIAL-DOCS" CLAUDE.mdboth hit.git diff origin/main...HEAD --stat -- CLAUDE.mdshows a 1-2 line delta.
npx markdownlint-cli2 --config .markdownlint-cli2.jsonc docs/OFFICIAL-DOCS.mdexit 0; therepo's offline link-integrity check passes on the new file (external-URL lychee lane is advisory
weekly — spot-check a sample of new URLs via WebFetch instead).
Phase 4: Worktree-semantics empirical verification (throwaway spike) [DONE]
Feasibility spike (might change Phase 5's shape) — results are evidence, no kept code. Parallel-safe
with Phases 1–3 (touches scratchpad + throwaway worktrees only).
All tests run in a throwaway
git initrepo in the scratchpad with a syntheticorigin—never in this repo (its ~30 live worktrees, runtime-written
.git/info/exclude, and main checkouton a feature branch confound every measurement). Use
claude -p --worktreeexclusively (skips thetrust dialog; interactive mode errors in a fresh repo). Unique worktree names per run (name reuse
resets clean worktrees to base since v2.1.208); the spike removes its own worktrees
(
-p-created worktrees are never auto-cleaned; Windows: expect NTFS lock retries,git worktree remove --force).Work items:
worktreesdoc (the doc anchor forbaseRef/.worktreeinclude— not thesettings page) plus
settings; record cited behavior, including the documented fallback"when
origin/HEADisn't resolvable, worktrees fall back to current local HEAD".worktree.baseRef: "head"at project-settings scope, two arms: control(
baseRefunset or"fresh") asserts marker ABSENT; treatment (baseRef: "head"incommitted
.claude/settings.json) asserts marker PRESENT. Verdict HONORED only if BOTH armsbehave — a marker-present-only test is defeated by the documented origin/HEAD fallback (false
positive). Variant A2: spawn from within an existing linked worktree (docs state
headresolvesto that worktree's HEAD — test against that expected value). Variant A3:
settings.jsonpresentonly in the worktree checkout vs only in the main checkout — pins which copy a linked-worktree
session reads (undocumented; only
settings.local.jsonis documented as main-checkout-resolved)..worktreeincludeone-way creation-time copy: use real nested-gitignore paths(
.work/<slug>/…ignored via a nested*.gitignore, mirroring this repo) — not a toyroot-level pattern; assert copy at creation; modify original, assert no sync-back.
the only source of truth; capture
git status --ignoredsnapshots in the raw transcript) +--bgsession worktree base semantics..work/plugin-philosophy/verifications/, stamps everyVERDICT file with
claude --version, and returns the VERDICT lines by value; the mainsession fills the pending rows in this PLAN's "Empirical verification results" table (PLAN.md
edits stay main-session-only) and feeds them into Phase 5's R1/R2 design. If the CC version has
moved by the Phase 5 gate, re-run the cheap test-A control/treatment pair.
Sanity Check:
.work/plugin-philosophy/verifications/contains ≥ 3 result files, one per smoke test, eachending in a one-line VERDICT (
HONORED/NOT-HONORED/ behavior description) and aclaude --versionstamp line.control:andtreatment:lines with opposite marker outcomes(else verdict is invalid by construction).
(pending)).Phase 5: Topic-docs contract 2.0.0 + seam fixes R1–R6 (one wave) [DONE]
Covers D13. Contract-major change: every implementer adopts in the same wave (no compatibility
machinery). Gated by Phase 4 verdicts.
Work items:
Grep/Globfor every consumer parsing theconvention surface —
.claude/topic-docs.yamlkeys, slug spec, tier paths, runtime guards, thescripts/check-cross-plugin-source-drift.shregistry, hooks readingdocs/topics/or.work/.Document parse paths in the memory slice before editing anything.
docs/conventions/topic-docs/README.md: worktree-visibility rationale, context ×tier visibility matrix, native mechanisms named (
worktree.baseRef,.worktreeinclude, by-valuereturns, tracker index); CHANGELOG entry
2.0.0; schema untouched unless a key changes (KEEPexpected). Reconcile the Implementers table with reality:
toolchainandverificationcarry
reference/topic-docs.mdbut are absent from the table;knowledge,claude-ops,docs-hygieneare listed without delta docs — the 2.0.0 table must match the actual fleet(add/annotate rows or document why a row is delta-doc-free). The CHANGELOG 2.0.0 entry states
the mixed-fleet window and why it is safe (no tier/key/slug-spec change — installed cache
copies and in-flight branches keep 1.x text until they update; divergence is doctrinal, not
layout-corrupting), and notes a post-PR-B stale-text sweep obligation for in-flight branches at
their merge time.
.claude/settings.jsonwithworktree.baseRef: "head"(shape per Phase 4 smoketest A verdict; if NOT-HONORED at project scope, execute the tagged fallback below). Rollout
note in the PR B description + convention doc: a clone with an existing untracked
.claude/settings.jsonhits "untracked working tree file would be overwritten" on pull —document the remedy; state the repo-wide worktree-spawn behavior change; gitignore
.claude/worktrees/in the same change (mandatory — the runtime.git/info/excludeentry ismachine-local; CI checkouts and fresh clones lack it, and partial tracking of
.claude/otherwise turns nested worktrees into
git add -Ahazards); run the hygiene CI lanes(machine-specific-paths, gitleaks, editorconfig) locally on the new tracked file. Document the
escape hatch: a personal
.claude/settings.local.json(main-checkout-resolved, covers everyworktree) silently overrides R1 machine-wide — the convention doc states this; no audit
dimension may assume R1 is universally in force.
Consumer-adoption path (mandatory): repo settings never travel with marketplace-installed
plugins (isolated cache) — R1/R2 as files fix only this repo. The 2.0.0 doc ships a
consumer-adoption section: the settings snippet + a
.worktreeincludetemplate, scoped as"authoring-repo materialization; consumer repos self-apply" (routing it through a D9 setup-skill
applyaction is recorded as a follow-on trigger, not built now). The visibility matrix gains acaveat row: a
WorktreeCreatehook makes.worktreeincludeinert (documented) — hook scriptowns the copy.
.worktreeincludewith targeted memory-tier patterns (stage ledgers, EXPLORE/RESEARCH; notbaselines/raw scratch); one-way creation-time copy documented in the convention doc.
plugins/work-items/skills/decomposecites the PR (not contractpaths) in ticket provenance;
plugins/planning/skills/architectrecords distilled baselinevalues in PLAN (raw captures stay memory-tier). Sweep both skill bodies for prunable-path
citations.
writing both tiers in the parent checkout (R4); the work-item tracker named as the cross-lane
awareness/index layer, markdown-in-tickets rejected with rationale (R5).
plugins/*/reference/topic-docs.mddelta docs against the 2.0.0owner doc; bump each touched plugin's
plugin.jsonsemver + CHANGELOG; docs-hygiene declutterdetector references checked (reader row).
File inventory (checkbox discipline — tick as processed):
docs/conventions/topic-docs/README.mddocs/conventions/topic-docs/CHANGELOG.mddocs/conventions/topic-docs/topic-docs.schema.jsondocs/conventions/topic-docs/examples/*.claude/settings.jsonworktree.baseRef.worktreeinclude.claude/worktrees/gitignored)plugins/discovery/reference/topic-docs.mdplugins/implementation/reference/topic-docs.mdplugins/planning/reference/topic-docs.mdplugins/review/reference/topic-docs.mdplugins/session-flow/reference/topic-docs.mdplugins/toolchain/reference/topic-docs.mdplugins/verification/reference/topic-docs.mdplugins/work-items/reference/topic-docs.mdplugins/work-items/skills/decompose/SKILL.mdplugins/planning/skills/architect/SKILL.mdplugins/*/plugin.json+CHANGELOG.mdplugins/knowledge/…,plugins/claude-ops/…,plugins/docs-hygiene/…Sanity Check:
bash scripts/check-cross-plugin-source-drift.sh --checkexit 0 (the flag CI runs; flagless modeis informational only).
grep -n "2.0.0" docs/conventions/topic-docs/CHANGELOG.mdhits;grep -rn "visibility matrix" -i docs/conventions/topic-docs/README.mdhits.plugins/*/reference/topic-docs.mdpath has a matching tablerow and vice versa (Read assertion against the glob result).
.work/plugin-philosophy/consumers-topic-docs.mdnon-empty.plugin.jsonversion bump:git diff origin/main...HEAD --name-only | grep '^plugins/' | cut -d/ -f2 | sort -ueach has amatching
plugins/<name>/plugin.jsonin the diff.bash scripts/validate-plugins.shexit 0 (includesgenerate-catalog.mjs --check— regeneratethe catalog if any plugin.json description changed).
npx markdownlint-cli2 --config .markdownlint-cli2.jsoncon touched .md files exit 0.Phase 6: Marketplace metadata wave [DONE]
Covers D15 + per-plugin
relevancequality verification (deferred question c).Work items:
plugin-marketplaces+discover-plugins+plugins-reference(default-enablement section) + the dedicated
plugin-relevancepage; re-verify entry schema(
relevance,defaultEnabled,displayName, description precedence,versionsilent-precedence trap).
defaultEnabledflip semantics for already-installed consumers areundocumented — if the fetched pages stay silent, run a 2-minute empirical flip on one plugin
before the wave (does a marketplace refresh disable an existing install?). Never touch a
plugin's
name(breaks existing installs without arenamesmap);displayNameis safe.relevanceonly where the signal is genuinely helpful(judged per-plugin — noise rejected),
defaultEnabled: falsefor personal/niche categories,displayNamewhere it clarifies, complete descriptions; assert noversionfield in anyentry.
pluginSuggestionMarketplaces+managed-settings source declaration) — lands in the discover/consumer section of README or
OFFICIAL-DOCS per where consumer docs live (decided at execution against the fetched page).
.work/plugin-philosophy/relevance-decisions.md.node scripts/generate-catalog.mjs(CI runs--check; metadataedits drift the generated block otherwise).
Sanity Check:
claude plugin validate .exit 0.node scripts/generate-catalog.mjs --checkexit 0.node -eassertion: 47 entries; every entry resolves a description (entry or plugin.json);versionabsent from all entries — exit 0..work/plugin-philosophy/relevance-decisions.mdhas 47 rows.Phase 7: Fleet conformance audit fanout + tracker graduation [DONE]
Covers D16. Runs against merged doctrine (Phases 1–6 landed).
Work items:
gh issue list --searchfor an existingplugin-conformance epic / wave issues. Match found → pivot to updating the existing items
(record the match + pivot in the memory slice); no match → proceed to create. Verify required
labels exist (
gh label list) and create missing ones before anygh issue create --labelcall (missing labels fail the create).
userConfig migration (D8), exec-form hooks, metadata completeness (D15), component stances (D6),
registry conformance (D11), prereq degradation (D10), pointer discipline (R3), freshness riders
(D7), plus dimensions the doctrine text yields. Freeze a rubric file with per-dimension
anchored PASS/FAIL criteria + one worked example, injected verbatim into every worker prompt
(uncalibrated independent scoring across batches encodes rubric drift, not conformance).
Authority rule: plugins are scored against landed doctrine only; where a fresh-fetched
doc disagrees with doctrine, that is a doctrine-update finding (its own wave), never plugin
nonconformance. Dimensions may not assume R1 is universally in force (local-settings override
exists). Checklist + rubric → memory slice.
per the authority rule above).
sensitiveuserConfig empirical verification (deferred question a): configure athrowaway
sensitiveuserConfig value on this Windows machine; locate where it persists(Credential Manager vs plaintext file); VERDICT recorded before any userConfig wave issue
involving secrets is filed. Secrets excluded from that wave if storage is plaintext (tagged
fallback below).
before full fanout; then per-plugin subagents score the remainder in batches of 8–10; each
worker writes its own raw report to
.work/plugin-philosophy/audit/<plugin>.md(memory-tierraw output is carved out of R4 — R4's orchestrator-writes rule governs contract/durable tiers)
and returns only its scored dimension row by value; the orchestrator (main session) appends
matrix rows incrementally per batch, so a compaction mid-run loses nothing. Double-score a
random 3-plugin sample with independent workers and reconcile disagreements before graduating
the matrix.
prose lives in per-wave issues; GitHub bodies cap near 64 KB) + per-wave issues (setup,
userConfig, metadata, hooks, convention-seam) via the work-items seam; issues cite the epic + PR
permalinks, never contract/memory paths (R3). Automatable checks list → epic section = deferred
CI gate backlog (D1 trigger).
Sanity Check:
.work/plugin-philosophy/audit/tracker-search.mdstates the query + hitcount + create-vs-update decision.
ls .work/plugin-philosophy/audit/*.md | wc -l≥ 47 (one report per plugin) + matrix file with47 scored rows.
gh issue list --label epic --search "plugin conformance"(or equivalent) returns the epic;epic body contains the matrix; ≥ 5 wave issues reference the epic.
grep -c "docs/topics/\|\.work/" <epic and wave issue bodies>= 0 (pointer discipline).sensitiveVERDICT file exists in.work/plugin-philosophy/verifications/.Empirical verification results
worktree.baseRefat project scope; sweep of ignored files;--bgbase.claude/settings.jsonworktree.baseRef: "head"honored, incl. from linked worktrees (A2: resolves to the worktree's own HEAD; A3: a linked-worktree session reads its OWN checkout's settings.json)..worktreeinclude: nested-gitignored files qualify, copy is one-way creation-time. Sweep:--worktreeworktrees never auto-swept (empirical); subagent/bg sweep would remove ignored-only worktrees (INFERRED — ignored ≠ untracked).--bgbase = origin/HEAD by default, so R1 moves it to local HEAD. Windows caveat: deep worktree base paths can trip git PATH_MAX ('$GIT_DIR' too big); this repo's base (~95 chars) is safe.relevancesignal quality**/*.mdandCLAUDE.mdpatterns are noise by construction — auto-loaded memory counts as filesRead). Also:defaultEnabled: falseon 5 (firecrawl, songwriting, kindle-dedrm, ai-briefing, miro),displayNameon 5 acronym names. Flip semantics documented (existing installs never flipped) — empirical check waived. Full ledger: memory slice.sensitiveuserConfig storagesensitive: truevalue persists as plaintext JSON in~/.claude/.credentials.jsonunderpluginSecrets; NO Credential Manager entry (cmdkey /listempty of claude); removed cleanly on uninstall. Documented no-keychain fallback confirmed observed. Tagged fallback APPLIED: secrets excluded from the userConfig wave issue (#315), blocked-upstream recorded in epic #313.Blast radius
HIGH. Matches stress-test triggers: new conventions constraining all future work (doctrine +
contract-major), architecture decisions across 47 plugins + 8 implementer materializations, shared
committed settings (
.claude/settings.json) affecting every session, and undocumented behavior(worktree semantics, Windows sensitive storage — mitigated by the empirical phases). Reversible via
git revert (docs/metadata only, no runtime code), and existing CI (contract tests, markdownlint,
drift check) gates every PR — hence HIGH, not CRITICAL.
Stress-test summary
Two fresh-context adversarial passes ran; all findings verified against the repo before adoption.
Plan-reviewer (Step 3): 9 IMPORTANT + 5 SUGGESTION, 0 CRITICAL — all applied: implementer-roster
reconciliation + parity check (Phase 5), CI-parity sanity commands (drift
--check, catalog--check, markdownlint config,node -eover Python), pointer-vs-restate check made structural(Phase 2), Phase 4 by-value/fence contradiction resolved, component-count made variable with a
Wave A join step, PR-chain PLAN lifecycle defined, Phase 7 batching + label verify-or-create,
worktree-variant smoke tests, R1 rollout notes.
Devils-advocate (Step 4): 16 assumptions attacked; 4 mandatory changes, all applied:
(1) Phase 4 redesigned — isolated scratch repo with synthetic origin, control+treatment arms
(defeats the documented origin/HEAD-fallback false positive), settings-scope variant A3,
CC-version-stamped verdicts with re-run at the Phase 5 gate; (2) PLAN lifecycle switched to
branch-local prune-per-PR (the program must not self-violate the contract it ships); (3) 2.0.0 doc
gains a consumer-adoption path — repo settings provably never reach marketplace-installed
consumers; (4) Phase 7 calibration — frozen anchored rubric, pilot batch, double-scored sample.
Also adopted: mandatory
.claude/worktrees/gitignore in PR B,WorktreeCreate-hook caveat for.worktreeinclude, mixed-fleet window statement in the CHANGELOG, doctrine-wins authority rule foraudit scoring,
defaultEnabled-flip empirical check, matrix cell budget (64 KB body cap),nameimmutability during the metadata wave. One finding escalated to a user gate: R6 major-vs-minor
contradiction with the contract's own versioning rule (see User-approval gates).
Execution shape
Two parallel-safe waves inside an otherwise sequential PR chain; fanout inside Phase 7.
OFFICIAL-DOCS.md, one CLAUDE.md row)Wave A (parallel): Phase 1 (main) ∥ Phase 3 (sub-agent) ∥ Phase 4 (sub-agent). Zero file overlap:
P1 =
docs/PLUGIN-PHILOSOPHY.md; P3 =docs/OFFICIAL-DOCS.md+ CLAUDE.md; P4 =.work/+ scratch.Wave B (sequential): Phase 2 → Phase 5 → Phase 6 → Phase 7.
Scope fences (Wave A): P3 agent ALLOWED
docs/OFFICIAL-DOCS.md,CLAUDE.md(one row);FORBIDDEN everything else incl. PLAN.md. P4 agent ALLOWED
.work/plugin-philosophy/verifications/and throwaway
git initrepos under the scratchpad (its own branches/worktrees live there);FORBIDDEN every file and branch of THIS repo (note:
claude -p --worktree <name>creates branchesnamed
worktree-<name>— another reason the spike never runs in this repo).Sequential fallback: any fence violation or agent failure → that phase re-runs inline main-session
in Wave B order. PLAN.md edits are main-session-only.
Cost note: Wave A = 2 extra agents vs sequential (~saves one serial doc-build + smoke-test round);
Phase 7 = ~47 scoring agents (D16-locked, run regardless of shape).
Open questions
None blocking — the three empirical questions are scheduled inside phases with tagged fallbacks.
Handoff to implementation
User-approval gates
("2.0.0, one wave"), but the contract's own Versioning rule says major = "moves a tier, renames a
key, or alters the slug spec" — R6 does none (schema KEEP; the change is visibility semantics +
doctrine text). Options: (a) keep 2.0.0 and amend the Versioning rule so visibility-semantics
guarantees also count as major (the doctrine repo then applies its own rule consistently);
(b) downgrade to a 1.x minor, dissolving the one-wave coordination burden and most of Phase 5's
mixed-fleet risk. RECOMMENDED: (a) — the Brief locked the one-wave clean break deliberately, and
a visibility-guarantee change does alter what implementers may rely on; the rule amendment makes
the label honest. The plan as written assumes (a).
worktree.baseRefnothonored): R1 degrades to documenting the limitation + the strongest honored scope in the
convention doc, and an upstream issue is filed; R2/R6 proceed unchanged.
sensitivestorage is plaintext: secret-bearinguserConfig migrations are excluded from the userConfig wave issue and recorded as blocked-upstream
in the epic; non-secret migrations proceed.
Execution shape ([EXEC-SHAPE] tagged)
docs/plugin-philosophy); PR B = Phases 4–5 (contract 2.0.0 wave; Phase 4 evidence rides thememory tier, distilled results in PLAN); PR C = Phase 6 (metadata); PR D = close-out (Phase 7's
PLAN/verdict updates + prune-with-pointer). Rationale: reviewability + distinct concerns
(doctrine vs contract-major vs metadata); each PR independently green on existing CI.
topic-docs contract says contract slices are pruned before merge, and this program (which ships
that very contract's 2.0.0) must not self-violate by parking a slice on
mainfor weeks. Each PRbranch commits the current PLAN, pastes it into its PR description, and prunes the slice in a
final commit before merge; the next PR branch (cut from post-squash
main) re-commits theupdated PLAN from the local working tree. Cross-PR continuity = the PR-description pastes + (from
Phase 7) the epic. Close-out at PR D: Phase 7's verdict rows and final status tags commit there,
durable outcomes graduate, final prune-with-pointer. The Windows
sensitiveVERDICT is recordeddurably (PLAN verdict table → PR D description + epic), not only in gitignored
.work/.(Alternative rejected: adding a multi-PR-program exception clause to the 2.0.0 lifecycle text —
viable, but it lands only in PR B while PR A would already need it; override at approval if the
exception clause is preferred.)
sub-agent fanout otherwise) — D16 locks the fanout itself.
rather than a standalone verification phase.
Mechanical work
implementer adoption (clean break lands atomically); PLAN.md status-tag updates ride each phase's
commit. Each PR branch is cut from post-squash
main, never from the previous PR branch(stacking would replay the prior PR's squashed commits in the diff).
(contract tests, markdownlint, drift check) green before each PR merge.
all fanout output.
/architect close-outat PR time — PLAN.md into PR description<details>, durableoutcomes graduate (vault_backend
docs), contract slice pruned with pointer.🤖 Generated with Claude Code
https://claude.ai/code/session_01M1owJj9ZzkV36V3C1CyX4a