Align ways-of-working guidance with the issue model

[MariusStorhaug]

The new issue model changes assumptions currently repeated across workflow, readiness, branching, goal-setting, specification, pull-request, agent-workflow-stage, and orchestration guidance. Those pages must agree that aggregate issues plan and track while delivery leaves build and ship.

Request

Update every affected Ways of Working and agent-facing page to consume the canonical OKF issue guidance without restating it. Ensure phases, readiness, closure, pull-request linking, stacked-work dependencies, and indexes-first workflow discovery reflect native issue types and relationships.

Acceptance criteria

• Workflow sends only Task/Bug delivery leaves into Build; Epic/PBI decompose and aggregate
• Definition of Ready and Done defines level-appropriate gates for aggregate versus leaf issues
• Branching and Merging uses native issue dependencies rather than textual Blocked by conventions
• PR Format closes exactly one Task/Bug and references parent PBI/Epic without closing keywords
• Goal Setting clarifies the Mission → OKR → Initiative → Epic boundary and the issue-type strategy above Epic
• Spec-Driven Development uses the canonical Epic/PBI/Task/Bug terminology and links to the new pages
• Contribution Workflow, Documentation Model, Fleet Orchestration, and Agent Workflow stage pages use the new paths and semantics
• Workflow is the canonical process entry; the Agents index only routes to stage procedures
• Discovery follows AGENTS.md -> docs root -> Ways of Working -> Workflow -> inferred stage; explicit task keywords may shortcut to a stage without creating another process definition
• No page redefines body structures, hierarchy, or relationship semantics owned by the Issues section
• Index check, links, lint, clean build, CI, and Copilot review are green

---

Technical decisions

Reference, do not restate: The Issues section owns the model. Other pages state only their local consequence and link to the canonical page.

Leaf pull requests: A pull request closes its Task/Bug delivery issue. PBI/Epic links are contextual and non-closing.

Native dependencies: Stacked pull requests mirror issue dependency edges; list order and prose do not create execution gates.

Agent workflow stages: src/docs/Agents/ describes stages and handoffs in one shared workflow, not standalone agent roles or personas. Bootstrap and framework guidance use the same model.

Indexes-first discovery: Workflow.md owns process progression and stage selection. Root and section indexes lead to it; Agents/index.md, skills, instruction files, agent definitions, and repository pointers only route to stage procedures and never copy the workflow.

---

Implementation plan

Workflow alignment

• Update workflow, readiness/done, branching, PR, goal-setting, and spec-driven pages
• Update contribution, documentation-model, orchestration, and Agent Workflow stage consumers
• Make Workflow canonical and align indexes-first stage discovery without duplicate process definitions
• Remove duplicated legacy terminology and textual relationship conventions

Validation

• Search the full documentation tree for stale paths and semantics
• Run documentation checks, CI, and the Copilot review loop

[MariusStorhaug]

