Spec: Finder Intake and Requirements Boundary

Context

Harness needs one simple path from uncertain product intent to delivery-ready work. Business-first and functional-first colleagues need nontechnical Finder entrypoints. Engineering agents need one obvious authority for closing full requirements and projecting Stories and Tasks.

Issue #180 showed the cost of the former staged model. The workflow created premature Stories and Technical work, fragmented one uncertainty into many tickets, combined unrelated Fogs, lost corrections, and made the next route depend on which Finder stage had already run. A requirements-first invocation could not reach backlog projection unless Technical Finder had created an exact Story first.

Issues #178 and #183 establish the provider constraint. Linear Free cannot represent the semantic hierarchy with nested Initiatives. The final accepted projection uses one native Initiative root, Product Area Projects, and labeled parent-child Issues for Initiative, Epic, Story, and Task.

The target system is:

Business Finder
  -> finder-phase
  -> Fog + generic support work
  -> optional Product Areas and Initiatives

Functional Finder
  -> finder-phase
  -> Fog + generic support work
  -> optional Business structure plus Epics

Direct requirements -------------------+
Optional Finder context ---------------+--> Requirements Phase
                                             -> Requirements Grill
                                             -> Create Spec
                                             -> Write Backlog
                                             -> derived Stories and Tasks

Business Finder and Functional Finder are human interaction profiles over the same Finder engine. They are not maturity stages. Finder context is optional for Requirements Phase. Story and Task counts are outputs derived from accepted requirements, never inputs or gates.

Supersession

This specification supersedes every conflicting requirement in these historical artifacts:

• project-backlog-operating-model/SPEC.md
• issue-178-180-finder-provider-intent-control/SPEC.md
• /tmp/collective-intelligence-finder-handoff.3I9pI5/HANDOFF.md

Specifically superseded are Technical Finder, Business/Functional/Technical Grilling stages, cumulative stage prerequisites, fixed Grilling-child or Story/specification cardinality, and earlier Linear Free mappings. Historical tickets, specifications, plans, implementation notes, and provider records stay unchanged as evidence. They do not define the current route.

Non-Goals

• Migrate, relabel, rewrite, replace, close, or clean up historical staged Grilling tickets.
• Design CI/CD event automation, release promotion, or pipeline-to-provider updates.
• Model sprints, Linear Cycles, or another scheduling system.
• Prescribe how many Grilling children, specifications, Stories, or Tasks a bounded request must produce.
• Make Finder an implicit model-selected route.
• Require Finder before Requirements Phase.
• Let Business Finder or Functional Finder project Stories or Tasks.
• Let Design Phase or another entrypoint bypass Requirements Phase for new Stories or Tasks.
• Add Azure DevOps, monday.com, or another backlog provider.
• Define Normalization invocation cadence.
• Define implementation files, commands, workers, delivery waves, or execution order.

Requirements and Outcomes

OUT-001: Business colleague captures uncertain product intent

As a colleague without technical capability, I can explicitly invoke Business Finder, describe the business situation in familiar language, and receive a Fog with useful optional Product Area and Initiative structure without discussing implementation.

OUT-002: Functional colleague develops product behavior

As a functional colleague, I can explicitly invoke Functional Finder with all Business Finder capabilities plus nontechnical functional depth, and optionally produce the applicable Business structure plus Epics without creating Stories or Tasks.

OUT-003: Requirements practitioner closes delivery requirements

As a requirements practitioner, I can invoke Requirements Phase directly or with optional Finder context, close the actual decision frontier, compile the accepted result, and project whatever Stories and Tasks that result requires.

OUT-004: Agent resumes uncertain work without a stage ladder

As an agent resuming a Fog, I can inspect its generic Grilling, Research, and Prototype support work, decide whether to reuse an obvious child or create another useful child, and request human steering only when the evidence is genuinely ambiguous.

OUT-005: Product owner sees one coherent product and delivery structure

As a product owner, I can see Product Areas, Initiatives, Epics, milestone-bound Stories and Tasks, lateral Fogs, roadmap progress, and active delivery without translating provider-specific objects.

OUT-006: Backlog operator writes provider state safely

As a backlog operator, I can initialize, project, or normalize the accepted semantic structure through one provider writer that validates identity, previews material changes, and reads every write back exactly.

