Skip to content

Epic: Harness Layer Separation — virtual layers via manifest metadata (v3.0.0) #190

@cheddarfox

Description

Epic: Harness Layer Separation (v3.0.0)\n\nDeferred from: SAW-1 (Fork-Friendly Harness Update Mechanism)\nBlocked by: v2.10.0 multi-domain sync must be stable and validated\n\n### Description\n\nImplement Proposal C from GH#28: split the harness into composable layers (core methodology / project config / documentation) using manifest metadata — NOT filesystem restructuring. This preserves Claude Code's path auto-discovery while enabling per-layer sync strategies.\n\n### Rationale\n\nPhysical restructuring would break all existing forks. Virtual layers via manifest layer_overrides and sync.layer_strategy provide the same benefits without breaking changes. Deferred to v3.0.0 after manifest system is proven.\n\n### Implementation Notes (from v2.10.0 session)\n\nFoundation now exists: v2.10.0 shipped the multi-domain sync engine with schema v1.1. The sync_scope, root-relative paths, manifest-authoritative model, and domain loop architecture are all in place. Layer separation would extend this by:\n\n1. Layer definitions in manifest — schema v2.0 adds layers section mapping files to layers (core/config/docs)\n2. Per-layer sync strategysync.layer_strategy allowing different conflict_strategy per layer (e.g., upstream-wins for core, local-wins for config)\n3. Layer-aware diffdo_diff() groups output by layer, not just by domain\n4. Layer-conditional substitutions — some layers may skip substitution (docs layer keeps placeholders for template users)\n\n### What v2.10.0 already provides that this builds on\n- Multi-domain sync loop (iterate per domain)\n- v1.0/v1.1 manifest version branching (ready for v2.0)\n- Root-relative path model (layer paths would also be root-relative)\n- Manifest-authoritative model (layers would be manifest-declared)\n- Protected/replaced/renames work across domains (would work across layers)\n\n### Open questions for decomposition\n- Should layers be orthogonal to domains (a layer spans multiple domains) or nested (each domain has layers)?\n- How does layer separation interact with sync_scope? Are layers a refinement within a domain or a cross-cutting concern?\n- Should manifest init auto-detect layers from file patterns, or is layer assignment always manual?\n- What's the migration path from v1.1 manifests (no layers) to v2.0 (with layers)?\n\n### Deferred release domains\nv2.10.0 explicitly deferred docs/, scripts/, patterns_library/ from sync_scope. These are the natural candidates for a "docs" or "release" layer in v3.0.0. Layer separation could gate these behind a separate sync strategy (e.g., opt-in, manual review only).\n\n### Estimated scope\nNot yet decomposed. Likely 5-8 stories, ~20-30 points. Requires SA design review before decomposition."

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions