docs: OpenSpec for task status workflow by johnmcollier · Pull Request #7 · rhdh-parasol/node-api

johnmcollier · 2026-08-21T15:50:02Z

Summary

Adds a typical small-app OpenSpec change — not implemented — so we can dogfood /fs-grillme on this playground.

The sample API today is an in-memory task store with a boolean completed flag. A natural next feature is a status workflow (todo → in_progress / blocked / done / cancelled) plus GET /tasks?status= filtering.

What a typical OpenSpec looks like here

This repo is not RHDH, so this is the lightweight spec-driven layout (proposal / design / spec / tasks), not the rhdh-spec-driven schema with PRDs, journals, and showboat demos.

openspec/config.yaml
openspec/changes/task-status-workflow/
  .openspec.yaml
  proposal.md      why, what, non-goals, impact
  design.md        decisions, trade-offs, open questions
  tasks.md         implementation checklist (unchecked)
  specs/task-status/spec.md   ADDED requirements + scenarios

Intentionally left a few decision gaps for grilling:

cancelled vs DELETE (two ways to dismiss a task)
Dual completed + status on PATCH, including completed: false on a blocked task
Whether unfiltered GET /tasks should hide cancelled

No src/ changes in this PR.

Test plan

Comment /fs-grillme on this PR
Confirm inline review comments land on the OpenSpec files
Reply to a thread, run /fs-grillme again

Made with Cursor

Proposal-only change (no implementation) so /fs-grillme can be exercised against a typical small-app OpenSpec: status enum, list filter, and a few still-open decisions around cancelled vs delete and the legacy completed flag. Co-authored-by: Cursor <cursoragent@cursor.com>

fullsend-ai-review · 2026-08-21T15:51:20Z

🤖 Finished Review · ✅ Success · Started 3:51 PM UTC · Completed 4:05 PM UTC

Commit: b2f6a1b · View workflow run →

fullsend-ai-review · 2026-08-21T16:05:05Z

Review

Findings

Medium

[internal-inconsistency] openspec/changes/task-status-workflow/specs/task-status/spec.md:41 — The spec commits to a definitive behavior for PATCH {"completed": false} (mapping to status: "todo"), but design.md (Open Questions section) and tasks.md (task 1.4) both mark this same behavior as provisional/open. If a developer implements from the spec they will treat this as settled; if they read the design doc they will see it is still an open question. One document should not present as decided what another presents as open.
Remediation: Either close the open question in design.md and remove the provisional note in tasks.md 1.4, or add a note to the spec scenario ("Unmark done via legacy completed flag") indicating this behavior is provisional and subject to the open question in design.md.
[edge-case-gap] openspec/changes/task-status-workflow/specs/task-status/spec.md:7 — The spec defines completed-to-status mapping rules and conflict resolution exclusively for PATCH updates, but says nothing about POST creates. Missing scenarios: (1) POST with completed: true and no status, (2) POST with both status and completed in conflict, and (3) POST with status: "done" verifying completed: true.
Remediation: Add scenarios to the spec covering these three POST edge cases.

Low

[missing-authorization] — This PR has no linked tracking issue. For a specification-only, non-code PR in a playground/dogfooding repo, this is a minor process gap rather than an authorization concern.
[scope-creep] openspec/config.yaml — This PR bundles framework bootstrap (config.yaml) with a specific feature proposal (changes/task-status-workflow/). In a playground repo this is pragmatic; in a production codebase these would warrant separate PRs.

Previous run

Review

Findings

Medium

[internal-consistency] openspec/changes/task-status-workflow/design.md:94 — Decision 2 definitively states that { "completed": false } is treated as { "status": "todo" }, but the Open Questions section asks whether todo is the right fallback when completed: false is PATCHed on a blocked task. This is a genuine tension: an implementer following Decision 2 would hardcode false → todo, while the open question signals that mapping may be wrong for certain states.
Remediation: Either qualify Decision 2 with "unless revisited per the open question below" or remove the open question and commit to todo as the fallback.
[edge-case] openspec/changes/task-status-workflow/specs/task-status/spec.md:37 — The spec has a scenario for completed: true → status: "done" but no scenario for the reverse (completed: false). Design Decision 2 and task 1.4 both define this mapping, so the spec should have a corresponding scenario — especially since the design's open question casts doubt on the todo fallback.
Remediation: Add a scenario: "Unmark done via legacy completed flag — WHEN PATCH with {"completed": false} THEN status is "todo" and completed is false."
[edge-case] openspec/changes/task-status-workflow/specs/task-status/spec.md — No scenario or task covers the conflict case where both status and completed are sent in the same PATCH and disagree. Design.md identifies this as a risk and proposes status wins, but neither the spec nor tasks.md codifies that rule.
Remediation: Add a spec scenario for {"status": "blocked", "completed": true} and a test task in tasks.md.