OUT-007: Delivery agent reports Fog completion truthfully

As a delivery agent, I can distinguish work started, blocked, reviewed, merged, staged, and produced, and complete a Fog only from production evidence for its accepted resulting scope.

Acceptance Criteria

• AC-001: The public Finder entrypoints are exactly Business Finder and Functional Finder. Both entrypoints and the internal finder-phase reject implicit model invocation.

  • Covers: OUT-001, OUT-002, OUT-004

• AC-002: Every public Finder invocation composes the shared finder-phase engine. No wrapper implements a second Fog lifecycle, support-work router, or provider writer.

  • Covers: OUT-001, OUT-002, OUT-004

• AC-003: Finder creates or resumes one Fog type. The Fog records its immutable original Business or Functional intake lens without using that lens as a maturity state.

  • Covers: OUT-001, OUT-002, OUT-004

• AC-004: Business Finder uses nontechnical business guidance and wording to capture the actor or affected party, problem or opportunity, desired outcome and value, evidence, constraints, non-goals, urgency, and open questions. Unknown values remain explicit.

  • Covers: OUT-001

• AC-005: Business Finder may reuse, enrich, or create applicable Product Areas and Initiatives through write-backlog. The projection is optional, never includes an Epic, and never blocks a valid Fog from returning.

  • Covers: OUT-001, OUT-005, OUT-006

• AC-006: Functional Finder includes every Business Finder capability and adds nontechnical functional guidance for actor, trigger, workflow, observable result, applicable domain rules, visible alternate and failure paths, acceptance signals, boundaries, known product dependencies, technical handoff questions, and target V* milestone context.

  • Covers: OUT-002

• AC-007: Functional Finder may reuse, enrich, or create its optional Business structure plus Epics: Product Areas, Initiatives, and Epics. It never projects Stories or Tasks, and it does not require Business Finder to have run first.

  • Covers: OUT-002, OUT-005, OUT-006

• AC-008: Functional Finder does not require architecture, APIs, data models, component boundaries, code structure, Tasks, commands, workers, or implementation design.

  • Covers: OUT-002

• AC-009: Finder uses generic Kind/grilling children. Business, Functional, and Technical are not Grilling kinds, Stage values, provider maturity fields, or ordered prerequisites.

  • Covers: OUT-001, OUT-002, OUT-004, OUT-006

• AC-010: A Fog may own several generic Grilling children and direct Research and Prototype support children. No schema or router imposes a maximum or a cross-wrapper semantic-key requirement.

  • Covers: OUT-004

• AC-011: Finder reuses an obviously relevant Grilling, Research, or Prototype child or creates another when current evidence supports separate useful work. Wrapper choice alone forces neither action. Genuine ambiguity returns human steering without creating a duplicate.

  • Covers: OUT-004

• AC-012: Research and Prototype identify the unknown or Grilling work they support, return durable evidence or a verdict, and never authorize backlog projection independently.

  • Covers: OUT-004

• AC-013: Reaching a Finder wrapper's bounded result returns control without asserting that the Fog is resolved or complete.

  • Covers: OUT-001, OUT-002, OUT-004, OUT-007

• AC-014: Requirements Phase is independently invocable with ordinary bounded requirements input. When no Finder context is supplied, it creates no Fog or Grilling provider item implicitly.

  • Covers: OUT-003

• AC-015: When a caller supplies a Fog, Finder child, Research child, Prototype child, or durable Finder handoff, Requirements Phase loads a conditional Finder-context contract, resolves the exact identity and owning Fog graph, and does not silently take ownership of sibling work.

  • Covers: OUT-003, OUT-004

• AC-016: Requirements Phase is the only orchestration route that runs the full Requirements Grill, invokes Create Spec, and then authorizes Story, Task, and blocker projection through write-backlog.

  • Covers: OUT-003, OUT-006

• AC-017: Requirements Phase does not ask for or prescribe a Grilling-child, specification, Story, or Task count. Create Spec compiles the accepted result, and Write Backlog derives the explicit Stories and Tasks supported by that result and current provider evidence.

  • Covers: OUT-003, OUT-006

• AC-018: Each derived Story remains a shippable product outcome, and every derived Task remains atomic, independently ownable, and understandable from its Story and stable specification authority. These quality rules do not impose a count.

  • Covers: OUT-003, OUT-005

