Spec: Finder Provider Projection and Intent Control

[!WARNING] This is the historical control-envelope specification. Its staged Grilling, fixed working-set cardinality, optional Linear profile, and Technical Finder requirements are superseded by Finder Intake and Requirements Boundary. Do not use this file or its adjacent plan as current implementation authority.

Context

Finder and write-backlog currently preserve semantic workflow rules, provider adapter rules, and conversational corrections as separate prose authorities. An agent can therefore follow one authority faithfully while acting on a stale stage, an unsupported provider hierarchy, or a correction that never reached the mutation path.

GitHub issues #178 and #180 expose the same control failure from different directions. Linear may not support the assumed native hierarchy, while Finder may continue from stale intent after the user splits scope, rejects a stage, requests removal, or changes topology. The system needs one versioned control contract from human intent through exact provider readback.

The primary actors are the human directing Finder, the agent routing the Fog lifecycle, the agent executing write-backlog, and the maintainer turning a provider incident into a durable regression fixture. The desired outcome is a provider-neutral, correction-aware workflow that spends more effort before a structural write and substantially less effort reconstructing state or repairing drift.

Non-Goals

• Mutate or reorganize the Collective Intelligence Linear workspace as part of this Harness change.
• Make the issue #178 fallback hierarchy a universal Linear Free default.
• Automatically migrate projects that use the former nested-Initiative projection.
• Add backlog providers or weaken an existing provider's exact-readback gate.
• Choose a provider-wide default for physical deletion, archival, cancellation, or closure.
• Replace the semantic Product Area, Initiative, Epic, Story, Task, Fog, or grilling-stage concepts with provider-native terminology.
• Turn each grilling question or unresolved detail into a provider ticket.

User Stories

US-001: Agent establishes provider-safe topology

As the agent initializing or resuming a backlog, I can use one explicitly approved projection profile that explains how stable semantic roles map to the current provider so I never infer topology from provider names alone.

US-002: Human correction remains authoritative

As the human directing Finder, I can correct scope, stage, topology, or cleanup intent once and have that correction invalidate every stale downstream proposal without losing the history needed to avoid repeating it.

US-003: Agent keeps each Fog coherent

As the agent receiving a request with unrelated outcomes, I can split it into coherent candidate work sets before any Fog write and keep only one unresolved stage working set active within each Fog.

US-004: Agent advances stages from evidence

As the agent driving a Fog, I can project Stories and start Technical work only after the required accepted evidence and provider readback exist for the preceding stage.

US-005: Human controls provider mutations precisely

As the human reviewing a backlog change, I can see the exact current and intended topology, authorize a specific structural or cleanup operation, and receive exact readback of what changed and what remains.

US-006: Agent resumes without transcript reconstruction

As an agent resuming cold, I can reconstruct the current route from fresh provider state plus structured intent and correction state without treating a narrative handoff as current authority.

US-007: Maintainer accretes control knowledge

As a Harness maintainer, I can encode each observed routing or provider failure as an executable fixture so the same class of drift is rejected permanently.

Acceptance Criteria

• AC-001: The semantic backlog graph retains stable Product Area, Initiative, Epic, Story, Task, Fog, and grilling-stage identities independently of their native provider representation.
  • Covers: US-001
• AC-002: A projection profile records, for every semantic role in use, its native object, native relation, collapsed or mirrored representation, unavailable capability, and exact readback method.
  • Covers: US-001
• AC-003: Initialization and Normalization produce zero provider writes when no explicitly approved projection profile matches the current provider and project topology.
  • Covers: US-001, US-005
• AC-004: Selecting or changing a projection profile is classified as a structural change and is bound to an explicit approval of its topology fingerprint.
  • Covers: US-001, US-005
• AC-005: The Collective Intelligence regression profile represents one root Initiative, five direct high-order business-area Projects, issue Epics, issue Stories, sub-issue Tasks, zero sub-Initiatives, and Product Area issue or label mirrors that do not become ownership parents.
  • Covers: US-001, US-007
• AC-006: A projection profile that cannot prove a required native capability or readback method returns typed setup guidance with zero provider writes.
  • Covers: US-001, US-005
• AC-007: Finder state carries a positive monotonic intent epoch for the current accepted human intent.
  • Covers: US-002, US-006
• AC-008: Every accepted correction appends a ledger entry containing the corrected decision, prior and current value, reason, affected semantic identities, invalidated downstream intents, and any requested cleanup.
  • Covers: US-002, US-006
• AC-009: Every accepted correction that changes scope, stage, topology, or cleanup intent advances the intent epoch exactly once.
  • Covers: US-002
• AC-010: A router result, mutation preview, approval, or mutation plan bound to an older intent epoch is rejected with zero provider writes.
  • Covers: US-002, US-005
