feat(tracker): selection-scoped install bundle + tracker gap closure

.devflow/features/compliance-feature/KNOWLEDGE.md

@@ -391,7 +391,7 @@ Step 1b reads the `## Version Names` and `## Version PR Titles` sections from `.
 - **PF-027** — Containment controls must never become loadable/optional: why `## Comment-sink scrub (D11)` never moved out of `git.md`.
 - **PF-058** — Containment is four separate obligations (every producer, every repetition, every escape, and the untrusted-vs-local boundary): the Principle 8 marker-neutralisation rule and the per-issue (never per-list) wrapping discipline documented above under Anti-Patterns/Constraints are this pitfall's direct fix.
 - **PF-063** — Byte-identical relocation is not semantics-preserving across a grammar boundary: the direct cause of the `###`-heading-depth rule applied to the moved D3 template.
-- Feature knowledge: **tracker-references** — owns the split mechanics in full detail: MDS build machinery (`VARIANT_MODULES`, `expandVariants`, `splitVariantSections`), the byte budget (`BUDGET_GIT_MD`, `BUDGET_SKILL_MD`, `BUDGET_LOADED_SET`, `PREAMBLE_MAX_LINES`), the containment oracle (`CONTAINMENT_EXEMPTIONS`, baselines from commit `101bda7`), and the installer overlay (`overlayGeneratedReferences`, converge-not-merge, prune). Read it before touching build-side plumbing; read this KB for what the contract means at runtime.
+- Feature knowledge: **tracker-references** — owns the split mechanics in full detail: MDS build machinery (`VARIANT_MODULES`, `expandVariants`, `splitVariantSections`), the byte budget (`BUDGET_GIT_MD`, `BUDGET_SKILL_MD`, `BUDGET_LOADED_SET`, `PREAMBLE_MAX_LINES`), the single-authority and reachability guards (`SHARED_LITERAL_REGISTRY`, `MCP_SHARED_LITERAL_REGISTRY`, `MIN_RATIONALE_CHARS`), and the installer overlay (`overlayGeneratedReferences`, converge-not-merge, prune). Read it before touching build-side plumbing; read this KB for what the contract means at runtime.
 - Feature knowledge: **installer-shadowing** — shadow resolution for SKILL.md and rule file follows `validateSkillShadow` / `validateRuleShadow` from the installer; `seedRuleShadow` tier logic lives in `rules.ts`.
 - Feature knowledge: **resolve-pipeline** — `/resolve` depends on `COMPLIANCE_SKILL_INSTALLED` for Phase 1b/9b/9c; resolution-summary.md format includes `## Third-Party Threads` section gated by this flag.
 </content>

.devflow/features/feature-knowledge-system/KNOWLEDGE.md

@@ -284,8 +284,9 @@ FENCED `## ` — inside a heredoc or a template fence a provider module ships on
 e.g. `manage-debt.md`'s `## Items` or `ensure-traceable-issue.md`'s D3 template — is
 exempt, via the fence-aware `collectUnfencedH2` helper in `tests/helpers.ts`, because
 demoting THOSE headings would change what the tracker renders). Every emitted file also