• AC-019: Create Spec returns readiness: agent-ready only after the confirmed requirements are retained at a verified immutable commit and stable blob URL. Write Backlog rejects a mutable or local-only specification reference.

  • Covers: OUT-003, OUT-006

• AC-020: Design Phase returns accepted design evidence to Requirements Phase when that evidence requires new Stories or Tasks. It cannot invoke a former Technical projection directly.

  • Covers: OUT-003

• AC-021: Historical Business, Functional, and Technical Grilling tickets remain byte-for-byte and provider-state unchanged unless a separately authorized operation targets them. Resuming related work does not trigger migration, normalization, relabeling, or replacement, and the former Stage is not a current gate.

  • Covers: OUT-004, OUT-006

• AC-022: The provider-neutral ownership hierarchy is Product/Backlog Root to Product Area to Initiative to Epic to Story to required Task. Fog stays lateral and records provenance for every structure or delivery item it enriches or produces.

  • Covers: OUT-005, OUT-006, OUT-007

• AC-023: linear-free-v1 is the sole default Linear Free projection. It maps Product/Backlog Root to a native Initiative, Product Area to a Project, Initiative to an Issue labeled Kind/initiative, Epic to its child Issue labeled Kind/epic, Story to its child Issue labeled Kind/story, and Task to its child Issue labeled Kind/task.

  • Covers: OUT-005, OUT-006

• AC-024: The Linear Free writer never creates nested Initiatives or a separate Project for each semantic Initiative. It verifies the connected workspace identity before using provider data and requires explicit approved Normalization before changing a divergent live topology.

  • Covers: OUT-005, OUT-006

• AC-025: The GitHub adapter uses one Projects V2 operating surface with Issues, recursive parent and sub-issue relations, repository milestones, blocker relations, semantic fields, and the accepted product-owner views. Missing required representation returns setup guidance with zero writes.

  • Covers: OUT-005, OUT-006

• AC-026: Every Story and Task belongs to one contextual V* milestone iteration, and every Task uses its Story's milestone. Product Areas, Initiatives, and Epics may span milestone iterations.

  • Covers: OUT-003, OUT-005, OUT-006

• AC-027: Task blockers may cross Stories and Epics when real. The complete reachable graph rejects missing targets, future-iteration dependencies, self-edges, and cycles before any provider write.

  • Covers: OUT-003, OUT-005, OUT-006

• AC-028: Product Map shows Product Area, Initiative, and Epic structure; Roadmap shows ordered V* milestone iterations and rolled-up Story and Task progress; Fogs show unresolved provenance; Current Delivery shows active milestone-bound Stories, Tasks, owners, status, and blocker readiness.

  • Covers: OUT-005

• AC-029: write-backlog is the only physical Linear or GitHub mutation authority. It resolves settings and workspace identity, reads every intended target and relation, validates the complete mutation, previews material topology changes, writes only the approved delta, and reads back every written identity, field, parent, milestone, relation, and source link.

  • Covers: OUT-001, OUT-002, OUT-003, OUT-005, OUT-006

• AC-030: Stable provider identity plus durable wiki identity authorizes reuse or enrichment. A title-only match, conflicting identity, incomplete search, unsupported relation, or ambiguous candidate produces zero writes and exact steering.

  • Covers: OUT-004, OUT-006

• AC-031: backlogProjectUrl keeps its current key and identifies the Product/Backlog Root. A legacy destination returns exact hi ensure guidance instead of guessing or creating another root.

  • Covers: OUT-005, OUT-006

• AC-032: Normalization may repair unambiguous stale links or metadata. Boundary, goal, parent, roadmap, duplicate closure, merge, split, reparenting, reorganization, and divergent-topology changes require a preview and explicit approval. Historical staged-ticket metadata is excluded from automatic Normalization.

  • Covers: OUT-005, OUT-006

• AC-033: Fog completion requires production evidence for its accepted resulting delivery scope. Merge does not prove staging or production. Cancelled and Superseded Fogs receive no completion credit.

  • Covers: OUT-007

• AC-034: This capability changes no provider state during specification, planning, or validation. Provider mutations occur only during an explicitly authorized write-backlog operation.

  • Covers: OUT-006