Low

[edge-case] openspec/changes/task-status-workflow/specs/task-status/spec.md — The spec covers invalid status on POST (create) and GET (filter) but not on PATCH. Task 1.2 mentions rejecting unknown status in both create and update, but the spec should make the PATCH contract explicit.
Remediation: Add a scenario: "Update with invalid status is rejected — WHEN PATCH with {"status": "donezo"} THEN 400."
[missing-authorization] — This PR introduces a new top-level openspec/ directory with no linked issue. CONTRIBUTING.md uses permissive language ("If a related issue exists, link it"), and the PR body explains the intent, but a linked issue would improve traceability for this structural addition.
Remediation: Consider creating an issue describing the intent to adopt OpenSpec.

Labels: PR adds only documentation/specification files under openspec/

johnmcollier · 2026-08-21T16:46:08Z

/fs-grillme

johnmcollier · 2026-08-21T17:28:00Z

/fs-grillme

fullsend-ai-review · 2026-08-21T17:29:26Z

🤖 Finished Grillme · ✅ Success · Started 5:29 PM UTC · Completed 5:32 PM UTC

Commit: b2f6a1b · View workflow run →

johnmcollier · 2026-08-21T19:21:43Z

/fs-grillme

fullsend-ai-review · 2026-08-21T19:23:16Z

🤖 Finished Grillme · ✅ Success · Started 7:23 PM UTC · Completed 7:26 PM UTC

Commit: b2f6a1b · View workflow run →

fullsend-ai-review · 2026-08-21T19:26:54Z

Now I have everything I need. Let me analyze the diff and formulate the grillme output.

Summary of the PR:

PR fix(grillme): require a recommended answer on inline questions #9 modifies the grillme agent prompt (.fullsend/custom/agents/grillme.md) and the grilling skill (.fullsend/custom/skills/grilling/SKILL.md) to require every inline question to include a **Recommended:** line with the agent's preferred answer and rationale.
Motivation: PR docs: OpenSpec for task status workflow #7's grillme session asked good questions but never took a stance, unlike the original one-question model.
No prior grillme threads exist on this PR (first turn).

Here is my output:

🔥 Grillme — Turn 1

Reviewing this PR for design decisions and architectural alignment.
4 questions pinned to the diff below.

Reply to each inline comment with your decision, then run /fs-grillme
to continue.

_{Reply to inline comments, then run /fs-grillme to continue · Run logs}

johnmcollier · 2026-08-21T19:42:19Z

/fs-grillme

fullsend-ai-review · 2026-08-21T19:43:49Z

🤖 Finished Grillme · ✅ Success · Started 7:43 PM UTC · Completed 7:47 PM UTC

Commit: b2f6a1b · View workflow run →

johnmcollier · 2026-08-21T19:48:36Z

/fs-grillme

fullsend-ai-review · 2026-08-21T19:50:02Z

🤖 Finished Grillme · ✅ Success · Started 7:50 PM UTC · Completed 7:55 PM UTC

Commit: b2f6a1b · View workflow run →

johnmcollier · 2026-08-21T19:59:33Z

/fs-grillme

fullsend-ai-review · 2026-08-21T20:01:10Z

🤖 Finished Grillme · ✅ Success · Started 8:01 PM UTC · Completed 8:04 PM UTC

Commit: b2f6a1b · View workflow run →

johnmcollier · 2026-08-21T20:08:26Z

/fs-grillme

fullsend-ai-review · 2026-08-21T20:09:50Z

🤖 Finished Grillme · ✅ Success · Started 8:09 PM UTC · Completed 8:13 PM UTC

Commit: b2f6a1b · View workflow run →

johnmcollier · 2026-08-21T20:15:56Z

/fs-grillme

fullsend-ai-review · 2026-08-21T20:17:35Z

🤖 Finished Grillme · ✅ Success · Started 8:17 PM UTC · Completed 8:20 PM UTC

Commit: b2f6a1b · View workflow run →