Baseline audit at live origin/main f156c3658969b03250c8af79a452649106aa5df3 (the merged Types/Process result from #94).

Native graph confirmed: #86 is a Task under #84, blocked by closed #87 and #88, and blocks open #90. No metadata migration is part of this task.

The canonical Ways-of-Working/Issues/ pages already own type hierarchy and bodies, planning/lifecycle, and native containment/dependency semantics. Consumer drift found before editing:

• Workflow.md routes generic simple tasks, sub-issues, and checklists directly into Build and cites obsolete numbered body sections.
• Definition-of-Ready-and-Done.md has one leaf-only readiness/done gate and does not cover Epic/PBI aggregation or the audited operational Task path.
• Branching-and-Merging.md records stack order with textual Blocked by: #N instead of native dependencies.
• PR-Format.md permits arbitrary closing links rather than exactly one Task/Bug; parent context is not distinguished from closure.
• Goal-Setting.md compresses the Initiative/Epic boundary into a one-to-one mapping.
• Spec-Driven-Development.md uses generic Tasks and the legacy epic -> item -> task ladder.
• Contribution-Workflow.md does not restrict repository delivery to Task/Bug leaves.
• Documentation-Model.md points generically at Issue Format rather than the canonical planning ownership boundary.
• Fleet-Orchestration.md treats a PR alone or optional tracking issue as a campaign work item and duplicates closure semantics.
• Agents/define.md, Agents/implement.md, and Agents/reviewer.md assume a universal three-section Task contract or generic issue delivery rather than routing by native type and altitude.

No stale pre-OKF file paths were found; current links already target Issues/Process/ and Issues/Types/. The implementation will change only local consumer consequences and link back to canonical owners rather than copy their definitions.

[MariusStorhaug]

Implementation and validation audit complete.

• Pull request: 📖 [Docs]: Ways of working now follows the canonical issue model #97
• Exact base: f156c3658969b03250c8af79a452649106aa5df3
• Exact head: eab23ca5a549b9f867e42bd5110fc6446a921c64
• Commits: 9010e39, a840def, 3f78fbd, 133ad22, eab23ca
• Scope: 20 documentation files across Workflow, readiness/done, branching, PR format, goal setting, spec-driven development, contribution, documentation model, fleet orchestration, worktrees, review guidance, agent roles, indexes, repository defaults, and downstream release propagation.
• Full-tree searches found no stale pre-OKF paths. Obsolete numbered body-section references, manual dependency conventions, generic work-item/tracking-issue exceptions, and PR-without-delivery-issue semantics were removed from affected consumers. Unrelated release Feature terminology and metadata migration were left unchanged.
• Local validation: documentation index update and check, full link validation, clean Zensical build, git diff --check, and all 14 Pester tests passed.
• PR CI at the exact head: Links, Build, Lint, and every reported linter context passed; Publish correctly skipped for the PR.
• Copilot review: two feedback rounds produced three valid comments, all fixed, replied to, and resolved. The fresh exact-head round at eab23ca reviewed all 20 files with zero new comments.
• PR state: ready for review, only NoRelease, assigned to MariusStorhaug, squash auto-merge enabled, still open and blocked on the required independent code-owner/last-push approval.

No live issue metadata was changed and no metadata-migration finding was discovered; #90 remains outside this pull request.

[MariusStorhaug]

Correction applied from review: agent guidance is now framed as one shared workflow rather than a catalog of standalone roles.

• Agents/index.md now defines the process and its transitions: Define -> Implement -> Review, with changes returning to Implement and Security Review as a specialized path.
• Each agent page now identifies its workflow stage, entry condition, boundary, and handoff.
• Workflow maintenance is explicitly outside delivery and owns the stage descriptions and thin repository pointers.
• Navigation, generated indexes, Agentic Development guidance, framework docs, memory-template terminology, and Fleet Orchestration now consume the same workflow-stage model.

Commit: a71bd38. The PR is draft again while exact-head CI and Copilot review rerun.

[MariusStorhaug]

Agent-workflow correction is fully revalidated at exact head a71bd387c0b36d3b9ec74b86855c87fce4b7da1f.

• Documentation index check and full link validation passed.
• Clean Zensical build passed.
• All 14 Pester tests passed.
• Exact-head PR Links, Build, Lint, and all reported linter contexts passed.
• Fresh exact-head Copilot review returned zero comments.

The PR can return to ready status with squash auto-merge; independent approval remains the only merge gate.

[MariusStorhaug]

Expanded exact-worktree audit follow-up completed in 9ae0d89.

Removed the final directly coupled stale role/persona framing from:

• Ways-of-Working/Principles/AI-First-Development.md (One workflow, not a swarm; shared stages and specialized review paths),
• bootstrap/README.md, and
• bootstrap/AGENTS.template.md.

A repository-wide boundary-aware search for agent role(s), roles agents play, specialized roles, persona, role descriptions, and per-agent-role returns no matches. Local index update/check, full links, clean build, and all 14 Pester tests pass. PR #97 remains draft with auto-merge disabled while exact-head CI and explicit Copilot review run.