• AC-011: Fresh provider evidence determines current operational facts while the correction ledger continues to constrain proposals that fresh state alone cannot explain.
  • Covers: US-002, US-006
• AC-012: Before allocating a Fog identity or emitting a Fog mutation intent, Finder groups the request by product outcome, owning area, repository boundary, and observable acceptance signal.
  • Covers: US-003
• AC-013: A request containing unrelated work sets returns a split preview with zero provider writes until the human selects or approves coherent Fog boundaries.
  • Covers: US-003, US-005
• AC-014: Each Fog has at most one unresolved working set at the router-selected grilling stage unless an explicit accepted split creates separate coherent Fogs.
  • Covers: US-003, US-004
• AC-015: Multiple accepted Functional children and their distinct resulting Stories remain valid after the one-unresolved-working-set constraint is satisfied.
  • Covers: US-003, US-004
• AC-016: One Functional working set uses one grilling child for one coherent Story intent; its individual questions remain in the durable grilling artifact rather than becoming sibling provider tickets.
  • Covers: US-003, US-004
• AC-017: A grilling child's canonical Stage is immutable after creation; reclassification supersedes the old intent and requires a new correctly staged identity instead of relabeling the existing child.
  • Covers: US-002, US-004
• AC-018: Functional Story projection is rejected until its Functional child has immutable accepted evidence and the accepted Business projection has exact provider readback.
  • Covers: US-004
• AC-019: Technical work is rejected until the selected Story is the exact projected result of one accepted Functional child and its placement has been read back from the current provider snapshot.
  • Covers: US-004
• AC-020: Every mutation plan is versioned and bound to the current intent epoch, semantic graph hash, projection profile identity and hash, provider snapshot identity, intended topology fingerprint, and approval record.
  • Covers: US-002, US-005, US-006
• AC-021: Mutation execution rejects a stale epoch, semantic graph, projection profile, provider snapshot, topology fingerprint, or approval record with zero provider writes.
  • Covers: US-002, US-005
• AC-022: A structural preview identifies the exact current and intended native parent or membership for every affected semantic object, including the owning Project placement of each Fog, Epic, Story, and Task when the selected profile requires it.
  • Covers: US-001, US-005
• AC-023: Exact post-write readback returns every observed object and relation plus a residual delta; partial success cannot be reported as complete.
  • Covers: US-005, US-006
• AC-024: Delete, cancel, archive, close, detach, supersede, and duplicate are distinct mutation intents with distinct readback results.
  • Covers: US-002, US-005
• AC-025: The provider writer executes only the exact cleanup operation the human authorized and the provider supports; it never substitutes Duplicate for removal.
  • Covers: US-002, US-005
• AC-026: Destructive cleanup requires exact stable targets, a current provider read, explicit operation approval, and final readback.
  • Covers: US-005
• AC-027: Requirements supersession records the affected downstream semantic and provider intents so Finder must reconcile or hand back before advancing.
  • Covers: US-002, US-004
• AC-028: The durable machine-readable control state records the schema version, Fog identity, intent epoch, accepted scope, coherent work sets, current stage and working set, semantic graph, projection profile, correction ledger, provider snapshot, topology fingerprint, mutation plan, approval, exact readback, residual delta, and evidence freshness.
  • Covers: US-002, US-006
• AC-029: The human-readable runtime handoff is generated from the validated control state and identifies its source state version and current intent epoch.
  • Covers: US-006
• AC-030: A handoff whose provider snapshot is older than fresh provider state cannot select the route or authorize a mutation.
  • Covers: US-006
• AC-031: Executable fixtures reject cross-area Fog creation, concurrent open Functional shells, premature Story projection, premature Technical routing, stage relabeling, stale correction epochs, Duplicate-for-removal, missing owning Project placement, stale handoff routing, stale approvals, and stale provider snapshots.
  • Covers: US-003, US-004, US-005, US-006, US-007
• AC-032: Executable fixtures accept the Collective Intelligence projection, multiple accepted Functional outcomes after sequential closure, an exact authorized cleanup operation, and cold resume from newer provider state plus preserved correction history.
  • Covers: US-001, US-002, US-004, US-005, US-006, US-007
• AC-033: Each new incident fixture names the violated invariant and the issue or immutable evidence that motivated it.
  • Covers: US-007

Constraints

