Finder Provider Projection and Intent Control Research

Scope and method

This report consolidates three readonly lanes:

1. GitHub issue #178, the Linear hierarchy contract, and current Collective Intelligence provider state.
2. GitHub issue #180, the supplied Finder handoff, and the current staged Finder implementation.
3. The full agent control path from user intent through phase routing, backlog projection, provider mutation, readback, correction, and cold resume.

Primary evidence came from current shared-skill projections, Harness design documents, the supplied handoff at /tmp/collective-intelligence-finder-handoff.3I9pI5/HANDOFF.md, both GitHub issue bodies, and fresh Linear reads on 2026-09-01. Research lanes made no repository or provider mutations.

Synthesized conclusion

Issues #178 and #180 share one architectural defect. Harness has semantic rules, provider adapter rules, and conversational correction rules, but no single versioned contract binds them for one operation.

The current workflow can therefore hold three individually plausible states at once:

• Finder prose describes the intended stage and Fog lifecycle.
• write-backlog prose describes one fixed provider hierarchy.
• the actual provider contains a different, later human-approved topology.

Fresh evidence may reveal the mismatch, but the agent must reconstruct the conflict from several documents and transcript history. Provider writes remain vulnerable to stale stage, stale topology, fragmented scope, and lost corrections until the mismatch is noticed manually.

The smallest coherent system change is a compiled control envelope. Every Finder route and every backlog mutation should consume the same durable intent epoch, provider projection profile, correction ledger, provider snapshot identity, and approved topology fingerprint. A stale or incomplete envelope must produce zero writes.

Facts

Current semantic and mutation authorities

• Finder reconstructs state from fresh Fog, child, relation, provider-object, immutable-evidence, and runtime-handoff reads. It loads one router-selected gate, while write-backlog owns all physical provider mutations. Source: .agents/skills/finder-phase/SKILL.md.
• Finder evidence precedence is current provider, repository, and wiki evidence; fresh workflow artifacts; valid runtime handoff; then suggested route. Source: .agents/skills/finder-phase/references/state-graph.md.
• The writer reads provider state, constructs the complete intended mutation in memory, previews structural changes, applies only the approved delta, and performs exact readback. Source: .agents/skills/write-backlog/SKILL.md.
• Requirements grilling already preserves stable question identities and explicit supersession history. Source: .agents/skills/requirements-grill/references/artifact-output.md.
• The runtime handoff preserves identities, immutable pointers, intended projection, exact readback, provider snapshot, blockers, and suggested route. It has no typed correction lineage or approved topology fingerprint. Source: .agents/skills/finder-phase/references/runtime-handoff.md.

Issue #178 contradicts the current Linear adapter

The current provider-neutral model fixes this hierarchy:

Product/Backlog Root
└── Product Area
    └── Initiative
        └── Epic
            └── Story
                └── Task

Source: .agents/skills/write-backlog/SKILL.md, .agents/skills/write-backlog/REFERENCE.md, and .agents/skills/write-backlog/assets/concepts/backlog-model.md.

The current Linear adapter maps both Product Area and Initiative to native Initiative levels, then maps Epic to a Linear Project. It requires exact Root to Product Area to Initiative hierarchy readback. Source: .agents/skills/write-backlog/references/providers/linear.md.

Issue #178 records that nested Initiatives were unavailable in the observed Linear plan. Its expected fallback used one root Initiative, issue and label representations for Product Areas, Projects for delivery Initiatives, issue hierarchy for delivery work, and lateral Fogs. Source: GitHub issue #178.

Fresh Collective Intelligence provider readback on 2026-09-01 shows a later accepted projection:

• CI - PLATFORM is the sole root Initiative, stable ID 6512884d-b6e4-43cc-859f-610eabc609be.
• The root has zero sub-Initiatives.
• Five direct Projects are the high-order business areas: Platform Administration & Distribution, Knowledge & Data, Integrations & Ingestion, AI Work & Automation, and Studio Experience.
• Functional Epics are issues inside an owning business-area Project.
• Product Area issues and grouped Area labels mirror Projects for issue views and classification.
• Fogs remain lateral issues, but Project membership makes them visible through the root Initiative.

Primary provider source: CI - PLATFORM and its five direct Project readbacks.

The current Linear adapter cannot represent this accepted topology faithfully. It would classify the absence of nested Initiatives and Epic Projects as hierarchy drift even though the live provider description explicitly says that no sub-Initiatives are used.

Issue #180 exposes missing execution constraints

The current design already contains several correct safeguards:

• one Fog per Finder invocation;
• Fog remains lateral provenance;
• immutable Functional acceptance precedes Story projection;
• Functional projection and exact readback precede Technical work;
• duplicate or ambiguous identities route to human steering;
• structural changes require preview and approval;
• a suggested route cannot outrank fresh evidence.

Sources: .agents/skills/finder-phase/references/entrypoint-contract.md, .agents/skills/finder-phase/phases/functional-grilling.md, .agents/skills/finder-phase/phases/router.md, .agents/skills/finder-phase/phases/reconcile.md, .agents/skills/finder-phase/scripts/finder-contract.mjs, and .agents/skills/write-backlog/SKILL.md.