• AC-035: A valid Requirements Phase result without prior Finder projection may cause Write Backlog to reuse, enrich, or create the accepted Product Area, Initiative, and Epic structure needed to place its derived Stories and Tasks. It never fails only because Business Finder, Functional Finder, or Technical Finder did not run first.

  • Covers: OUT-003, OUT-005, OUT-006

• AC-036: Create Spec identifies specification requirements and outcomes with neutral OUT-### identifiers, and readiness requires every OUT-### to have at least one Acceptance Criterion. Write Backlog treats OUT-### only as specification traceability, then derives the actual Epic, Stories, and Tasks after compilation. An OUT-### identifier implies neither a provider Story identity nor a Story count.

  • Covers: OUT-003, OUT-006

• AC-037: The Create Spec template, readiness contract, quality bar, and skill boundary consistently use requirement/outcome terminology and OUT-### traceability. Create Spec has no Technical Finder or exact provider Story prerequisite. Write Backlog requires neither a preselected exact Story nor an accepted Technical Grilling resolution and derives or reuses the accepted Epic, Stories, and Tasks from the retained specification. No affected contract retains US-### as the canonical specification identifier or assumes one outcome equals one Story.

  • Covers: OUT-003, OUT-006

Constraints

• Canonical reusable skill changes originate in /Users/stefan/Desktop/repos/wearedevpunks-skills on its checked-out main branch, are committed and pushed there, and are then synchronized into Harness with exact source-receipt evidence.
• The shared-skill source worktree currently contains user-owned changes in the affected Finder, Requirements, and Write Backlog surfaces. Implementation and planning must preserve and reconcile that state rather than reset or overwrite it.
• The project wiki owns durable product meaning. Settings select the provider destination. Fresh provider reads prove current backlog state. Repository and deployment evidence prove implementation and environment facts.
• Linear and GitHub are the only provider targets in scope.
• Provider writes fail closed when identity, hierarchy, metadata, milestone, relation, approval, or readback cannot be proven.
• GitHub Story-to-Task nesting is API-supported but lacks a live workflow-created grandchild example. The first such write needs exact provider readback before runtime coverage is claimed.
• Existing Linear tickets from the rejected staged workflow remain historical evidence and are not migration inputs.

Dependency Readiness

No Stack Required

No prerequisite code or provider mutation must land before this specification can be planned. Provider availability and permissions remain runtime preflight conditions. The dirty shared-skill source is an implementation starting-state constraint, not an authority that this specification may overwrite.

Branch/Base Intent

Not applicable.

The requirements grill accepted no implementation parent, base, or child branch. Repository-owned branch and shared-skill publication rules remain mandatory constraints for later planning.

Accepted Technical Decisions

• Keep Business Finder and Functional Finder as the only public Finder wrappers. Keep finder-phase as their shared internal graph-based engine and explicit resume target.
• Remove Technical Finder and its Technical target depth, gate, Stage, cardinality rule, catalog exposure, and alternate Story/Task projection route.
• Represent Business and Functional as nontechnical presentation and capability profiles. Do not persist them as Grilling types or maturity stages.
• Keep one Fog type with an immutable original intake lens and generic Grilling, Research, and Prototype support children.
• Let the agent choose obvious support-child reuse or creation from current evidence. Do not add a generic semantic-key or cardinality subsystem.
• Keep Requirements Phase independently invocable. Load Finder-context rules only when a caller supplies Finder context.
• Make Requirements Phase the sole orchestration owner of Requirements Grill, Create Spec, and post-spec Story/Task projection. Keep write-backlog as the physical provider writer.
• Derive Story and Task shape after requirements closure. Do not recreate the Technical Finder one-Story gate inside Create Spec or Write Backlog.
• Keep specification requirements and backlog delivery items as separate identities. Create Spec emits neutral OUT-### identifiers; Write Backlog derives the Epic, Stories, and Tasks and retains OUT-### only for traceability.
• Use the provider-neutral hierarchy and linear-free-v1 projection exactly as defined in AC-022 through AC-025.
• Preserve historical staged tickets unchanged. Compatibility reads may use them as evidence, but no current route depends on their Stage metadata.

Compiler and Projection Repair Guidance

Apply this contract in the canonical shared-skill source, then synchronize its generated Harness mirrors according to the repository constraint above. These are contract surfaces, not an implementation order:

