Spec: Project Backlog Operating Model

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

Context

Harness needs one coherent backlog operating model for nontechnical product intake, proficient functional definition, technical requirements closure, project initialization, provider mutation, normalization, and delivery-state updates.

The confirmed model separates the durable product hierarchy from Fog provenance and delivery iterations:

Product/Backlog Root
└── Product Area
    └── Initiative
        └── Epic
            └── Story [one V* milestone iteration]
                └── Task 1..n [required, same V*, blocker relations]

Fog remains outside this ownership hierarchy. It records intake, uncertainty, accepted decisions, supporting evidence, every structure it enriches, every delivery item it produces, and the production evidence required for completion.

Three human-invoked Finder wrappers expose cumulative decision depths over one graph-based finder-phase engine:

business-finder   → Business grilling                         → Product Area / Initiative / Epic
functional-finder → Business + Functional grilling            → Story
technical-finder  → Business + Functional + Technical grilling → SPEC.md → Tasks / blockers

write-backlog is the sole physical provider mutation authority for Linear and GitHub. It must combine wiki context, repository identity, fresh provider state, accepted grilling evidence, and delivery evidence before writing.

Non-Goals

• Design CI/CD pipelines, pipeline-to-provider automation, release-branch provenance, or automatic shipped-time history.
• Configure or enforce branch protection or repository rulesets.
• Model sprints, provider Cycles, or provider Iteration fields.
• Automatically prioritize or schedule work from backlog priority alone.
• Define the cadence that invokes Normalization.
• Promise Azure DevOps or monday.com support.
• Create a separate public project-initialization or Epic-creation skill.
• Preserve the former Fog-graduation lifecycle as a compatibility mode.
• Define implementation files, commands, worker assignments, delivery waves, or execution order.

User Stories

US-001: Business owner structures a product request

As a nontechnical product owner, I can explicitly invoke Business Finder, resolve why a request matters and where it belongs, and receive one Fog linked to a coherent Product Area, Initiative, and Epic path without needing technical implementation knowledge.

US-002: Proficient user defines shippable behavior

As a technical or proficient nontechnical user, I can explicitly invoke Functional Finder, reuse accepted Business context, define one or more concrete shippable product behaviors, and receive Stories in the correct Epic and milestone iteration.

US-003: Technical user resolves delivery work

As an engineering user, I can explicitly invoke Technical Finder, reuse accepted Business and Functional decisions, close technical requirements per Story, and receive agent-ready specifications plus required atomic Tasks and blocker relations.

US-004: Product owner initializes or reconstructs the backlog

As a product owner, I can use write-backlog to initialize or reconcile a greenfield, inherited, or existing product from its wiki, repository, and provider state so its business context, hierarchy, roadmap, and views remain coherent.

US-005: Operator migrates the configured backlog destination

As a repository operator, I receive actionable hi ensure guidance when backlogProjectUrl still points to a legacy Epic Project and can replace it with the Product/Backlog Root URL without rerunning full scaffold initialization.

US-006: Maintainer normalizes existing backlog state

As a backlog maintainer, I can run Normalization to detect and safely reconcile stale, duplicated, misplaced, or incomplete provider state while retaining approval gates for structural changes.

US-007: Delivery agent keeps work state current

As a delivery agent, I update linked provider items when work starts, becomes blocked, gains a pull request, or obtains directly observed merge or deployment evidence, without treating merge as proof of production.

Acceptance Criteria

• AC-001: business-finder, functional-finder, technical-finder, and finder-phase each declare disable-model-invocation: true; no root or model-routing guidance implicitly starts them.
  • Covers: US-001, US-002, US-003
• AC-002: An explicit invocation of any public Finder wrapper creates exactly one Fog when no Fog identity is supplied, or resumes the exact Fog identified by stable provider or durable wiki identity.
  • Covers: US-001, US-002, US-003
• AC-003: Every wrapper invokes the same finder-phase engine with target depth Business, Functional, or Technical; no wrapper owns a second lifecycle state machine.
  • Covers: US-001, US-002, US-003
• AC-004: Finder reads the Fog, direct children, relations, resolution pointers, provider objects, and evidence before creating anything, then reuses accepted lower stages and resumes the first missing or invalidated stage.
  • Covers: US-001, US-002, US-003
