Rename settlement vocabulary inside the os-sdlc runner to intent-based terms

jared commented

2026-08-25 13:23:21 +00:00

Owner

Slice

Rename all "settle/settlement" vocabulary in the os-sdlc runner — agent-facing output and internal code — to the handoff/intent vocabulary the prompts use, while the subagent-stop command name and payload contract stay stable.

Context

The 2026-08-25 prompt reword (ADR-0148 session) replaced "settle your dispatch" with "submit the handoff to the runner" across all agent prompts, but the runner itself (CLI output, error text, gate feedback, class/method names) still speaks "settlement". Decision 2026-08-25 (maintainer, 100%): full rename — option B. Internal names follow because the original leak was runner-internal vocabulary bleeding into prompts; renaming only surfaces would recreate it.

Inventory (2026-08-25): agent-facing — stopped_without_settlement step value, /tmp/settle-<N>.json pattern in 11 agent .md files, "settlement command" in change-interpreter.md. Internal — GateSettlement, BlankContentSettlement, settle!, settle_verdict, settle_parsed_completion, already_settled_payload, ALREADY_SETTLED_TYPE, test helpers; concentrated in completion_intake.rb (19) and cli_subagent_stop_test.rb.

Governing ADRs: ADR-0144 (agent-initiated settlement mechanism — unchanged in behavior, informs the contract-stability constraint), ADR-0148 (prompt fossil/vocabulary rule — this ticket extends it to the runner), ADR-0149 (violations recorder touches gate_settlement.rb).

Acceptance criteria

Given any agent-facing runner output (CLI feedback, error text, JSON step values), when an agent reads it, then no "settle"/"settlement" term appears (e.g. stopped_without_settlement → a handoff-vocabulary equivalent)
Given the runner source under plugins/os-sdlc/lib and its tests, when grepped case-insensitively for "settle", then no class, method, constant, or test-helper names remain
Given an agent submits via os-sdlc-runner subagent-stop, when the payload is processed, then the command name and payload contract are unchanged (or the change is deliberately versioned with a recorded decision)
Given the agent prompt files under plugins/os-sdlc, when they reference the handoff flow, then they use the same vocabulary as the runner's output
Given the full test suite, when run, then it passes at the current baseline (1 known pre-existing failure)

Non-goals

Renaming the subagent-stop subcommand itself
Rewriting historical design-discussion docs (never-ask-twice.md, self-improvement-loops.md, OVERVIEW status markers) where "settled" is a design-status sense of the word
Any behavior change to the completion-intake state machine (ADR-0144)

Notes for implementer

Schema-adjacent string values (e.g. the STEP constant) are part of observable output — rename the value only if no persisted DB rows or external consumers depend on the literal; otherwise disclose. Run bin/refresh-plugins after prompt/SKILL edits.

Origin

Trigger: 2026-08-25 protocol-vocabulary survey and prompt reword (ADR-0148 session); user named the runner-side rename explicitly
Improvised this session: none
Chain: agents misread "settlement" ← prompts copied runner-internal vocabulary ← DESIGN (runner state-machine terms leaked into authoring; plugins/os-sdlc)
Root candidate: this ticket

## Slice Rename all "settle/settlement" vocabulary in the os-sdlc runner — agent-facing output and internal code — to the handoff/intent vocabulary the prompts use, while the `subagent-stop` command name and payload contract stay stable. ## Context The 2026-08-25 prompt reword (ADR-0148 session) replaced "settle your dispatch" with "submit the handoff to the runner" across all agent prompts, but the runner itself (CLI output, error text, gate feedback, class/method names) still speaks "settlement". Decision 2026-08-25 (maintainer, 100%): full rename — option B. Internal names follow because the original leak was runner-internal vocabulary bleeding into prompts; renaming only surfaces would recreate it. Inventory (2026-08-25): agent-facing — `stopped_without_settlement` step value, `/tmp/settle-<N>.json` pattern in 11 agent .md files, "settlement command" in change-interpreter.md. Internal — `GateSettlement`, `BlankContentSettlement`, `settle!`, `settle_verdict`, `settle_parsed_completion`, `already_settled_payload`, `ALREADY_SETTLED_TYPE`, test helpers; concentrated in `completion_intake.rb` (19) and `cli_subagent_stop_test.rb`. Governing ADRs: ADR-0144 (agent-initiated settlement mechanism — unchanged in behavior, informs the contract-stability constraint), ADR-0148 (prompt fossil/vocabulary rule — this ticket extends it to the runner), ADR-0149 (violations recorder touches `gate_settlement.rb`). ## Acceptance criteria - [ ] Given any agent-facing runner output (CLI feedback, error text, JSON step values), when an agent reads it, then no "settle"/"settlement" term appears (e.g. `stopped_without_settlement` → a handoff-vocabulary equivalent) - [ ] Given the runner source under plugins/os-sdlc/lib and its tests, when grepped case-insensitively for "settle", then no class, method, constant, or test-helper names remain - [ ] Given an agent submits via `os-sdlc-runner subagent-stop`, when the payload is processed, then the command name and payload contract are unchanged (or the change is deliberately versioned with a recorded decision) - [ ] Given the agent prompt files under plugins/os-sdlc, when they reference the handoff flow, then they use the same vocabulary as the runner's output - [ ] Given the full test suite, when run, then it passes at the current baseline (1 known pre-existing failure) ## Non-goals - Renaming the `subagent-stop` subcommand itself - Rewriting historical design-discussion docs (`never-ask-twice.md`, `self-improvement-loops.md`, OVERVIEW status markers) where "settled" is a design-status sense of the word - Any behavior change to the completion-intake state machine (ADR-0144) ## Notes for implementer Schema-adjacent string values (e.g. the `STEP` constant) are part of observable output — rename the value only if no persisted DB rows or external consumers depend on the literal; otherwise disclose. Run `bin/refresh-plugins` after prompt/SKILL edits. ## Origin - Trigger: 2026-08-25 protocol-vocabulary survey and prompt reword (ADR-0148 session); user named the runner-side rename explicitly - Improvised this session: none - Chain: agents misread "settlement" ← prompts copied runner-internal vocabulary ← DESIGN (runner state-machine terms leaked into authoring; plugins/os-sdlc) - Root candidate: this ticket