-clears a content floor (`MIN_REFERENCE_CHARS = 80`, asserted in `tests/tracker/
-containment.test.ts` / `linear-module.test.ts` — a thinness guard owned by the
+clears a content floor (`MIN_REFERENCE_CHARS = 80`, owned by `tests/tracker/
+reference-floor.ts` and imported by `reference-reachability.test.ts` / `linear-module.test.ts` /
+`jira-module.test.ts` — a thinness guard owned by the
 `tracker-references`/`tracker-feature` test suite, not by the build itself; the build's own
 emptiness check, `empty-section`, only refuses a fully blank section, not a merely thin one).
 

README.md

@@ -65,13 +65,13 @@ This is the **orchestrated flow** — you stay in the loop between every step. W
 
 **Always-on rules.** 13 ultra-condensed engineering principles (~10 lines each) load on every prompt — security, quality, and language-specific guidance (TypeScript, React, Go, Python, Java, Rust), plus a compliance rule when compliance is enabled. Rules install from your selected plugins only, so a Go project won't get React rules. Override any rule via `~/.devflow/rules/{name}.md` or `devflow rules shadow <name>`.
 
-**41 skills** (40 universal + 1 feature-owned compliance skill, installed when compliance is enabled). Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.
+**41 skills** (40 plugin-owned + 1 feature-owned compliance skill, installed when compliance is enabled). Skills install for the plugins you selected plus whatever those plugins declare they use, so the default plugin set installs 32 of the 40 and a Go project never gets the React skill. Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.
 
-**Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules.
+**Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules. A shadow for a skill outside your plugin selection stays where it is: not installed, never deleted, and live again the moment you select that plugin.
 
 **Compliance built in.** Six regulatory frameworks — GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX — composed into a review skill and an always-on rule for exactly the frameworks you select. Compliance reviews activate automatically when a diff touches regulated surface. `devflow compliance --enable`.
 
-**Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`. On a non-GitHub tracker a background agent learns your conventions once (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. That file is yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if it no longer matches your selected provider. **GitHub is the default and GitHub users see no change** — no prompt, no new file, no altered byte.
+**Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`. Only the tracker you picked is installed: GitHub gets 13 generated reference files and nothing else, Jira and Linear get 24 plus the tool-call contract and the background agent that reads it. On a non-GitHub tracker that agent learns your conventions once (project key, issue types, required fields, workflow transitions, how a reference renders) and writes them to `~/.devflow/tracker.md`, so traceability speaks your tracker's vocabulary instead of assuming `#123`. That file is yours: hand-editable, kept across an uninstall, and refused rather than silently trusted if it no longer matches your selected provider. **GitHub is the default and GitHub users see no change** — no prompt, no new file, no altered byte.
 
 **Full lifecycle.** Beyond the core flow: `/explore` maps a codebase into knowledge bases, `/research` runs multi-type research with trust-aware synthesis, `/debug` investigates with competing hypotheses in parallel, `/bug-analysis` hunts bugs before review, `/self-review` runs Simplify + Scrutinize quality passes, and `/release` ships with learned configuration.
 
@@ -191,6 +191,8 @@ npx devflow-kit init --plugin=implement # Install specific plugin
 npx devflow-kit ambient --enable        # Toggle ambient mode (orchestrator)
 npx devflow-kit learning --enable       # Toggle decision/pitfall tracking
 npx devflow-kit compliance --enable     # Enable compliance reviews (pick frameworks)
+npx devflow-kit tracker --set jira       # Pick the issue tracker (github | jira | linear)
+npx devflow-kit tracker --status         # Show provider, learned conventions, installed mechanics
 npx devflow-kit rules --status          # Show installed rules
 npx devflow-kit security --status       # Show / manage the security deny list
 npx devflow-kit safe-delete --enable    # Install rm -> trash safe-delete

docs/cli-reference.md

@@ -132,6 +132,12 @@ Valid provider IDs: `github`, `jira`, `linear`. The ID is matched **exactly** 
 
 The selection is stored in `~/.devflow/manifest.json` under `features.tracker.provider` and is **machine-wide**, not per-project. A malformed value in that file is self-healed to `github` silently on read.
 
+The selection also decides what gets installed. `github` installs 13 generated reference files under the `devflow:git` skill; `jira` and `linear` install 24, plus the tool-call contract `references/tracker/_mcp.md` and the Tracker agent that reads it. `devflow tracker --set <id>` converges all of that in a fixed order — references, stale-conventions rename, manifest, Tracker agent file, attempt counter, presence sentinel — and it converges **both ways**, so `--set github` removes what `jira` or `linear` installed.
+
+Two branches exit 1 and change nothing you can see: `devflow:git` is not installed (there is nowhere for the mechanics to land — run `devflow init --tracker <id>` instead), or the reference overlay failed. In both the manifest, the sentinel and the conventions file are left exactly as they were, so the previous provider stays whole. The overlay is atomic per unit, so a failure reports the units that failed rather than claiming nothing moved at all.
+
+`devflow tracker --status` prints the provider, where the selection came from, whether `~/.devflow/tracker.md` has been learned yet, and a `Mechanics:` line — `installed (N file(s))`, `MISSING — run devflow init`, or `unreadable (<errno>)`. The three are different facts with different remedies: nothing installed is fixed by an install, a permissions problem is not.
+
 ### When the wizard asks
 
 `devflow init` asks for a provider only when the question can be answered interactively:
@@ -219,7 +225,7 @@ Override any Devflow skill with your own version. Shadowed skills survive `devfl
 ```bash
 npx devflow-kit skills shadow software-design    # Create override (copies current as reference)
 vim ~/.devflow/skills/software-design/SKILL.md   # Edit your override
-npx devflow-kit skills list                      # List all skills with shadow state
+npx devflow-kit skills list                      # List all skills: shadow state and which plugin provides each
 npx devflow-kit skills unshadow software-design  # Remove override
 ```
 
@@ -360,7 +366,7 @@ npx devflow-kit uninstall
 | Option | Description |
 |--------|-------------|
 | `--scope <user\|local>` | Uninstall scope (default: auto-detect all installed scopes) |
-| `--plugin <names>` | Selective uninstall by plugin name |
+| `--plugin <names>` | Selective uninstall by plugin name. Assets are retained on behalf of the plugins the **manifest** records as installed — not the whole registry — so removing a plugin removes exactly its own skills, agents and rules and keeps only what a plugin you actually installed still needs |
 | `--keep-docs` | Preserve `.devflow/docs/` directory |
 | `--dry-run` | Show what would be removed |
 | `--verbose` | Show detailed output |

docs/reference/file-organization.md

@@ -102,14 +102,14 @@ devflow/
 │   ├── helpers.ts                    # Shared helpers: resolveAgentSource, resolveAllAgents, extractOpSectionFromCorpus, gitAgentSinkCorpus, walkFiles, loadGolden, extractStatusLines, parseFences, isAgentBlock, requireDistFile/requireDistFiles
 │   ├── seams/                        # Command→agent input contract
 │   ├── goldens/                      # Byte-equality against tests/fixtures/golden/
-│   ├── guards/                       # Named-collector guards with known-bad probes: literal-agent-paths, retired-wording, numeric-floor-manifest, agent-source-resolver, agent-source-precedence, dist-agents, extended-references, capability-hoist, heredoc-quoting, fence-grammar, provider-scope, guard-census
-│   ├── tracker/                      # Tracker contract/mechanics split — containment oracle, byte budget
+│   ├── docs/                         # Docs guards — the CLAUDE.md Tracker block cap and the selection-scoped naming
+│   ├── guards/                       # Named-collector guards with known-bad probes: literal-agent-paths, retired-wording, numeric-floor-manifest, agent-source-resolver, agent-source-precedence, dist-agents, extended-references, capability-hoist, heredoc-quoting, fence-grammar, provider-scope, requires-closure
+│   ├── tracker/                      # Tracker contract/mechanics split — byte budget, schema scope, hostile values, single-authority registries, reference reachability
 │   ├── dynamic/                      # Two-sided writer↔reader grammar seams
 │   ├── installer/                    # Generated-reference overlay (converge-not-merge, atomic per-unit swap)
 │   ├── integration/                  # Real claude / tarball installs
 │   └── fixtures/
 │       ├── golden/                   # git-agent.md (regenerated in fixture-only commits); github-status-lines.txt (frozen)
-│       ├── tracker/baseline/         # Byte copies of the pre-split tree — never regenerated
 │       └── numeric-floors.json       # Hand-registered ratchet manifest — floors raise, never lower; ceilings lower, never raise
 ├── docs/
 │   └── reference/                    # Extracted reference docs
@@ -126,19 +126,20 @@ Plugins are entries in `DEVFLOW_PLUGINS` in `src/core/plugins.ts` — no per-plu
   commands: ['/implement'],
   agents: ['git', 'code', 'simplify', 'scrutinize', 'evaluate', 'test', 'validate', 'knowledge'],
   skills: ['patterns', 'qa', 'quality-gates', 'worktree-support', 'feature-knowledge', 'apply-feature-knowledge'],
+  requires: ['git', 'testing', 'test-driven-development', 'software-design', /* … */],
   rules: [],
 }
 ```
 
-The `commands` array lists slash-command names (e.g., `'/implement'`). The installer maps each command name to a compiled `.md` file in `dist/commands/` and copies it to `~/.claude/commands/devflow/`. Skills and rules are copied directly from `src/assets/` with no build step. Agents are mixed: a hand-authored `src/assets/agents/{name}.md` is copied directly, while an `.mds` generator host is installed from the `dist/agents/{name}.md` it compiles to.
+The `commands` array lists slash-command names (e.g., `'/implement'`). The installer maps each command name to a compiled `.md` file in `dist/commands/` and copies it to `~/.claude/commands/devflow/`. Skills and rules are copied directly from `src/assets/` with no build step. `skills` are the skills a plugin OWNS and `requires` the ones it uses without owning; the install set is the closure of both over the selected plugins, and a bidirectional guard holds `requires` against what the plugin's commands, agents and skill bodies actually name. Agents are mixed: a hand-authored `src/assets/agents/{name}.md` is copied directly, while an `.mds` generator host is installed from the `dist/agents/{name}.md` it compiles to.
 
 ## Installation Paths
 
 | Asset | Path | Notes |
 |-------|------|-------|
 | Commands | `~/.claude/commands/devflow/` | Namespaced; installed from `dist/commands/*.md` |
 | Agents | `~/.claude/agents/devflow/` | Namespaced; resolved most-preferred-first over `dist/agents/` then `src/assets/agents/`, first hit wins |
-| Skills | `~/.claude/skills/devflow:*/` | Namespaced (`devflow:` prefix); installed from `src/assets/skills/` |
+| Skills | `~/.claude/skills/devflow:*/` | Namespaced (`devflow:` prefix); installed from `src/assets/skills/`, scoped to the selected plugins and their declared `requires:` |
 | Rules | `~/.claude/rules/devflow/` | Flat `.md`; installed from `src/assets/rules/` (plugin-scoped) |
 | Scripts | `~/.devflow/scripts/` | Helper scripts |
 | Hooks | `~/.devflow/scripts/hooks/` | Installed from `src/assets/scripts/hooks/`; Working Memory hooks |