sjames / sjames/syscribe

feat(validate): PlanningItem-scoped completion check — done requires achieves evidence

Open
#114 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Rust
Stars
7
Forks
1
Avg merge
21m
Merged PRs (30d)
2

Description

Summary

Add a validation rule scoped specifically to PlanningItem.status: done versus the verification state of the requirements it claims to achieves: — not just the model-wide, Requirement-centric W002 ("approved requirement has no active TestCase") / W305 ("parent requirement has no active system integration TestCase"), but a check that fires from the PlanningItem's own perspective: "this PlanningItem is done, but requirement X in its achieves: list has no active/verified TestCase."

Motivation

W002/W305 already exist and would, in principle, have caught the underlying gap — but they're independent, per-Requirement warnings that show up in the general noise of a validate run (this model currently has 33+ pre-existing W002/W305 warnings from unrelated, still-open work). Nothing ties "this specific PlanningItem you're about to mark done" to "here specifically are the achieves-requirements that aren't actually backed by evidence yet." That distinction matters most exactly when it's needed most: right before an agent (or a human) commits a PlanningItem as finished.

Concretely: a PlanningItem's implementing agent can be interrupted mid-task (session limit, crash, disconnect) having done real work but not finished verification. If whoever picks it back up marks it done without independently reasoning about every achieves: entry's TestCase status — which is easy to skip under time pressure — nothing today says "wait, one of the things this claims to achieve isn't actually verified." A purpose-built check closes that gap mechanically instead of relying on someone remembering to cross-reference achieves: against who-verifies by hand.

Proposed rule (new code, e.g. W309)

W309  PlanningItem '<id>' is 'done', but achieves '<REQ-id>' whose only
      TestCase(s) are still 'approved' (not active/verified)
  • Fires per (PlanningItem, Requirement) pair, not once per Requirement — so it's actionable from the PlanningItem you're looking at, not lost in the general Requirement-status warning list.
  • Natural fit for --profile: a project could define a [profiles.pi-done] that promotes W309 to a gate failure, and run it as a pre-commit check specifically when closing out a PlanningItem (syscribe validate --profile pi-done), distinct from the full-model gate used elsewhere.

Acceptance criteria

  • Fires for a done PlanningItem with an achieves: requirement whose TestCase(s) are all below active
  • Does not fire for todo/in_progress/blocked PlanningItems (those already have no completion claim to check)
  • Does not duplicate as a second, unrelated finding when W002 already fires for the same Requirement — either suppress the redundant one or clearly cross-reference
  • Shows up in --json output with both the PlanningItem id and the Requirement id, so tooling can filter on either

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing W002 and W305 validation rules and the validate command's --json and --profile handling. Add the proposed W309 check for each done PlanningItem and its achieves requirements, then verify the acceptance cases: status filtering, duplicate handling, and both IDs in JSON output.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.