jared added the

plugin/os-sdlc

label

2026-08-25 13:23:21 +00:00

jared referenced this issue

2026-08-25 13:26:29 +00:00

Single-source the settlement block duplicated across os-sdlc agent prompts #504

jared commented

2026-08-25 15:28:58 +00:00

Author

Owner

This was generated by AI during triage.

Triaged 2026-08-25. Maintainer decision: option B, full rename (internal names follow the agent-facing rename), confidence 100%. Body refined to ticket template with inventory and governing ADRs (0144, 0148, 0149). Labels applied: enhancement, ready-for-agent. Work starting in a dedicated worktree; confidence passes (code-probe, change-interpreter, behavior-verifier) precede implementation.

> *This was generated by AI during triage.* Triaged 2026-08-25. Maintainer decision: option B, full rename (internal names follow the agent-facing rename), confidence 100%. Body refined to ticket template with inventory and governing ADRs (0144, 0148, 0149). Labels applied: enhancement, ready-for-agent. Work starting in a dedicated worktree; confidence passes (code-probe, change-interpreter, behavior-verifier) precede implementation.

jared added the

enhancement

ready-for-agent

labels

2026-08-25 15:28:58 +00:00

jared commented

2026-08-25 15:52:10 +00:00

Author

Owner

Resolution

Done: Full option-B settlement→handoff rename shipped on branch worktree-ticket-505-settlement-rename (commits f4b07fc + 36581d1, in worktree pending merge to main). GateSettlement→GateHandoff, BlankContentSettlement→BlankContentHandoff, settle-family methods→record-family, step literal now stopped_without_handoff, agent prompts use /tmp/handoff-.json, subagent-stop command and payload contract byte-for-byte unchanged.

Evidence: Suite 1110 runs, 2863 assertions, 0 failures (better than the 1-failure baseline: the stale pre-reword prompt assertions in change_interpreter_agent_test were in-scope and fixed). New settlement_vocabulary_guard_test pins the rename in lib/. Rubocop clean on touched files. Behavior-verifier audit passed after one finding (pipeline-state-investigate SKILL.md ADR-0140 reference) was fixed. Disclosure: historical step_results rows keep the literal stopped_without_settlement; no reader filters on it anywhere in the repo.

Follow-ups: none — optional cosmetic leftovers (fixture data strings like 'settle checkbox parsing', policy-sense 'settled decisions' comments) are deliberate exemptions recorded in the ticket's non-goals

## Resolution **Done:** Full option-B settlement→handoff rename shipped on branch worktree-ticket-505-settlement-rename (commits f4b07fc + 36581d1, in worktree pending merge to main). GateSettlement→GateHandoff, BlankContentSettlement→BlankContentHandoff, settle-family methods→record-family, step literal now stopped_without_handoff, agent prompts use /tmp/handoff-<N>.json, subagent-stop command and payload contract byte-for-byte unchanged. **Evidence:** Suite 1110 runs, 2863 assertions, 0 failures (better than the 1-failure baseline: the stale pre-reword prompt assertions in change_interpreter_agent_test were in-scope and fixed). New settlement_vocabulary_guard_test pins the rename in lib/. Rubocop clean on touched files. Behavior-verifier audit passed after one finding (pipeline-state-investigate SKILL.md ADR-0140 reference) was fixed. Disclosure: historical step_results rows keep the literal stopped_without_settlement; no reader filters on it anywhere in the repo. **Follow-ups:** none — optional cosmetic leftovers (fixture data strings like 'settle checkbox parsing', policy-sense 'settled decisions' comments) are deliberate exemptions recorded in the ticket's non-goals

jared closed this issue

2026-08-25 15:52:10 +00:00

jared referenced this issue

2026-08-25 17:55:55 +00:00

Build worktree Thor CLI (bin/worktree start|finish) and merge skills into /os:worktree #508

jared referenced this issue from a commit

2026-08-26 12:04:31 +00:00

refactor(os-sdlc): rename settlement vocabulary to handoff across runner (#505)

jared referenced this issue from a commit

2026-08-26 12:04:31 +00:00

docs(os-sdlc): history row for #505 handoff vocabulary rename

jared referenced this issue from a commit