Make handoff items machine-readable and remove Item::TAG #924

New issue

Open

opened 2026-10-03 13:20:08 +00:00 by jared · 1 comment

jared commented

2026-10-03 13:20:08 +00:00

Owner

Problem

Jared ruled on closed ticket #906 on 2026-10-03 and called the shipped approach "flimsy".
Handoff items entries are YAML strings that hold several fields as prose, and Commit::Item reads a path out of that prose with a regex.
The handoff container is already YAML; the defect is that one string holds several fields.
Jared's rule: the default is a machine-readable format (YAML or JSON, by context). Use prose only when a human reads it, or when prose serves an AI consumer better than a structured format.
He suspects YAML fits the template that the refactorer gets, and that structured items make the parsing, the object creation, and the actions clearer. A machine-readable format hardens the connection between the agent and the codebase.
This ticket needs a design ruling from Jared.

Observed

plugins/os-sdlc/lib/os_sdlc/parser/implementation/commit/item.rb:7 defines TAG = /\A[a-z_]+:\s*/, and line 23 strips it: @entry.strip.sub(TAG, "").split(/\s/).first.to_s.gsub(DECORATION, "").
Before #906 (commit 04fbc824) the refactorer wrote items as CHANGE: <path> :: <prose>.
Judge agents write tagged items: plugins/os-sdlc/agents/test-reviewer.md:33 TEST: <path> :: <test name>., and contract-auditor.md:30 and behavior-verifier.md:27 ("a list mixing these prefixes").
#906 changed only plugins/os-sdlc/agents/refactorer.md:46 to plain paths ("one plain repository-relative path per entry, with no tag").
The parser kept the lowercase TAG.
plugins/os-sdlc/tests/command/implementation/commit_test.rb:163 still pins items: ["modified: lib/widget.rb -- extracted the row reader"]; the #906 prediction says no agent writes that format.
plugins/os-sdlc/tests/parser/implementation/commit/item_test.rb:14 checks paths with path.match?(%r{\A[\w-]+(/[\w.-]+)*\.\w+\z}).

Reproduce

n/a: design ticket; the format gap is visible by reading the files above.

Approach

Decide the item structure for every agent handoff template, then change parser, templates, and tests together.

Choose the item structure for every agent's handoff template (for example a mapping with path and a kind or note field) and name which agents keep prose items because a human or AI reads them.
Remove Item::TAG and the modified: test at commit_test.rb:163.
Decide which ADRs apply and whether new ones are required: ADR-0171 decision 2 (items are "prose-shaped in judge agents", parsed strictly; it needs an amending ADR), ADR-0135 (handoff contract), ADR-0159 (handoff item kinds: creates, expect-new). Run os-adr:find before work starts. No Accepted ADR may be reversed silently.
Second note from Jared: item_test.rb:14 checks paths with a regex. Does Pathname or a simpler assertion fit? Pathname.new("CHANGE:") is also a valid Pathname, so Pathname alone cannot reject a tag. An equality assertion against the expected paths is one alternative.

Required work: none beyond the acceptance criteria.

Acceptance criteria

Given a ruling on the item structure, when the ticket is made ready-for-agent, then it lists the structure for each agent template.
Given the ruling, when the work ships, then no regex reads a path out of an item string and TAG is absent from plugins/os-sdlc/lib/os_sdlc/parser/implementation/commit/item.rb.
Given the work ships, when commit_test.rb runs, then no test pins modified:.

Owner sketch

class OsSdlc::Implementation::Commit::Item
  def path
  end
end

Origin

Trigger: Jared's ruling on closed #906 on 2026-10-03 (shipped approach "flimsy").
Improvised this session: none
Chain: regex path parsing ← #906 changed only the refactorer prompt, not the parser (04fbc824) ← ADR-0171 decision 2 chose prose-shaped items parsed strictly (DESIGN: docs/adr/0171)
Root candidate: none
Where: plugins/os-sdlc/lib/os_sdlc/parser/implementation/commit/item.rb
Session: a0dbd5c4-ce77-4eaa-bb8a-9517044ae3ad
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/a0dbd5c4-ce77-4eaa-bb8a-9517044ae3ad.jsonl

VERDICT: CREATE