• AC-005: Finder never creates a second Business child, duplicate Functional child for the same Story intent, or duplicate Technical child for one Story; ambiguous identity or conflicting accepted evidence produces zero writes.
  • Covers: US-001, US-002, US-003
• AC-006: Business Finder uses atomic $grilling, $wait-what language, and $show-me views of relevant existing Product Areas, Initiatives, Epics, milestones, and proposed impact before material structural writes.
  • Covers: US-001
• AC-007: Accepted Business grilling may reuse, enrich, or, after required scope-expansion approval, create the resolved Product Area, Initiative, and Epic path through write-backlog while preserving the Fog as provenance.
  • Covers: US-001, US-004
• AC-008: A Fog normally targets one Product Area and Initiative; a request spanning either boundary is shown visually and requires an explicit split-or-proceed decision before projection.
  • Covers: US-001
• AC-009: Functional grilling settles the actor, trigger, observable workflow and result, applicable business rules, visible alternate or failure paths, product-level edge cases, acceptance signals, boundaries, known product dependencies, unresolved engineering questions, and exact target V* milestone iteration.
  • Covers: US-002
• AC-010: Functional grilling uses atomic $grilling, does not require implementation architecture, and produces exactly one Story per Functional child through write-backlog after immutable accepted evidence and provider readback exist.
  • Covers: US-002
• AC-011: Technical grilling runs full $requirements-grill once per Story, compiles one agent-ready SPEC.md, and only then authorizes one or more mandatory Tasks and their blocker relations for that Story.
  • Covers: US-003
• AC-012: One Fog owns exactly one Business grilling child, one or more Functional grilling children, and exactly one Technical grilling child per Story; every child records its immutable resolution pointer and every provider object it created or enriched.
  • Covers: US-001, US-002, US-003
• AC-013: Research and Prototype remain direct Fog children, identify the grilling children they support, return immutable evidence or verdict pointers, and never authorize backlog projection independently.
  • Covers: US-001, US-002, US-003
• AC-014: Provider taxonomy exposes one grilling kind with exactly one Stage value of Business, Functional, or Technical; Finder performs no preliminary generic grill.
  • Covers: US-001, US-002, US-003, US-004
• AC-015: Every Story and Task belongs to exactly one contextual V* milestone iteration, every Task inherits its Story's iteration, and Product Areas, Initiatives, and Epics may span iterations.
  • Covers: US-002, US-003, US-004
• AC-016: A fitting existing milestone is reused before a new milestone is proposed; moving work between milestone iterations requires explicit approval.
  • Covers: US-001, US-002, US-004, US-006
• AC-017: Every Story has one or more atomic, independently ownable Tasks; the complete reachable Task graph rejects missing targets, future-iteration dependencies, self-edges, and cycles while permitting real blockers across Stories and Epics.
  • Covers: US-003
• AC-018: Reaching a wrapper's target depth returns control without completing the Fog; Fog completion requires production evidence for all remaining accepted resulting Stories and Tasks and records the milestone iteration in which the final required work reached production, while Cancelled and Superseded Fogs receive no completion credit.
  • Covers: US-001, US-002, US-003, US-007
• AC-019: write-backlog preserves its current ticket-structuring behavior while routing conditional rules through project-context.md, backlog-initialization.md, fog-intake.md, business-projection.md, functional-projection.md, technical-projection.md, issue-reconciliation.md, normalization.md, delivery-status.md, providers/linear.md, and providers/github.md.
  • Covers: US-001, US-002, US-003, US-004, US-006, US-007
• AC-020: write-backlog resolves destination and authority, reads wiki and provider state, constructs and validates the full intended mutation, previews material topology changes, performs the write, and reads back every intended item, relationship, source link, field, and provider state.
  • Covers: US-001, US-002, US-003, US-004, US-006, US-007
• AC-021: Stable provider identity plus durable wiki identity authorizes enrichment or upsert; title-only or ambiguous matches stop all writes.
  • Covers: US-001, US-002, US-004, US-006
• AC-022: Backlog initialization creates or reconciles the Product brief, business objectives, target users, product boundaries, existing Product Map, durable constraints and non-goals, operating rules, owner, repository link, wiki link, and current/future V* milestone context, projecting only provider-supported metadata.
  • Covers: US-004
• AC-023: Backlog initialization creates or preserves Product Map, Roadmap, Fogs, and Current Delivery views with the accepted contents and without CI/CD or Releases views.
  • Covers: US-004, US-006
