Functional core, imperative shell: encode as essential principle

[andrewemark]

Motivation

The plugin's curated test suites still felt low-value and mock-heavy even after /drvr:assess. We traced it to a structural cause in the planning skill:

• Test strategy was designed independently of architecture (test pyramid ratios, coverage quotas, "mock at unit boundaries").
• Under that framing, mock-heavy unit tests are structurally inevitable — the planner has nowhere to put logic except inside classes whose collaborators then get mocked.
• The "scaffolding vs durable" framing leaned on assessment to clean up later, but the KEEP criterion ("asserts observable behavior") was a weaker bar than what we actually want: a test a reader can use to understand the code.

The fix flips the dependency: architecture determines test shape, not the other way around.

What this PR does

Encodes functional core, imperative shell (Bernhardt; also Hexagonal / Ports-and-Adapters) as a load-bearing architectural commitment across every phase of the SDLC. Under this commitment:

• Pure-core code takes values in, returns values out — no I/O, no time, no randomness, no mutable shared state. Unit-tested with values in / values out and no mocks.
• Imperative shell performs I/O and calls into the core. Integration-tested against real I/O.
• A ""unit test"" that needs a mock for an internal module is a signal the boundary is broken — fix the architecture, not the test.
• Mocks are permitted only at hard external boundaries (third-party APIs without sandboxes, cost-bearing services, hardware absent in test).

When the surrounding code isn't already in core/shell shape, the plugin steers each new feature toward extraction anyway — local mess from a clean extraction is preferred to a clean fit with an entangled neighbor. We're fighting architectural entropy actively.

Where it lands, by phase

Phase	File	Change
Constitution	CLAUDE.md + templates/CLAUDE.md.template	Principle as first Key Principle. Expanded in Engineering Practices. New kind task frontmatter field (core/shell/both). Plan schema requires a ### Core/Shell Decomposition subsection under ## Architecture Fit.
Research	skills/research-guidance/SKILL.md	Surfaces the natural decomposition during ""How"" research. Required section in overview.
Planning	skills/planning-guidance/SKILL.md (heaviest edit)	Test Strategy is now derived from a required Core/Shell Decomposition subsection. Test pyramid + coverage quotas + ""mock at unit boundaries"" replaced with: pure-core unit tests (values in / values out, no mocks) and shell integration tests (real I/O). ""Scaffolding test"" category removed — every test is now durable by construction. Added boundary self-review.
Validation	commands/dry-run-plan.md	New gap checks (mostly HIGH severity): missing decomposition, pure-core items that aren't pure, internal-module mocks in proposed tests, test/item classification mismatches.
Materialization	skills/materialize-tasks/SKILL.md	Reads the plan's decomposition, propagates per-task classification into task doc frontmatter (kind) and a ## Core/Shell section. BLOCKs if plan lacks the decomposition.
Implementation	skills/implementation-guidance/SKILL.md	Sub-agent prompts now carry the core/shell rules + per-task classification. New ""core/shell boundary"" deviation category — needing a mock for an internal module is a stop-and-surface signal.
Assessment	commands/assess.md	PRUNE/KEEP/PROMOTE keyed on mock presence and core/shell membership. ""When uncertain, KEEP"" reversed for mock-heavy tests (PROMOTE instead so the architecture failure surfaces). New §FCIS boundary check in Step 4a — runs regardless of whether codebase has its own standards artifact.
Standards review	agents/standards-review.md	§FCIS check runs unconditionally (Step 2a). Codebase-specific standards layer on top (Step 2b, conditional).
Handoff	commands/docs-artifacts.md	New Functional Core, Imperative Shell section in architecture.md handoff template so reviewers can verify the boundary in the diff.
Pass-through	commands/review.md, commands/setup.md	Updated descriptions to reflect the new commitment.

What's deliberately NOT in this PR

• Validation tests for the new contract. The existing test_plan_doc_sections probably doesn't know about the required ### Core/Shell Decomposition subsection. Worth adding as a follow-up.
• CHANGELOG entry. Template version bumped to 1.1.0, but no CHANGELOG entry written.
• README mention. README doesn't currently surface the commitment; worth adding for plugin users browsing the repo.
• skills/intent-guidance, skills/sdlc-orchestration. Neither phase materially shapes architecture, so left untouched.

Backward compatibility

This is a real philosophical shift. Plans written before this change won't have a Core/Shell Decomposition subsection — materialize-tasks will BLOCK on them and route back to planning. That's intentional: we don't want pre-existing plans silently treated as conforming.

Test plan

• Open a new feature with /drvr:feature, run through Research → Planning → see the Core/Shell Decomposition prompts land in the expected places
• Try to materialize a plan missing the decomposition; confirm it BLOCKs
• Run /drvr:assess on a test suite known to contain mock-heavy tests; confirm they surface as PRUNE/PROMOTE rather than KEEP
• Run /drvr:review on a codebase without its own CLAUDE.md; confirm §FCIS check still runs

🤖 Generated with Claude Code