## Problem Jared ruled on closed ticket #906 on 2026-10-03 and called the shipped approach "flimsy". Handoff `items` entries are YAML strings that hold several fields as prose, and `Commit::Item` reads a path out of that prose with a regex. The handoff container is already YAML; the defect is that one string holds several fields. Jared's rule: the default is a machine-readable format (YAML or JSON, by context). Use prose only when a human reads it, or when prose serves an AI consumer better than a structured format. He suspects YAML fits the template that the refactorer gets, and that structured items make the parsing, the object creation, and the actions clearer. A machine-readable format hardens the connection between the agent and the codebase. This ticket needs a design ruling from Jared. ## Observed `plugins/os-sdlc/lib/os_sdlc/parser/implementation/commit/item.rb:7` defines `TAG = /\A[a-z_]+:\s*/`, and line 23 strips it: `@entry.strip.sub(TAG, "").split(/\s/).first.to_s.gsub(DECORATION, "")`. Before #906 (commit 04fbc824) the refactorer wrote items as `CHANGE: <path> :: <prose>`. Judge agents write tagged items: `plugins/os-sdlc/agents/test-reviewer.md:33` `TEST: <path> :: <test name>.`, and `contract-auditor.md:30` and `behavior-verifier.md:27` ("a list mixing these prefixes"). #906 changed only `plugins/os-sdlc/agents/refactorer.md:46` to plain paths ("one plain repository-relative path per entry, with no tag"). The parser kept the lowercase `TAG`. `plugins/os-sdlc/tests/command/implementation/commit_test.rb:163` still pins `items: ["modified: lib/widget.rb -- extracted the row reader"]`; the #906 prediction says no agent writes that format. `plugins/os-sdlc/tests/parser/implementation/commit/item_test.rb:14` checks paths with `path.match?(%r{\A[\w-]+(/[\w.-]+)*\.\w+\z})`. ## Reproduce n/a: design ticket; the format gap is visible by reading the files above. ## Approach Decide the item structure for every agent handoff template, then change parser, templates, and tests together. 1. Choose the item structure for every agent's handoff template (for example a mapping with `path` and a kind or note field) and name which agents keep prose items because a human or AI reads them. 2. Remove `Item::TAG` and the `modified:` test at `commit_test.rb:163`. 3. Decide which ADRs apply and whether new ones are required: ADR-0171 decision 2 (items are "prose-shaped in judge agents", parsed strictly; it needs an amending ADR), ADR-0135 (handoff contract), ADR-0159 (handoff item kinds: creates, expect-new). Run `os-adr:find` before work starts. No Accepted ADR may be reversed silently. 4. Second note from Jared: `item_test.rb:14` checks paths with a regex. Does `Pathname` or a simpler assertion fit? `Pathname.new("CHANGE:")` is also a valid Pathname, so `Pathname` alone cannot reject a tag. An equality assertion against the expected paths is one alternative. Required work: none beyond the acceptance criteria. ## Acceptance criteria 1. Given a ruling on the item structure, when the ticket is made ready-for-agent, then it lists the structure for each agent template. 2. Given the ruling, when the work ships, then no regex reads a path out of an item string and `TAG` is absent from `plugins/os-sdlc/lib/os_sdlc/parser/implementation/commit/item.rb`. 3. Given the work ships, when `commit_test.rb` runs, then no test pins `modified:`. ## Owner sketch ```ruby class OsSdlc::Implementation::Commit::Item def path end end ``` ## Origin - Trigger: Jared's ruling on closed #906 on 2026-10-03 (shipped approach "flimsy"). - Improvised this session: none - Chain: regex path parsing ← #906 changed only the refactorer prompt, not the parser (04fbc824) ← ADR-0171 decision 2 chose prose-shaped items parsed strictly (DESIGN: docs/adr/0171) - Root candidate: none - Where: plugins/os-sdlc/lib/os_sdlc/parser/implementation/commit/item.rb - Session: a0dbd5c4-ce77-4eaa-bb8a-9517044ae3ad - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/a0dbd5c4-ce77-4eaa-bb8a-9517044ae3ad.jsonl VERDICT: CREATE

jared added the

plugin/os-sdlc

filed-by/agent

labels

2026-10-03 13:20:08 +00:00

jared commented

2026-10-03 13:54:32 +00:00

Author

Owner

Ruling from Jared, 2026-10-03 (session a0dbd5c4): he scored the shipped #906 approach as "disagree". It improved on the original but did not challenge the problem deeply enough. The correct direction for this ticket: each field of a handoff item has a key, and no regex reads a path. The test compares the parsed paths with the expected list (an equality assertion). With structured items, the test needs no path validation. Jared: "This solution improves the code's resilience while simplifying it and making it more readable."

jared added the

category/owner-ruling

label

2026-10-10 13:31:49 +00:00