Issue #180 records that the live workflow still created a cross-cutting Fog, projected Stories and Technical work before Functional closure, attempted a Functional-to-Business relabel, fragmented one Functional grill into many tickets, used Duplicate when removal was requested, omitted owning Project placement, and repeatedly lost corrections. Source: GitHub issue #180 and the supplied handoff.

The implementation leaves the following gaps:

• Fog creation has no pre-Fog decomposition gate for unrelated concerns.
• One Functional child per Story intent permits several concurrently open Functional shells; there is no one-open-grill working-set invariant.
• Stage child identities are an untyped handoff field. No parser binds stage, cardinality key, story intent, correction revision, and supersession.
• The handoff has no rejected-proposal, superseded-topology, cleanup, or deletion-readback ledger.
• Requirements supersession does not explicitly invalidate already emitted downstream provider intents.
• The provider writer has no retraction contract that distinguishes delete, cancel, archive, close, and duplicate.
• Finder route logic is a script projection without the claimed reproducible route fixture suite in this checkout.

Primary sources: .agents/skills/finder-phase/references/runtime-handoff.md, .agents/skills/finder-phase/phases/ensure-fog.md, .agents/skills/write-backlog/references/fog-intake.md, .agents/skills/requirements-grill/references/artifact-output.md, and .agents/skills/finder-phase/AUTHORING-HANDOFF.md.

The supplied handoff is already stale in one branch

The supplied handoff says all four Fogs have exactly one open Functional child and no Story or Technical projection. Fresh Linear reads on 2026-09-01 still confirm that shape for Extensions, n8n migration, and Devpunks Intelligence. Dataset Platform has advanced:

• COL-237 Business and COL-212/COL-238/COL-239/COL-240 Functional grills are Done.
• COL-241 through COL-244 are projected Stories under Epic COL-203.
• COL-245 is related as the Technical grill for COL-241.

Primary provider source: fresh reads of COL-203, COL-212, and COL-231 through COL-245 in the Collective Intelligence workspace.

This is expected temporal drift. It proves why a narrative handoff cannot be treated as a current execution plan. The handoff remains historical evidence for corrections; current provider and immutable resolution evidence must determine the route.

Conflicts

Fixed hierarchy versus provider projection

The provider-neutral model currently treats semantic hierarchy and physical provider hierarchy as the same graph. Linear Free and the accepted Collective Intelligence topology require a projection graph with collapsed or mirrored semantic layers.

Issue #178 fallback versus later accepted Collective topology

Issue #178 describes Product Area anchor issues and delivery-Initiative Projects. Current Collective provider authority describes the five Projects themselves as high-order business areas, with Product Area issues and labels as mirrors. The system must not hardcode the issue's initial workaround as the universal Free-tier model.

One Functional child per Story intent versus one open working set

The general Finder contract correctly allows multiple accepted Functional outcomes. Issue #180 requires one compact open Functional grill per coherent Fog during active discovery. The durable invariant should constrain concurrent open work, while preserving multiple accepted Functional resolutions and resulting Stories.

Fresh state versus correction history

Fresh provider state must win for operational facts. Rejected proposals and user corrections must remain durable because they constrain what may be proposed next. These are separate authorities and need separate fields in one control envelope.

Inferences

The agent needs a compiled control tower

The system becomes easier to drive when each layer has one job and one typed output:

Human intent and corrections
  -> coherent work-set decomposition
  -> Finder stage state
  -> semantic backlog graph
  -> approved provider projection profile
  -> versioned mutation plan and topology fingerprint
  -> preview or approval token
  -> provider execution
  -> exact readback and residual delta
  -> generated cold-resume handoff

Every arrow should be a validated contract. Later layers may add provider evidence, but they cannot reinterpret an earlier human decision silently.

The semantic graph must survive provider differences

A Product Area, Initiative, Epic, Story, Task, Fog, and grilling stage should retain stable semantic identities even when one provider collapses a layer, mirrors it with a label, or uses a different native object. The provider projection profile should record each mapping explicitly:

• native object;
• native relation;
• collapsed semantic layer;
• mirrored classification;
• unavailable capability;
• exact readback method.

This gives agents one conceptual model while keeping provider truth explicit.

Corrections should advance an epoch

Every accepted correction should advance a monotonic intent epoch. It should preserve:

• the accepted scope and target depth;
• coherent Fog boundaries;
• canonical stage terminology;
• rejected or superseded proposals;
• invalidated downstream intent and provider identities;
• cleanup requested and exact cleanup readback;
• current provider snapshot and projection profile;
• approved topology fingerprint.

Any router result, preview, approval, or provider write compiled from an older epoch should fail closed.

Cold resume should be generated from state

The human-readable handoff should be a projection of machine-readable state plus concise history. An agent should not have to reconstruct the current route from a transcript or manually reconcile several prose summaries.

Recommended system design

1. Provider-neutral semantic graph

Keep semantic roles stable. Remove provider-native assumptions from the core topology. Represent whether a semantic layer is required for one product context and whether a provider projection maps, mirrors, or collapses it.