• AC-024: Structural boundary, goal, parent, roadmap, duplicate closure, merge, split, reparenting, and reorganization changes require a preview and explicit approval; unambiguous additive links and stale-state repairs may proceed after preflight.
  • Covers: US-004, US-006
• AC-025: Linear maps Product/Backlog Root to a top-level Initiative, Product Area and Initiative to nested Initiatives, Epic to Project, Story to Issue, and Task to sub-issue, after verifying the actual workspace identity rather than trusting an MCP alias.
  • Covers: US-001, US-002, US-003, US-004
• AC-026: GitHub uses one Projects V2 operating surface with configured semantic fields and views plus Issues, recursive sub-issues, repository milestones, and blocker relations; missing required Project V2 representation stops with setup guidance rather than degrading to flat Issues-only output.
  • Covers: US-001, US-002, US-003, US-004
• AC-027: Backlog initialization may provision missing Kind, Grilling Stage, and view metadata only after structural preview and required approval; ordinary writes never invent this metadata ad hoc.
  • Covers: US-004, US-006
• AC-028: backlogProjectUrl keeps its existing key but identifies the provider Product/Backlog Root; a legacy Linear Epic Project URL stops with guidance to rerun hi ensure, and the successful settings-only flow rewrites the same key to the selected root Initiative URL.
  • Covers: US-005
• AC-029: Normalization detects invalid Fog-child placement, missing or invalid Stage values, duplicate or ambiguous structures, stale links and status, hierarchy drift, roadmap drift, and wiki/provider disagreement; it repairs only unambiguous mappings automatically.
  • Covers: US-006
• AC-030: New and resumed work immediately uses the Fog-child lifecycle; Normalization may propose existing-item migration, but no compatibility mode creates new work using the former Fog-graduation model.
  • Covers: US-001, US-002, US-003, US-006
• AC-031: Delivery flow updates the linked provider item immediately when work starts, becomes blocked, or gains a pull-request link, and records directly observed merge or named-environment deployment evidence as distinct facts.
  • Covers: US-007
• AC-032: Merge never proves staging or production deployment, and this change introduces no CI/CD event design or automatic pipeline adapter.
  • Covers: US-007
• AC-033: Functional Finder may start against an exact existing Product Area → Initiative → Epic path without changing business scope; otherwise the shared Finder engine must complete Business grilling before Functional projection.
  • Covers: US-002
• AC-034: Functional Finder uses precise project language, invokes $wait-what when terminology or behavior does not land, and uses $show-me before grilling and at workflow, Story-split, alternate-path, dependency, milestone, and final Story-write decisions.
  • Covers: US-002
• AC-035: A provider-supported V* milestone exposes its version name, one-sentence product goal, and included product outcomes or capability changes; when those fields are unavailable, the version name alone is sufficient.
  • Covers: US-001, US-002, US-004

Constraints

• Canonical shared-skill changes originate in /Users/stefan/Desktop/repos/wearedevpunks-skills on its checked-out main branch, then synchronize into Harness-managed projections with exact source receipt evidence.
• write-backlog remains the only physical provider mutation authority; Finder wrappers and finder-phase produce semantic intent and consume provider readback.
• The project wiki owns durable product meaning; settings select the destination; fresh provider reads prove live backlog state; repository and deployment evidence prove implementation and environment facts.
• A new explicit human decision resolves a genuine semantic conflict and must be persisted in its durable owning source.
• Linear and GitHub are the only provider targets in this scope.
• Provider writes are fail-closed when identity, hierarchy, metadata representation, milestone, or blocker relations cannot be proven.
• GitHub Story-to-Task nesting is API-supported but not yet live-instance-proven; the first workflow-created nested Task requires exact provider readback before runtime coverage is claimed.
• Normalization invocation cadence remains external to the skill.

Dependency Readiness

No Stack Required.

No implementation dependency must land before this capability can be planned. Linear and GitHub API feasibility evidence is recorded in the confirmed grill; provider availability and permissions remain runtime preflight conditions rather than code-stack dependencies.

Branch/Base Intent

• Intended implementation branch: team/stefan/finder-phase-write-backlog-improvements.
• The branch was explicitly created for this capability from local main at 7cc93c73363be3a0fa7803a1f9ca0ed244550469.
• Current remote comparison evidence at compilation: origin/main is 36a328e8916734b603d12ff8f0e42a8e2abf1871; merge base is 87baf138f310db26cbe51bed209df1c7ac48c8e0.
• This is not a stacked child capability. Delivery planning must preserve this specification and reconcile the topic branch with the then-current origin/main before integration.

