sjames / sjames/syscribe

feat(edit): safe field mutation command (syscribe set) for status/evidence updates

Open
#112 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 narrow, schema-aware syscribe set <id> <field>=<value> command for mutating a small allowlist of existing element fields — starting with status (and quantity fields like evidence: append). Today the only commands that write to an existing element are move, applies-when --set, and scaffold-gherkin --fix; every status transition and evidence addition has to be done by hand-editing YAML frontmatter.

Motivation

Working an LLM-driven implementation loop (agents implementing PlanningItems, then bumping Requirement.status: approved → verified, TestCase.status: approved → active, and appending evidence: blocks on the PlanningItem), every one of those mutations was a raw text edit against frontmatter. That's exactly where an agent-authored typo (status: verifed, a mis-indented evidence: list item, a stray quote) silently corrupts state until the next validate run catches it — if it catches it at all, since a typo'd enum value might not trip any existing rule.

A human editing YAML in an editor gets to eyeball the diff before saving. An agent in a loop often doesn't pause to re-read what it just wrote. Moving field mutation into the tool means the tool can reject the bad value immediately, at the point of the edit, instead of at the next full-model validate.

Proposed CLI

syscribe set <qname|id> status=<value>              # validates against the type's allowed status enum
syscribe set <qname|id> evidence.add ref=<id>        # or evidence.add path=<repo-path>
syscribe set <qname|id> achieves.add <req-id>
  • Rejects an out-of-enum status value immediately (per-type allowed set, e.g. Requirement's draft/review/approved/implemented/verified vs PlanningItem's todo/in_progress/blocked/done).
  • For PlanningItem.status=done: optionally cross-check (or just warn, matching validate's own W002/W305 semantics) that every requirement in achieves: has at least one active/verified TestCase, so setting done prematurely is caught at write time rather than only later, generically, on the next validate.
  • Writes only the changed field(s), preserving field order and surrounding content/comments — same "surgical edit" bar as move's reference rewriting.

Acceptance criteria

  • set <id> status=<invalid-enum-value> is rejected with the allowed value list, no file written
  • set <id> status=<valid-value> writes only that field, byte-identical elsewhere
  • Works by both qualified name and stable ID
  • evidence.add/achieves.add append without disturbing existing list ordering
  • --dry-run prints the would-be diff without writing

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 move, applies-when --set, scaffold-gherkin --fix, and validate command entry points and their YAML editing and schema-validation paths. Define the command's unresolved PlanningItem.status=done warning behavior before implementation. Done means valid status mutations and evidence.add/achieves.add work by qualified name and stable ID, invalid values write nothing, dry-run shows the diff, and unchanged content remains byte-identical.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.