#3107 extension push/quality: structured acceptances for agents, a clearer title than For next time, and an optional reason

Context

Follow-up to swamp-club#3021 (declared acceptances, shipped in swamp-club/swamp#2883). Authors are expected to act on push and quality findings with an agent, not by copying text by hand. The closing report should be assessed on two things: what is easiest for a person to read and decide on, and what an agent can understand and implement without guessing.

Problem

1. The acceptance is a pre-formatted paste string, not a described edit. Each forNextTime entry carries acceptance (a text block) and placement (an English sentence such as "on line 9 of models/b.ts, or the line above"). An agent has to parse the sentence to find the file and position. For a sidecar acceptance the block is a whole quality.yaml (a comment line, version: 1, accept:, then the entry), so two findings produce two whole files. Merged literally, the result fails to parse ("duplicated key ... version: 1") and blocks the push. The JSON warnings and reviewRuleWarnings lists carry acceptance but not its placement.
2. The block title and key are not right. "For next time:" / forNextTime was the intent (advice, not a scolding) but not the right literal title.
3. The required reason is friction. The point of an acceptance is that the author saw the warning and decided to suppress it at that site; that decision, visible in the diff and reviewed in the pull request, is enough. Today a missing reason, or the <reason> placeholder, is a blocking invalid-acceptance.

Proposed change

1. Structured acceptance in JSON. Replace the acceptance string with an object describing the edit:

"acceptance": { "form": "comment", "file": "models/b.ts", "line": 9, "position": "same-line", "text": "// swamp-quality-ignore deno-command" }

"acceptance": { "form": "sidecar", "file": "quality.yaml", "entry": { "rule": "ipv4-address-literals", "file": "docs/hosts.txt" } }

position is an enum (same-line, line-above, file-header), replacing the prose placement. A sidecar acceptance is one entry to add to the accept list, so merging is unambiguous whether or not quality.yaml exists, and the doubled-header problem goes away. Carry the same object on the entries in warnings and reviewRuleWarnings.

2. Shorter log form. One line per option, no YAML header:

deno-command — models/b.ts:9: uses Deno.Command() to spawn a subprocess
  fix: prefer swamp's own primitives; validate every argument if a subprocess is required
  or accept on the line: // swamp-quality-ignore deno-command
ipv4-address-literals — docs/hosts.txt:3: IPv4 literal 10.0.0.1
  fix: use 192.0.2.x, 198.51.100.x or 203.0.113.x in examples
  or accept in quality.yaml: { rule: ipv4-address-literals, file: docs/hosts.txt }

3. Rename the block and key. Replace "For next time:" / forNextTime with a title that says what the list is: the warnings this run did not resolve, each with its fix and how to accept it. Candidates: "Unresolved warnings:" / unresolvedWarnings, or "Warnings to resolve:" / warningsToResolve. Decide in triage. Consider renaming "Accepted, with reasons:" to match if reasons become optional (for example "Accepted warnings:"), keeping declaredAcceptances distinct from the flag-waiver record acceptedWarnings.

4. Make the reason optional. Accept // swamp-quality-ignore <rule-id> with an optional : <reason>, and make reason optional on sidecar accept entries. Consequences to carry through:

• Drop the "reason is required" and <reason> placeholder rejections; snippets no longer carry a placeholder.
• Keep the restrictions on reason text in source when a reason is given (no quote character, no Deno.Command(, no base64 run): they are what keeps a directive from triggering or hiding a safety finding.
• Keep everything else that makes acceptances safe: one finding per acceptance, no error-level or adversarial-review rule, invalid directives block, stale directives warn.
• Report and contentMetadata.acceptances carry reason only when given.

5. Skill guidance for agents. In the extension-publish references: offer the fix first; accept only when the user decides the finding is not right for this extension; add sidecar entries to the existing accept list rather than writing a new file; ask the user for a reason only when one helps a reviewer.

Acceptance

• push --dry-run --json with two sidecar-form findings gives two entries an agent can merge into one valid quality.yaml; the merged file parses and both findings are accepted.
• Every comment-form acceptance in JSON carries file, line and an enum position.
• // swamp-quality-ignore deno-command with no reason accepts its line; the same with an error-level rule is still a blocking invalid-acceptance.
• The renamed block and key appear in log and JSON for push (dry run and completed) and quality.
• The swamp skill references and design/primitives/extensions.md describe the new shape, the optional reason and the agent guidance; swamp-uat #554's schemas and assertions are updated.

Related

swamp-club#3021 (declared acceptances), swamp-club#3095 (registry stores contentMetadata.acceptances; its shape should follow this issue), swamp-club#3098 (manual pages), swamp-club#3017 (one JSON document per run).