Accepted Technical Decisions

• The public surface is exactly three cumulative, human-invoked direct-composition wrappers: Business Finder, Functional Finder, and Technical Finder.
• finder-phase is one Durable Workflow Graph and internal re-entry target. Its bootstrap/router selects exactly one gate from current evidence and target depth; its executable gates cover Fog ensure/resume, Business grilling, Functional grilling, Technical grilling, Research, Prototype, reconciliation, target-depth return, and human_steering_required handback.
• Wrapper profiles own audience, target depth, input expectations, presentation policy, and return shape only. Shared wrapper invariants live in Finder-owned references.
• Runtime authority is current provider Fog, child, relation, and immutable evidence state. Graph-authoring records never become runtime workflow state.
• write-backlog has one concise router and progressive single-source references for project context, initialization, Fog intake, three projection stages, reconciliation, Normalization, delivery status, and provider mechanics.
• Business, Functional, and Technical are required stage metadata on one provider-neutral grilling kind.
• The accepted provider hierarchy is Product/Backlog Root → Product Area → Initiative → Epic → Story → required Task, with Fog as lateral provenance.
• backlogProjectUrl changes meaning in place and remains operator-owned through hi ensure; no parallel replacement settings key is introduced.
• Fog completion is derived from production evidence for its accepted resulting scope and is independent of whether a shared Epic remains open.

Accepted Testing Decisions

• Every provider mutation requires exact post-write readback of the applicable identity, hierarchy, membership, milestone, blocker, semantic-field, provenance, and source-link state.
• Finder graph validation must prove deterministic baseline, branch, support-work cycle, reconciliation, human checkpoint, human_steering_required, cold-resume, stale-evidence, contradictory-suggestion, and premature-completion routes.
• Cumulative resume validation must prove accepted lower stages are reused and duplicate Business, Functional, Technical, Story, and Task projections are rejected.
• Task-graph validation must inspect the full reachable dependency graph and reject missing targets, future-iteration edges, self-edges, and cycles.
• Settings migration validation must distinguish a legacy Linear Epic Project URL from a Product/Backlog Root Initiative URL, emit actionable hi ensure guidance, rewrite only the operator-owned destination, and preserve idempotent accepted settings.
• GitHub runtime coverage cannot claim Story-to-Task support until one workflow-created nested Task is read back with exact Project V2, parent, milestone, semantic-field, and blocker state.
• Delivery-state validation must prove start, blocked, pull-request, merge, staging, and production facts remain distinct and that merge does not advance deployment state.

Verification Seams

• Skill invocation metadata proves all Finder surfaces reject implicit model invocation.
• Finder's durable router outcome and provider Fog/child state prove selected target depth, next gate, resume behavior, and terminal conditions.
• write-backlog mutation preview and provider readback prove the final topology and exact written relations.
• hi ensure's public result plus .devpunks/settings.json prove legacy destination migration and settings-only scope.
• Linear Initiative, Project, Issue, milestone, and relation reads prove the native mapping.
• GitHub Projects V2 fields/views plus Issue parent, sub-issue, milestone, and blocker reads prove the configured mapping.
• Linked provider item state and immutable repository/deployment evidence prove delivery transitions and Fog completion.
• Routed wiki content validation proves the compiled specification, glossary, and indexes remain discoverable and structurally valid.

Parked Decisions

• CI/CD pipeline events, pipeline-to-provider automation, release-branch provenance, and automatic shipped-time history. Owner: a future dedicated requirements grill. Resume trigger: an explicit human request to design deployment automation.
• Branch-protection and repository-ruleset enforcement. Owner: a future repository-governance requirements grill. Resume trigger: an explicit human request to include repository governance in project initialization.
• Automatic prioritization and scheduling. Owner: a future product-planning requirements grill. Resume trigger: an explicit human request for capacity-aware scheduling behavior.
• Normalization cadence. Owner: the future operator-policy decision. Resume trigger: a request to automate or schedule Normalization outside the skill.
• Azure DevOps and monday.com support. Owner: a future provider-expansion requirements grill. Resume trigger: either provider becomes an accepted implementation target.

Decision Log