fix: outside is checked, panel threads are not the maintainer's review; changelog and docs consolidated

[sebastian-iancu]

Summary

This PR fixes what a final review of everything since v0.11.1 found. It also carries two docs commits that were only on the local main.

Commits:

1. docs: consolidate the Unreleased changelog: the overlapping bullets from fix(tools): a pass over fixes reads only the fixes; Next respects the pass budget #45–fix: the review findings on v0.11.1..HEAD (guard, review state, backlog, docs) #51 become one set grouped by subsystem, under a summary paragraph like the released sections have.
2. docs: bring the user docs and README in line with the merged review work, from a docs review against the tree:
   • upgrading.md gets From 0.11.x to 0.12.0;
   • the conformance recipe in examples.md runs through /sdd-review, since the reviewer agents need the briefs it builds;
   • quick-start says how a review comment is graded and what status prints on a ready pull request;
   • the hook descriptions are corrected;
   • testing.md covers guard, the pass note and the pass budget.
3. fix(tools) and fix(skills): the review's four important findings and its smaller ones (below).

The four important findings:

• outside was only the reviewer's word. A defect on a line the branch changed, filed --outside, stopped blocking. sdd-pr add now checks the line against the branch's diff from its merge base and drops outside from a changed line, with a note. An unchanged line in a changed file keeps it.
• A panel reviewer's threads counted as the maintainer's review. That came from fix: the review findings on v0.11.1..HEAD (guard, review state, backlog, docs) #51's pull change meeting a review request that never asked for a By: line, so a panel or bot reviewer could open the pass over the fixes before the maintainer looked. Now:
  • the request asks each inline comment for By: <your name>;
  • pull ignores bot authors (…[bot]) when recording the maintainer's review;
  • the review is recorded at the pull request's head when the checkout holds it.
• An outside defect in a review body reached nothing. pull now reads the review bodies too. Each line there in the findings-file grammar that ends · outside becomes an outside finding, added only once, even after it has been resolved in the file. The request asks for that grammar.
• The outside rule covered code only. § Scope and the reviewers' digests now say "code, or a document". The template and the methodology's rules table follow.

The smaller ones:

• The test suite on a documents-only pass. /sdd-review now runs it only when code, tests or other files changed.
• § Passes says each of the maintainer's reviews opens one pass over the fixes, which is what the tool does.
• /sdd-deliver step 6 confirms a worker's out-of-scope defect before filing it, so add gets the evidence it requires.
• Untracked test inputs. The conformance reviewer names each guard sdd-pr guard refused. review.md and upgrading.md say why a test that needs untracked inputs can't run in guard's worktree.
• The two sentences the chore(skills): QA and trim the skill definitions; deliver opens a normal pull request #50 trim lost are back:
  • sdd-scaffold: "Nothing dispatches an agent the descriptor does not name";
  • sdd-trace: when to run the whole-tree audit.
• .sdd/. The session-start hook creates it only where the ignore line covers it, so an older repository doesn't end up with a dirty tree.
• The first harvest re-checks from --since.
• Locking. remove_scratch waiting for a running guard is now pinned by a test.
• A double space in review.md § Scope.

Not changed:

• Methodology §13. The merge gate still asks for a guard-removal test on every binding sentence, while the conformance reviewer proves only MUST and MUST NOT. That needs the maintainer's decision; the review recommends narrowing §13 to MUST and MUST NOT.
• Suggestions are still not ranked within a category. Deliberate.

Docs

Area	What changed
references/review.md	§ Scope, § The forge mirror, § Passes, § The tool
Methodology	its rules table
Template	ai-workflow.md, § Review and its review request
Agents	sdd-doc-reviewer, sdd-spec-conformance-reviewer
Skills	sdd-review step 3, sdd-deliver step 6, sdd-scaffold step 4, sdd-trace Mode C
Hooks	session-start.sh
User docs	README, docs/ (upgrading, examples, quick-start, install, testing, authoring, versioning)
Release notes	CHANGELOG

Word budgets grow: review.md +59, sdd-trace +10, sdd-scaffold +9, sdd-review +7, conformance reviewer +12, ai-workflow.md +10, sdd-doc-reviewer +3, sdd-deliver +1.

Verification

• ./scripts/validate.sh: OK, including two new hook checks (.sdd/ created only where it is ignored).

• Unit tests: python3 -m unittest discover -s tools/tests, 545 OK (was 540).

• Selftest: python3 tools/sdd-check.py selftest, OK.

• Plugin structure: claude plugin validate ., passed.

• Can-fail proof: each new fix was broken in turn in a scratch copy of the tool (7 versions):

  • the outside check;
  • the review-body read;
  • its de-duplication;
  • the bot skip;
  • the head commit;
  • the first re-check;
  • the removal lock.

  Each made a test fail.

• Real git: add --outside on a changed line is filed as blocking, with the note; on an unchanged line of the same file it stays outside.

Notes for review

Look hardest at:

• changed_lines and its use in cmd_add: diff from the merge base, -U0, new-side lines;
• the review-body reading in cmd_pull.

Azure DevOps: review_bodies returns every thread's first comment, but an inline thread's first line has no path, so it doesn't parse as a review-body line.

Checklist

• Scoped to one logical change (the final review's findings, plus the changelog and docs consolidation)
• The gates above pass locally and their output was read
• CHANGELOG entry under Unreleased
• AGENTS.md, README.md and hooks/session-start.sh synced; no component added or renamed
• No internal or private repository names, absolute paths or organisation-private details

🤖 Generated with Claude Code