fullsend-ai-review · 2026-08-21T20:20:44Z

🔥 Grillme — Session Complete

All 11 threads resolved across 3 turns.

Decisions reached:

Decision 2 provisional: completed: false → status: "todo" mapping marked as provisional until the open question about restoring previous non-done status is resolved. Task 1.4 gets a matching note.
Conflict resolution promoted to Decision: When both status and completed are present on PATCH, status wins. A spec scenario for the conflict case (status: "blocked" + completed: true) to be added.
Unfiltered GET includes cancelled: Open question closed — GET /tasks returns all statuses including cancelled. Promoted from implicit spec scenario to explicit Decision in design.md.
Soft-delete non-goal reframed: The non-goal reworded to acknowledge that cancelled is functionally soft-delete; the non-goal is about not having a separate soft-delete endpoint.
completed kept indefinitely: No deprecation timeline — service is dev preview, dual-field is acceptable.
updatedAt explicitly deferred: Added to Non-Goals with a one-liner rather than left as an implicit omission.
STATUSES single source of truth: Exported from the store module; HTTP layer imports it.
PATCH invalid status scenario added to spec: Symmetric with the create rejection scenario.
Options-object signature for create(): Switching from positional create(title, description) to create({ title, description, status }).
Docs task added: ## 4. Docs section in tasks.md for README endpoint table updates.
Typed ValidationError: Store throws ValidationError; HTTP layer catches it separately from SyntaxError instead of misclassifying as "invalid JSON."

Remaining gaps:

completed: false on a non-done task (e.g., blocked): intentionally left as an open question with the provisional fallback to todo. This is a deliberate deferral, not a gap.

Suggested next step: Apply the agreed changes to the OpenSpec documents in this PR (add provisional qualifiers, promote decisions, add spec scenarios, add docs task section), then /fs-fix or manual edit.

_{Start a new session with /fs-grillme · Run logs}

johnmcollier · 2026-08-21T20:22:28Z

/fs-fix apply fullsend grill me results

fullsend-ai-coder · 2026-08-21T20:23:36Z

🤖 Finished Fix · ✅ Success · Started 8:23 PM UTC · Completed 8:29 PM UTC

Commit: b2f6a1b · View workflow run →

design.md: - Reframe soft-delete non-goal to distinguish cancelled status from soft-delete endpoint - Add updatedAt to Non-Goals as explicit deferral - Mark Decision 2 completed:false→todo mapping as provisional - Promote conflict resolution (status wins over completed) to Decision 5 - Promote unfiltered GET returns all statuses to Decision 6 - Remove resolved open questions (cancelled in GET, updatedAt) specs/task-status/spec.md: - Add scenario for completed:false → status:todo mapping - Add scenario for PATCH with invalid status → 400 - Add scenario for status/completed conflict resolution tasks.md: - Specify options-object signature for TaskStore.create - Specify ValidationError for store validation (not sentinel) - Specify STATUSES exported from store as single source of truth - Add task 1.5 for status/completed conflict handling - Add provisional note to task 1.4 - Add test 3.5 for conflict case - Add section 4 (Docs) with README update task Addresses review feedback on #7

fullsend-ai-coder · 2026-08-21T20:29:01Z

🔧 Fix agent — iteration 1 (human-triggered)

Applied 14 grillme-resolved decisions across 3 OpenSpec files (design.md, spec.md, tasks.md). Changes include: reframing the soft-delete non-goal, adding updatedAt to Non-Goals, marking Decision 2 as provisional, promoting conflict resolution and unfiltered-GET-returns-all to formal Decisions (5 and 6), adding 3 new spec scenarios (completed:false, invalid PATCH status, status/completed conflict), and updating tasks.md with options-object signature, ValidationError, STATUSES export, conflict task, provisional note, new test, and docs section. One finding (completed deprecation timeline) was declined by the engineer.

Fixed (14):