• write-backlog remains the sole authority for physical provider mutations; Finder emits semantic intent and consumes exact readback.
• The project wiki remains semantic product authority, settings select the provider destination, fresh provider reads prove live state, and immutable accepted resolutions prove stage closure.
• Existing canonical Business, Functional, Technical, Product Area, Initiative, Epic, Story, Task, and Fog terms remain unchanged.
• One Finder invocation creates or resumes exactly one coherent Fog after the decomposition gate.
• Provider capability evidence is scoped to the actual configured workspace; a plan name or generic provider assumption is insufficient.
• Human-readable views may explain state but never replace structured identity, approval, or exact-readback evidence.
• Existing uncommitted shared-skill work is user-owned and must remain outside this change's commits and generated projection.
• Shared reusable skill changes originate on the checked-out main branch of /Users/stefan/Desktop/repos/wearedevpunks-skills, are pushed there first, and are synchronized into Harness from the exact pushed receipt.

Dependency Readiness

Ready.

• Research authority is retained in Harness commit 5a4acbfc at apps/wiki/content/docs/project/research/finder-provider-projection-intent-control-research-report.md.
• Shared-skill authority is available on main at commit 2c7473179569d237acd3d01a2df055cb76d2e174.
• The current Harness branch is based on origin/main commit 694420ca and already contains the retained research commit.
• Linear sub-Initiatives being Enterprise-only is documented by the provider at https://linear.app/docs/sub-initiatives; runtime capability and current project topology still require workspace-specific readback.

Branch/Base Intent

• Harness work continues on team/stefan/finder-control-envelope, based on origin/main at 694420ca.
• Reusable skill work lands on and is pushed from the checked-out shared-source main branch before Harness synchronizes the exact resulting commit.
• No Collective Intelligence repository branch or Linear mutation is part of this implementation.

Accepted Technical Decisions

• Use a provider-neutral semantic graph and a separately persisted provider projection profile. Provider adapters translate; they do not redefine product semantics.
• Persist one versioned, machine-readable control state per durable Fog identity under the existing .devpunks/finder-phase runtime authority. Generate the concise Markdown handoff from that state.
• Use a monotonic intent epoch and append-only correction ledger. Any material correction invalidates older downstream route, projection, approval, and mutation artifacts.
• Compile a deterministic mutation plan before preview or execution. Bind its identity to the semantic graph, projection profile, provider snapshot, intended topology, intent epoch, and approval.
• Treat projection-profile selection and changes as structural operations. Projects without an approved compatible profile stop before mutation.
• Keep one unresolved stage working set per Fog while allowing multiple accepted Functional results over time.
• Keep stage identities immutable. Reclassification is explicit supersession, not a label edit.
• Model cleanup actions explicitly. Duplicate is a semantic relation and cannot satisfy deletion, cancellation, archival, closure, detachment, or supersession intent.
• Preserve fresh provider state and correction history as separate authorities inside one envelope: fresh state selects operational facts; correction history limits permissible proposals.

Accepted Testing Decisions

• Extend the existing Node contract-test suite rather than add a second test runner.
• Represent #178 provider shapes and #180 lifecycle failures as named JSON fixtures consumed by deterministic contract validators.
• Test zero-write rejection results as first-class outputs, including the exact stale or unsupported binding that caused rejection.
• Test both acceptance and rejection paths for projection profiles, working-set cardinality, stage gates, correction epochs, mutation approvals, cleanup operations, readback residuals, and cold resume.
• Verify the shared source first, then verify exact source-to-Harness projection and the Harness CLI/wiki surfaces that distribute or document the contracts.

Verification Seams

• The control-state validator proves schema completeness, epoch monotonicity, working-set cardinality, stage-transition prerequisites, and correction invalidation.
• The provider-profile validator proves semantic-to-native mappings, unavailable capabilities, current topology fingerprint, and exact-readback requirements.
• The mutation-plan validator proves all authority bindings and returns either a write-eligible plan or a zero-write typed rejection.
• The provider adapter preview and exact readback expose the current topology, intended topology, observed delta, and residual delta.
• The generated runtime handoff exposes the source state version, current epoch, provider snapshot identity, selected route, accepted corrections, and unresolved work without becoming mutation authority.
• Contract fixtures provide the reproducible boundary for every failure and success enumerated in AC-031 and AC-032.

Parked Decisions

• A generic Linear Free default profile. Owner: future provider-capability requirements grill. Resume trigger: a project without an approved profile needs initialization after reliable capability evidence is available.
• Automatic detection versus operator confirmation for each Linear capability. Owner: future Linear adapter requirements grill. Resume trigger: the connected provider API can prove more capability facts or a project requires a new profile.
• Migration from the former nested-Initiative projection. Owner: dedicated backlog-migration requirements grill. Resume trigger: an existing project explicitly requests migration.
• Provider-wide default cleanup semantics. Owner: future provider-specific recoverable-actions requirements grill. Resume trigger: a provider workflow requests a default beyond the exact operation authorized for one mutation.

Decision Log