• create-spec/assets/SPEC-TEMPLATE.md: replace the User Stories heading with Requirements and Outcomes, use OUT-001 for the example outcome, and use Covers: OUT-001 for its example Acceptance Criterion.
• create-spec/references/readiness.md: validate that every unique OUT-### has at least one AC-###, every Covers reference resolves to an existing OUT-###, and coverage remains one-way from Acceptance Criterion to outcome.
• create-spec/references/spec-quality-bar.md: describe requirements and outcomes rather than specification-level user stories, require one-way OUT-### coverage links, and treat provider Stories as possible source evidence rather than specification identities.
• create-spec/SKILL.md: remove the Technical Finder conditional input, exact selected Story prerequisite, and Technical projection boundary. Preserve Create Spec as the provider-neutral compiler of confirmed decisions.
• write-backlog/references/technical-projection.md: remove the prerequisites for one exact Story and an accepted Technical Grilling resolution. Consume the verified stable specification, derive or reuse the accepted Epic, derive whatever Stories and Tasks the requirements support, retain OUT-### links as traceability, and keep provider validation, preview, approval, and exact readback gates.

Accepted Testing Decisions

• Create Spec fixtures prove every OUT-### has Acceptance Criteria. Write Backlog fixtures prove OUT-### references remain specification traceability while independently derived Epic, Story, and Task identities and counts vary.
• Contract-consistency fixtures reject US-###, User Stories, a Technical Finder prerequisite, a preselected exact Story, or an assumption of one Story per outcome in the five repair surfaces. At least one projection fixture has different OUT-### and derived Story counts.
• Contract validation proves that only Business Finder and Functional Finder are public explicit-only wrappers and that neither can produce Stories or Tasks.
• Finder validation covers new Fog, exact resume, several generic Grilling children, Research and Prototype support cycles, obvious reuse, useful new child creation, ambiguous human steering, and return without Fog completion.
• Requirements Phase validation covers direct invocation with no Finder artifacts and invocation with each supported optional Finder-context handle.
• Direct Requirements Phase fixtures prove that missing upstream Product Area, Initiative, or Epic structure can be derived from accepted specification authority without a prior Finder projection.
• Requirements-to-backlog fixtures cover accepted outputs with different Story and Task shapes without requiring a count in the input contract.
• Compatibility fixtures prove that completed and open historical staged tickets remain unchanged and do not impose current prerequisites.
• Linear fixtures prove the exact linear-free-v1 hierarchy and reject nested Initiatives, semantic-Initiative Projects, wrong workspace identity, missing Kind labels, wrong parents, and Story/Task milestone mismatch.
• GitHub fixtures prove Projects V2 fields and views, recursive issue hierarchy, milestones, blockers, setup failure, and exact readback behavior.
• Provider mutation tests treat preview, approval, write, exact readback, and residual delta as distinct observable results.
• Task-graph tests cover same-Story and cross-Story blockers plus missing target, future milestone, self-edge, and cycle rejection.
• Delivery-state tests keep start, block, pull request, merge, staging, and production facts distinct and prove that merge cannot complete a Fog.

Verification Seams

• Create Spec readiness output proves complete OUT-### to AC-### traceability without exposing provider Story identities.
• Static contract validation across the template, readiness contract, quality bar, Create Spec boundary, and Write Backlog projection proves the same outcome vocabulary and the absence of old Technical/exact-Story gates.
• Public skill metadata and the scaffold catalog prove the available Finder entrypoints and their explicit-only invocation policy.
• Finder's durable return and handback contracts prove Fog identity, support work, optional projection, ambiguity, and non-completion behavior.
• Requirements Phase results prove both direct and Finder-context routes and identify the stable specification passed to Write Backlog.
• The retained SPEC.md blob URL proves immutable requirements authority.
• Write Backlog's preview and exact provider readback prove the projected hierarchy, identities, labels, milestones, blockers, provenance, and residual delta.
• The provider-neutral Task graph validator proves dependency validity before mutation.
• hi ensure output and .devpunks/settings.json prove Product/Backlog Root destination handling.
• Routed wiki validation proves the current specification, grill, and planning indexes remain discoverable.

Parked Decisions

• CI/CD event automation and release-to-provider projection. Owner: a future requirements grill. Resume trigger: an explicit request to design that workflow after the manual delivery-state contract is implemented and proven.

Decision Log