2. Persisted projection profile

Initialization and Normalization should resolve provider capabilities and current approved topology before proposing writes. Persist a stable profile ID, capability evidence, semantic-to-native mapping, required views and fields, fallback limits, and readback contract.

At minimum, Linear needs distinct profiles for:

• native nested-Initiative hierarchy when supported and explicitly accepted;
• root Initiative plus business-area Projects, issue Epics, issue Stories, and sub-issue Tasks, matching current Collective Intelligence authority;
• any alternative Free-tier mapping only after explicit project approval.

Profile selection is structural. $show-me previews it, explicit approval binds its topology fingerprint, and subsequent writes reuse it until a new approved migration supersedes it.

3. Intent epoch and correction ledger

Extend Finder state with structured fields for intent revision, stage, cardinality key, story intent, coherent work-set identity, rejected proposals, superseded topology, invalidated projection IDs, cleanup result, projection profile, provider snapshot, and approved topology fingerprint.

Requirements supersession should invalidate affected downstream intents. The router should reconcile or hand back before any later-stage work continues.

4. Pre-Fog decomposition and active-work cardinality

Before ensure-fog, classify independent concerns by product outcome, owning area, repository boundary, and acceptance signal. A request containing unrelated concerns returns a split preview with zero provider writes.

For each Fog, permit at most one open grilling working set at the current stage unless the user explicitly accepts a split. Accepted children may remain many; concurrent unresolved shells stay bounded.

5. Versioned mutation plan

write-backlog should compile a complete mutation plan containing:

• intent epoch;
• semantic graph hash;
• projection profile ID and hash;
• provider snapshot identity;
• intended stable objects and relations;
• destructive or structural classifications;
• validation results;
• required approval token.

Execution rejects a stale epoch, profile, snapshot, or approval token. Exact readback returns observed writes and a residual delta.

6. Explicit retraction semantics

Define delete, cancel, archive, close, duplicate, detach, and supersede separately. An agent may apply only the operation the user authorized and the provider supports. Destructive cleanup requires exact stable targets, current readback, and final readback. Duplicate remains a semantic relationship, not a safe substitute for removal.

7. Executable contract fixtures

Add route and mutation fixtures for:

• Linear capability profile selection;
• current Collective root plus direct Projects and zero sub-Initiatives;
• cross-area request split before Fog creation;
• one compact open Functional working set;
• Functional closure before Story projection;
• Story readback before Technical projection;
• stage relabel rejection;
• correction epoch invalidation;
• deletion versus Duplicate;
• missing owning Project placement;
• stale handoff versus newer provider state;
• stale approval or provider snapshot rejection.

Each real workflow failure should become one durable regression fixture. This is the accretive loop: provider incidents improve the executable control system instead of expanding prose alone.

Resource effects

The proposed envelope reduces repeated work:

• one batched fresh provider read produces a snapshot identity;
• one projection profile prevents repeated plan-capability reasoning;
• one semantic graph eliminates provider vocabulary leakage across phases;
• one intent epoch prevents transcript reconstruction after corrections;
• one mutation plan supports preview, approval, execution, and readback;
• one generated handoff makes cold resume deterministic;
• one fixture per failure preserves hard-won knowledge cheaply.

The workflow spends more effort before the first structural write and materially less effort on cleanup, correction replay, duplicate tickets, and provider re-audits.

Decisions and open questions

DECIDED by current evidence

• Collective Intelligence uses CI - PLATFORM as one root Initiative with five direct high-order business-area Projects and no sub-Initiatives.
• Fogs remain lateral provenance and gain root visibility through owning Project membership.
• Existing stage terminology and user corrections must survive handoff and resume.
• Functional acceptance precedes Story projection; stable Story projection and readback precede Technical work.
• Unrelated concerns require separate coherent Fogs.
• Duplicate cannot substitute for an explicitly requested removal.
• Fresh provider evidence outranks a stale suggested route or narrative handoff for operational state.

RECOMMENDED

• Introduce the compiled control envelope described above.
• Treat provider projection as a persisted, approved profile rather than a hardcoded universal mapping.
• Constrain one open stage working set per Fog while preserving multiple accepted children.
• Generate human handoffs from structured state and correction history.
• Convert #178 and #180 into executable provider, route, and mutation fixtures.

OPEN

• Whether a generic Linear Free default should exist when no approved project profile is present. Zero-write setup guidance is safer until provider capability detection is proven.
• The exact durable location and serialization for the projection profile and intent epoch.
• Which Linear capability facts can be detected through the connected API and which require operator confirmation.
• Whether unsupported saved views produce a typed degraded profile or block initialization.
• Migration policy for projects that already use the former nested-Initiative projection.
• Whether physical deletion, soft deletion, archive, or cancellation is the default cleanup operation for each provider. The requested operation and provider behavior must remain explicit.

Next local action

Create an execution-ready specification and plan that scopes the first implementation to shared Finder and write-backlog contracts, executable fixtures, Harness projections, and aligned durable docs. Preserve the pre-existing uncommitted shared-skill edits and avoid overlapping them unless their ownership is resolved.