From 05098e40336ffbc3fdf79e3eebf9f168f7afd73d Mon Sep 17 00:00:00 2001 From: gsxdsm Date: Wed, 3 Jun 2026 16:20:32 -0700 Subject: [PATCH] FN-5963: add goals refinement evidence pack Document the evidence required before activating conditional goals refinement work. - add a dedicated goals refinement evidence pack doc with required observation fields and activation thresholds - link the new evidence pack from the docs index and dashboard guide - cover the doc with a dashboard test and keep PR conflict-resolution modal styling aligned after merge Files changed: docs/README.md | 1 + docs/dashboard-guide.md | 2 +- docs/goals-refinement-evidence-pack.md | 74 ++++++++++++++++++++++ .../goals-refinement-evidence-pack-docs.test.ts | 22 +++++++ .../dashboard/app/components/PrCreateModal.css | 6 +- .../dashboard/app/components/PrCreateModal.tsx | 2 +- 6 files changed, 103 insertions(+), 4 deletions(-) Fusion-Task-Id: FN-5963 Fusion-Task-Lineage: 22cefe55-6b1e-4ff7-8fb1-5734f2b5a29b --- docs/README.md | 1 + docs/dashboard-guide.md | 2 +- docs/goals-refinement-evidence-pack.md | 74 +++++++++++++++++++ ...oals-refinement-evidence-pack-docs.test.ts | 22 ++++++ .../app/components/PrCreateModal.css | 6 +- .../app/components/PrCreateModal.tsx | 2 +- 6 files changed, 103 insertions(+), 4 deletions(-) create mode 100644 docs/goals-refinement-evidence-pack.md create mode 100644 packages/dashboard/app/__tests__/goals-refinement-evidence-pack-docs.test.ts diff --git a/docs/README.md b/docs/README.md index ee581eb3a4..3bcf599b15 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,7 @@ For a full walkthrough (installation, onboarding, first task, and daily workflow | [Todo View](./todo-view.md) | Canonical guide for the experimental Todo View, including enablement, usage, API routes, and storage | | [Missions](./missions.md) | Mission hierarchy, planning flow, activation, progress tracking, and autopilot behavior | | [Goals Refinement Gate](./goals-refinement-gate.md) | Evidence gate for activating the conditional post-v1 goals refinement slice only after real usage pain is documented | +| [Goals Refinement Evidence Pack](./goals-refinement-evidence-pack.md) | Structured observation template and two-observation threshold for conditional Slice 4 activation requests | | [Research](./research.md) | Research runs, provider setup, dashboard/CLI usage, findings, exports, and task integration | | [Research View UX Spec](./research-view-ux-spec.md) | Canonical layout and capability-state messaging spec for the Research dashboard view (FN-4138, informs FN-4134/FN-4135) | | [Workflow Steps](./workflow-steps.md) | Reusable quality gates, templates, pre/post-merge phases, and workflow execution results | diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md index 7f8cb05987..15d6c2ec4e 100644 --- a/docs/dashboard-guide.md +++ b/docs/dashboard-guide.md @@ -613,7 +613,7 @@ Inspect task definition, logs, review feedback, comments, documents, workflow ou - In shared task edit/create forms, GitHub Tracking appears at the bottom of **More options**, after **Workflow Steps**. - From this section you can explicitly enable/disable tracking and manage a per-task repo override (`owner/repo`). Clearing the override saves `null` and falls back to project/global defaults. - In `in-review`, pull-request controls/status (including stall badges) are in a dedicated **Pull Request** tab instead of the Definition tab. -- The **Create Pull Request** modal now offers in-app remediation for every blocking preflight check. If `branchOnRemote` is false, use **Push branch to remote** and Fusion will publish `fusion/` to `origin` and refresh preflight. If `conflictsWithBase` is true, use **Resolve conflicts with AI** and Fusion will resolve merge markers on the task branch, commit the result, push the branch, and refresh preflight so normal PR creation can continue once all checks pass. +- The **Create Pull Request** modal now offers in-app remediation for blocking preflight checks. If `branchOnRemote` is false, use **Push branch to remote** and Fusion will publish `fusion/` to `origin` and refresh preflight. If `conflictsWithBase` is true, use **Resolve conflicts with AI** and Fusion will use an AI coding agent to resolve merge markers on the task branch, commit the result, push the branch, and refresh preflight so normal PR creation can continue once all checks pass. - The **Review** tab is separate from **Comments**: Review shows actionable PR/reviewer feedback and same-task revision controls, while Comments remains the general collaboration thread. - **Request revision** in Review resumes work on the same task ID (no refinement task): `in-progress` tasks get steering injection, while `in-review` tasks are moved back to `in-progress` for the same branch/worktree revision pass. - Review supports a manual **Refresh** action in-place: PR mode pulls latest GitHub review state/decision, while direct mode rehydrates reviewer-agent feedback from persisted task data (no GitHub call). diff --git a/docs/goals-refinement-evidence-pack.md b/docs/goals-refinement-evidence-pack.md new file mode 100644 index 0000000000..df2f74f8ec --- /dev/null +++ b/docs/goals-refinement-evidence-pack.md @@ -0,0 +1,74 @@ +# Goals Refinement Evidence Pack + +[← Docs index](./README.md) + +This document defines the structured evidence pack contributors must fill out before recommending activation of **Slice 4: Schema/Focus-Set Refinement (Conditional)** in the Goals mission (`M-MP32KU9Y-0001-2ADN`). It standardizes how real-use pain is recorded; it is not an implementation plan and does not authorize Slice 4 work by itself. + +## Purpose + +The Goals mission guardrails intentionally keep v1 simple until real usage proves otherwise. This evidence pack exists so that when pain does appear, contributors capture it consistently and make any activation recommendation from observed evidence rather than speculation. + +## Locked guardrails carried forward from the mission + +Every observation collected here must be interpreted within the mission guardrails already locked by CEO + CTO + PM: + +1. **Hard cap of 5 active goals** remains the v1 operating limit unless real use proves that cap is too restrictive. +2. **Success metrics live in slice/feature text for v1** rather than a structured `successMetric` schema unless real use shows that free text is insufficient. +3. **Only Slice 1 was activated up front**; later slices were intentionally not pre-approved. +4. Slice 4 is conditional follow-up work, not an automatic continuation of the Goals rollout. + +These guardrails mean the evidence pack cannot be used to justify speculative implementation. + +## Required evidence fields for each observation + +Record each real-use observation as its own copy of the template below. + +```md +### Observation : +- **Observed pain:** +- **Frequency:** +- **Impacted workflow:** +- **Reproduction artifacts:** +- **Why this is independent:** +``` + +### Field interpretation notes + +- **Observed pain** must describe a real breakdown, not a hypothetical improvement idea. +- **Frequency** should be concrete enough to distinguish one-off friction from recurring pain. +- **Impacted workflow** should identify where the current v1 design is failing in practice. +- **Reproduction artifacts** should give reviewers enough evidence to inspect the incident directly. +- **Why this is independent** is required because the activation threshold depends on distinct observations. + +## Activation threshold + +An activation recommendation for Slice 4 requires **at least two independent real-use observations**. + +**Independent** means the observations come from distinct sessions, workflows, or incidents. Two notes describing the same underlying event do **not** satisfy the threshold. + +The observations may point to the same refinement direction, but they must still represent separate evidence from real use. + +## Unmet-threshold rule + +If the evidence pack does **not** contain at least two independent real-use observations, **Slice 4 remains pending and no implementation tasks are created**. + +This evidence pack feeds the activation rule defined in [Goals Refinement Gate](./goals-refinement-gate.md). That gate is the artifact that decides whether Slice 4 may start. Candidate directions that an observation may point toward are maintained separately in the FN-5962 conditional refinement options backlog; this evidence pack should cite those options rather than duplicate or pre-approve them. + +## How to use this template + +1. Add one observation block per real-use incident. +2. Confirm each block includes all required fields. +3. Check whether at least two observations are truly independent. +4. If the threshold is met, prepare a written rationale under the [Goals Refinement Gate](./goals-refinement-gate.md) naming the observed pain and the candidate refinement direction. +5. If the threshold is not met, stop: Slice 4 stays pending and no schema, focus-set, or reporting implementation work should begin. + +## Decision rule summary + +Before recommending Slice 4 activation, confirm all of the following: + +- Each observation includes **observed pain**, **frequency**, **impacted workflow**, and **reproduction artifacts**. +- The pack contains **at least two independent real-use observations**. +- The observations are grounded in the locked v1 guardrails rather than speculative product expansion. +- The final recommendation cites the [Goals Refinement Gate](./goals-refinement-gate.md) and points only to candidate directions tracked in FN-5962. + +If any condition is missing, do not recommend activation. diff --git a/packages/dashboard/app/__tests__/goals-refinement-evidence-pack-docs.test.ts b/packages/dashboard/app/__tests__/goals-refinement-evidence-pack-docs.test.ts new file mode 100644 index 0000000000..1c19c5816c --- /dev/null +++ b/packages/dashboard/app/__tests__/goals-refinement-evidence-pack-docs.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from "vitest"; +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +describe("Goals refinement evidence pack documentation", () => { + it("documents the required evidence fields, activation threshold, and unmet-threshold rule", () => { + const doc = readFileSync( + resolve(__dirname, "../../../../docs/goals-refinement-evidence-pack.md"), + "utf-8", + ); + + expect(doc).toContain("**Observed pain:**"); + expect(doc).toContain("**Frequency:**"); + expect(doc).toContain("**Impacted workflow:**"); + expect(doc).toContain("**Reproduction artifacts:**"); + + expect(doc).toContain("at least two independent real-use observations"); + expect(doc).toContain( + "Slice 4 remains pending and no implementation tasks are created", + ); + }); +}); diff --git a/packages/dashboard/app/components/PrCreateModal.css b/packages/dashboard/app/components/PrCreateModal.css index a15b107731..30151e1e77 100644 --- a/packages/dashboard/app/components/PrCreateModal.css +++ b/packages/dashboard/app/components/PrCreateModal.css @@ -80,7 +80,8 @@ gap: var(--space-sm); } -.pr-create-modal__preflight-remediation { +.pr-create-modal__preflight-remediation, +.pr-create-modal__conflict-resolution { display: flex; align-items: center; justify-content: space-between; @@ -276,7 +277,8 @@ .pr-create-modal__grid-two, .pr-create-modal__commit-row, .pr-create-modal__file-row, - .pr-create-modal__preflight-remediation { + .pr-create-modal__preflight-remediation, + .pr-create-modal__conflict-resolution { display: flex; flex-direction: column; align-items: flex-start; diff --git a/packages/dashboard/app/components/PrCreateModal.tsx b/packages/dashboard/app/components/PrCreateModal.tsx index 01a00d1c47..ef71e62731 100644 --- a/packages/dashboard/app/components/PrCreateModal.tsx +++ b/packages/dashboard/app/components/PrCreateModal.tsx @@ -421,7 +421,7 @@ export function PrCreateModal({ ) : null} {preflight?.conflictsWithBase ? ( -
+

Resolve conflicts with AI

Fusion will use AI to resolve conflicts on this branch and push it.