Reframe soft-delete non-goal (openspec/changes/task-status-workflow/design.md): Reworded non-goal from 'Soft-delete; DELETE remains hard-delete' to clarify that cancelled is a status, not a soft-delete mechanism, per engineer agreement
Add updatedAt explicit deferral to Non-Goals (openspec/changes/task-status-workflow/design.md): Added updatedAt to Non-Goals with one-liner explaining no timestamp tracking beyond createdAt in this change, per engineer agreement
Mark Decision 2 completed:false mapping as provisional (openspec/changes/task-status-workflow/design.md): Added '(provisional — see open question below)' qualifier to Decision 2's completed:false to todo mapping, since the open question about fallback for blocked tasks is still unresolved
Promote conflict resolution rule to Decision 5 (openspec/changes/task-status-workflow/design.md): Moved the status-wins-over-completed conflict resolution from a Risks/Trade-offs proposal to Decision 5, per engineer agreement
Promote unfiltered GET returns all statuses to Decision 6 (openspec/changes/task-status-workflow/design.md): Closed the open question about cancelled in unfiltered GET by promoting it to Decision 6, per engineer agreement
Add completed:false spec scenario (openspec/changes/task-status-workflow/specs/task-status/spec.md): Added 'Unmark done via legacy completed flag' scenario: PATCH with completed:false maps to status:todo, covering the reverse mapping that was missing
Add PATCH invalid status spec scenario (openspec/changes/task-status-workflow/specs/task-status/spec.md): Added 'Update with invalid status is rejected' scenario: PATCH with invalid status returns 400, per engineer agreement
Add status/completed conflict spec scenario (openspec/changes/task-status-workflow/specs/task-status/spec.md): Added 'Conflict between status and completed' scenario: PATCH with both status:blocked and completed:true results in status winning, per engineer agreement
Specify options-object signature for create (openspec/changes/task-status-workflow/tasks.md): Updated task 1.1 to specify switching TaskStore.create to an options-object signature, per engineer agreement
Specify ValidationError for store validation (openspec/changes/task-status-workflow/tasks.md): Updated task 1.2 to specify throwing ValidationError instead of ambiguous throw-or-sentinel, and updated task 2.3 to catch ValidationError distinctly from SyntaxError, per engineer agreement
Export STATUSES as single source of truth (openspec/changes/task-status-workflow/tasks.md): Updated task 1.1 to export STATUSES from the store and task 2.2 to import it for HTTP validation, per engineer agreement
Add task 1.5 for status/completed conflict handling (openspec/changes/task-status-workflow/tasks.md): Added new task 1.5 for status-wins-over-completed conflict handling, renumbered list filter to 1.6
Add provisional note to task 1.4 (openspec/changes/task-status-workflow/tasks.md): Added provisional note to task 1.4 so implementers know the false-to-todo mapping may change
Add test 3.5 and docs section 4 (openspec/changes/task-status-workflow/tasks.md): Added test 3.5 for conflict case and new section 4 (Docs) with task 4.1 to update README endpoints table, per engineer agreement

Disagreed (1):

completed deprecation timeline: Engineer explicitly declined: the service is still dev preview, so a deprecation timeline is not needed yet. No change made to proposal.md.

Tests: passed

Next steps:

/fs-review — request a re-review of the changes
/fs-fix <your instruction> — run another fix pass with specific guidance
Push commits directly — review re-runs automatically on push
_{Updated by fullsend fix agent}

fullsend-ai-review · 2026-08-21T20:30:15Z

🤖 Finished Review · ✅ Success · Started 8:30 PM UTC · Completed 8:43 PM UTC

Commit: 8cae49c · View workflow run →

This comment was marked as outdated.

Sign in to view

fullsend-ai-review Bot added requires-manual-review Review requires human judgment documentation Improvements or additions to documentation labels Aug 21, 2026

johnmcollier mentioned this pull request Aug 21, 2026

fix(grillme): vendor gcp-vertex.env for BYOA overlay gap #8

Merged

3 tasks

This comment was marked as outdated.

Sign in to view

johnmcollier mentioned this pull request Aug 21, 2026

fix(grillme): require a recommended answer on inline questions #9

Merged

3 tasks

johnmcollier mentioned this pull request Aug 21, 2026

fix(grillme): pin each turn to the triggering PR #10

Merged

4 tasks

This comment was marked as outdated.

Sign in to view

Conversation

johnmcollier commented Aug 21, 2026

Summary

What a typical OpenSpec looks like here

Test plan

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review

Findings

Medium

Low

Review

Findings

Medium

Low

Uh oh!

This comment was marked as outdated.

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026

🔥 Grillme — Turn 1

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026

🔥 Grillme — Session Complete

Uh oh!

johnmcollier commented Aug 21, 2026

Uh oh!

fullsend-ai-coder Bot commented Aug 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-coder Bot commented Aug 21, 2026 •

edited

Loading

fullsend-ai-review Bot commented Aug 21, 2026 •

edited

Loading