claude-dev-env 8.102.0 → 8.103.0

package/.agents/skills/orchestrator/SKILL.md

@@ -110,6 +110,7 @@ Checkpoint after decisions and state changes, before waiting, and before a known
 
 ### Complete the requested outcome
 
+Before a completion report or status answer, follow [completion reporting](reference/completion-reporting.md).
 Close a task only after its evidence is checked and integrated into the task authority.
 Close a goal only when its acceptance conditions and authorized delivery are met.
 Keep a named pending user action open when required. Completed work needs no invented final human action.
@@ -137,6 +138,7 @@ Report the result, evidence, and any remaining limit.
 | `AGENTS.md` | Skill subtree instructions. |
 | `.claude/CLAUDE.md` | Claude instruction import. |
 | `reference/run-state.md` | Goal records, task authority, follow list, and active-root registry. |
+| `reference/completion-reporting.md` | Verified goal status and unfinished administrative work. |
 | `reference/recovery.md` | Cold-start and compaction recovery. |
 | `reference/oversee-delegated-work.md` | Spawner review of delegated work before it reaches the user. |
 | `reference/platform-evidence.md` | Official Projects sources and coordinator report boundaries. |

package/.agents/skills/orchestrator/reference/completion-reporting.md

@@ -0,0 +1,13 @@
+# Report completion
+
+Use this procedure before a completion report or an answer about whether work is done.
+
+1. Recover the user's requested outcome and acceptance conditions. Read the evidence for that outcome before choosing its status.
+2. Check what each unfinished item changes. Missing deliverables, required verification, necessary approvals, and stated completion prerequisites keep the affected goal open. An administrative item whose absence has no effect on the result, its use, or its acceptance keeps its own task open.
+3. State the main outcome first. When that outcome is verified complete and only incidental recordkeeping remains, report the task as complete. A requested status notice alone does not make the main outcome incomplete. Mention the administrative item separately when useful or required by the active reporting rules.
+4. Keep unfinished work tracked honestly. When one tracker item combines the completed outcome and unfinished administration, preserve the outcome's goal and evidence, mark its work complete, and keep a separate open administrative follow-up. Do reachable administrative work before ending. Preserve its next action or blocker when it cannot be finished. Never mark it done merely to make the report look complete.
+5. Preserve other goals and required delivery. A complete subgoal does not close an unfinished goal or the parent run. Use the goal's acceptance conditions in the [run record](run-state.md) to decide what its remaining work affects.
+
+An administrative action can be requested without being a condition of the main outcome's completion. Treat it as a completion prerequisite when the user states that dependency, when it carries an essential requested result, or when its absence affects the result's usability, safety, or completeness.
+
+For example, a verified report already delivered to the user is complete while an internal progress notice remains unsent. A report still missing required checks, required approval, or its requested delivery remains incomplete.

package/.agents/skills/pull-request/reference/body-sections.md

@@ -7,7 +7,8 @@ A reviewer reads the body in place of the code. The body says what the change do
 | `## What this does` | Two or three plain sentences: the behavior before, the behavior after, and who notices. Written for a reviewer who has not read the worker's conversation. |
 | `## What changed` | One bullet per area of the diff, in plain words. |
 | `## Existing work` | What already did part of the job, with a link or file and line, and what this change adds. Or the places searched. |
-| `## Proof in practice` | Each command in backticks, the output without the change and with it, and anything still unproven. |
+| `## Proof in practice` | Each command in backticks, and the output without the change and with it. The run on the target the change exists to fix is here before the pull request opens. |
+| `## Not covered` | Optional. A condition the change does not target and the runs left out, such as an older data shape. |
 | `## Eval` | Only for a `feat` title. The eval's cases and grader, the command, and its result. |
 | `## Risk` | What could break, for whom, and how anyone would notice. `Low` and one reason for a doc or test change. |
 | `## How to revert` | The exact undo step, and any data or state a plain revert leaves behind. |

package/bin/install.prompt-context.test.mjs

@@ -35,13 +35,14 @@ test('reinstall drops the retired style reminder and keeps one skill reminder ho
     mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
 
     const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
-    assert.equal(userPromptHooks.length, 6);
+    assert.equal(userPromptHooks.length, 7);
     assert.equal(userPromptHooks[0].command, userCommand);
     assert.match(userPromptHooks[1].command, /session\/skill_loaded_reminder\.py$/);
     assert.match(userPromptHooks[2].command, /lifecycle\/nested_project_hooks\.py$/);
     assert.match(userPromptHooks[3].command, /blocking\/chat_reply_gate\.py$/);
     assert.match(userPromptHooks[4].command, /session\/tracking_nudge\.py$/);
     assert.match(userPromptHooks[5].command, /session\/plugin_change_warning\.py$/);
+    assert.match(userPromptHooks[6].command, /blocking\/turn_review_gate\.py$/);
     assert.ok(userPromptHooks.every(eachHook => !eachHook.command.includes('style_reminder_prompt')));
 
     const firstMerge = JSON.stringify(settings);

package/docs/agents-guidance/asks.md

@@ -11,6 +11,12 @@
 - Keep each item's status current as the work moves: in progress when you start it, completed only after you saw the proof. A long turn updates the list at each step, so the list never lags the work.
 - An item blocked on the user stays open, and the reply says what the user must give.
 
+## Completion reports
+
+Judge completion against the user's outcome and acceptance conditions. Report a verified main outcome as complete when only incidental recordkeeping remains, even when that administration was requested. Missing deliverables, required verification, approvals governing the outcome, stated completion prerequisites, and work needed for usability, safety, or completeness keep the affected goal open.
+
+When one task combines a completed outcome and unfinished administration, preserve the goal and evidence, mark the main work complete, and track administration as a separate open follow-up. Do reachable administrative work now. Report the main outcome first and mention administration separately when useful.
+
 ## Asks ledger
 
 When the host keeps an asks ledger with `ledger.py` and `asks_check.py`, record each ask in it too:

package/docs/rule-guides/proof-before-pull-request.md

@@ -30,14 +30,14 @@ For a change to Claude Code behavior, such as a hook, skill, rule, setting, prom
 - Read the broker report for the account it chose. Read the stream for the hook events and their output, `permission_denials`, the final result, and the token usage on the result event.
 - When the broker exits 3 with action "wait", no account has room. Treat that as a blocked proof and report its reason and `resets_at`. Spawn Claude only through the broker.
 
-Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, state the difference between the runs with and without the change, and name anything still unproven.
+Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, and state the difference between the runs with and without the change. The run on the target the change exists to fix belongs in this section before the pull request opens. List a condition the change does not target, such as an older data shape, under a "Not covered" heading at the same level.
 
 When you cannot prove it, leave the pull request unopened. Tell the owner in three short sentences what you could not run and which tool would make it possible. A blocked proof is an acceptable result, because it shows where tooling is missing.
 
 ## Enforcement
 
-`hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on `gh pr create`, the `pull_request.py create` script, and each `mcp__*__create_pull_request` tool. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. The gate also denies a section whose only commands run a test runner, such as `pytest`, `python -m unittest`, `uv run pytest`, `npm test`, `npx vitest`, `jest`, `go test` or `cargo test`. Quotes around a runner word, interpreter flags before `-m`, and `coverage run -m unittest` are still test runs. A command is an inline backticked span or a `$ ` line inside a fenced block. A span that starts with a path and line, such as `gate.py:12`, is not a command. A span that holds one path or file name, such as `src/x.py`, is not a command unless that span runs a test runner, such as `py.test` or `pytest.exe`. A test run piped into `tee`, `tail`, `head`, `grep` or `cat` is still a test run. The deny quotes the line "Unit tests are welcome as extra evidence. The live run is the proof." and asks for a run of the changed thing the way its user runs it, without the change and with it. A section with one command that is not a test run passes. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
+`hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on `gh pr create`, the `pull_request.py create` script, and each `mcp__*__create_pull_request` tool. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. The gate also denies a section whose only commands run a test runner, such as `pytest`, `python -m unittest`, `uv run pytest`, `npm test`, `npx vitest`, `jest`, `go test` or `cargo test`. Quotes around a runner word, interpreter flags before `-m`, and `coverage run -m unittest` are still test runs. A command is an inline backticked span or a `$ ` line inside a fenced block. A span that starts with a path and line, such as `gate.py:12`, is not a command. A span that holds one path or file name, such as `src/x.py`, is not a command unless that span runs a test runner, such as `py.test` or `pytest.exe`. A test run piped into `tee`, `tail`, `head`, `grep` or `cat` is still a test run. The deny quotes the line "Unit tests are welcome as extra evidence. The live run is the proof." and asks for a run of the changed thing the way its user runs it, without the change and with it. The gate also denies a section whose prose says part of the change is not proven, not tested or not verified, with "yet", "been" or "fully" allowed after the "not", or says unproven, untested or unverified. The deny quotes that line, and asks for the run before the pull request opens, or for the line under a "Not covered" heading when the change does not target it. Words inside backticks or a fenced block are quoted output and do not count. A section with one command that is not a test run, and no such line, passes. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
 
 When the checked-out branch changes a file people see (`.html`, `.htm`, `.css`, `.scss`, `.tsx`, `.jsx`, `.vue`, `.svelte`), the gate also denies a body whose proof section holds no picture: a markdown image, an image URL, or an Artifact page link that shows the screenshots. Render the change, read the screenshot, and put it in the section, so the reader sees what you looked at. When git in the session directory cannot list the branch's changed files, the gate asks for the picture as well.
 
-The gate checks that the section is there and names a command. Whether the run proves the change stays a judgment for the author and the reviewer.
+The gate checks that the section is there, names a command, and admits no unproven part. Whether the run proves the change stays a judgment for the author and the reviewer.

package/hooks/blocking/pull_request_proof.py

@@ -56,7 +56,12 @@ from hooks_constants.pull_request_proof_constants import (
     FENCED_COMMAND_PROMPT,
     INLINE_COMMAND_PATTERN,
     TEST_ONLY_PROOF_REASON,
+    ALL_CODE_FENCE_MARKERS,
+    BLOCKQUOTE_MARKERS,
+    INLINE_CODE_SPAN_PATTERN,
     UNITTEST_MODULE_NAME,
+    UNPROVEN_ADMISSION_PATTERN,
+    UNPROVEN_PROOF_REASON,
     ALL_PASSTHROUGH_PROGRAM_NAMES,
     PATH_WITH_LINE_PATTERN,
     SINGLE_FILE_NAME_PATTERN,
@@ -332,14 +337,31 @@ def _line_commands(line: str, is_inside_fence: bool) -> list[str]:
     return []
 
 
-def _proof_commands(section: str) -> list[str]:
-    all_commands: list[str] = []
-    is_inside_fence = False
+def _fence_marker(line: str) -> str | None:
+    fence_text = line.strip().lstrip(BLOCKQUOTE_MARKERS).strip()
+    for each_marker in ALL_CODE_FENCE_MARKERS:
+        if fence_text.startswith(each_marker) and each_marker not in fence_text[len(each_marker) :]:
+            return each_marker
+    return None
+
+
+def _lines_with_fence_state(section: str) -> Iterator[tuple[str, bool]]:
+    open_marker: str | None = None
     for each_line in section.splitlines():
-        if each_line.strip().startswith(CODE_FENCE_MARKER):
-            is_inside_fence = not is_inside_fence
+        line_marker = _fence_marker(each_line)
+        if line_marker is not None and open_marker is None:
+            open_marker = line_marker
             continue
-        all_commands.extend(_line_commands(each_line, is_inside_fence))
+        if line_marker is not None and line_marker == open_marker:
+            open_marker = None
+            continue
+        yield each_line, open_marker is not None
+
+
+def _proof_commands(section: str) -> list[str]:
+    all_commands: list[str] = []
+    for each_line, each_is_inside_fence in _lines_with_fence_state(section):
+        all_commands.extend(_line_commands(each_line, each_is_inside_fence))
     return [each_command for each_command in all_commands if _reads_as_command(each_command)]
 
 
@@ -401,6 +423,35 @@ def _proof_runs_only_tests(section: str) -> bool:
     return bool(all_commands) and all(_command_runs_tests(each_command) for each_command in all_commands)
 
 
+def _prose_lines(section: str) -> Iterator[tuple[str, str]]:
+    for each_line, each_is_inside_fence in _lines_with_fence_state(section):
+        if not each_is_inside_fence:
+            yield each_line, re.sub(INLINE_CODE_SPAN_PATTERN, "", each_line.replace(CODE_FENCE_MARKER, "`"))
+
+
+def unproven_admission(section: str) -> str | None:
+    """Return the first prose line of a proof section that says something is not proven, or None.
+
+    ::
+
+        "Not proven here: a fresh Convert run."   -> "Not proven here: a fresh Convert run."
+        "The live run is untested."               -> "The live run is untested."
+        "It has not been tested on the target."   -> "It has not been tested on the target."
+        "`not proven` printed by the probe"       -> None
+        "> Not proven here: the live run."        -> "> Not proven here: the live run."
+        "Ran `python run.py`, quoted below."      -> None
+
+    The markers are not proven, not tested and not verified, each with any
+    run of yet, been or fully after the not, plus unproven, untested and
+    unverified, matched without regard to case. Inline code spans and fenced
+    blocks are skipped, so output quoted there never counts.
+    """
+    for each_line, each_prose in _prose_lines(section):
+        if re.search(UNPROVEN_ADMISSION_PATTERN, each_prose, re.IGNORECASE):
+            return each_line.strip()
+    return None
+
+
 def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None:
     """Return a deny reason when a new pull request's body has no proof, else None.
 
@@ -412,6 +463,7 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
         proof whose only command is `py.test`                   -> TEST_ONLY_PROOF_REASON
         proof whose only command is `python -q -m unittest`     -> TEST_ONLY_PROOF_REASON
         proof with `pytest` and `python run.py`                 -> None
+        proof whose prose says "Not proven here: the run"      -> UNPROVEN_PROOF_REASON
         gh pr create --fill                                     -> MISSING_BODY_REASON
         gh pr edit, git push, any other tool                    -> None
 
@@ -425,6 +477,9 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
     the section is denied. Quotes around a runner word still count. Interpreter
     flags before -m unittest still count. coverage run -m unittest counts.
     A pipe into tee, tail, head, grep or cat keeps a test run a test run.
+    A section whose prose says part of the change is not proven, untested or
+    unverified is denied, with the line quoted; unproven_admission lists the
+    markers.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -437,6 +492,9 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
             return MISSING_PROOF_REASON
         if _proof_runs_only_tests(section):
             return TEST_ONLY_PROOF_REASON
+        admission = unproven_admission(section)
+        if admission is not None:
+            return UNPROVEN_PROOF_REASON.format(admission=admission)
     return None
 
 

package/hooks/blocking/test_pull_request_proof.py

@@ -18,6 +18,7 @@ from hooks_constants.pull_request_proof_constants import (
     MISSING_EXISTING_WORK_REASON,
     MISSING_PROOF_REASON,
     TEST_ONLY_PROOF_REASON,
+    UNPROVEN_PROOF_REASON,
     UNREADABLE_CHANGES_REASON,
 )
 
@@ -111,6 +112,92 @@ def test_proof_with_a_test_run_and_file_references_should_be_denied() -> None:
     assert gate.missing_proof_reason(_mcp_create(body)) == TEST_ONLY_PROOF_REASON
 
 
+def test_proof_that_says_its_target_run_is_not_proven_should_be_denied() -> None:
+    body = (
+        "## Proof in practice\nRan `python verify.py theme`.\n> PASS\n\n"
+        "Not proven here: a fresh Convert run of Bear Penguin that rewrites the record.\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: a fresh Convert run of Bear Penguin that rewrites the record."
+    )
+
+
+@pytest.mark.parametrize(
+    "admission", ["unproven", "not yet tested", "Untested", "unverified", "not verified", "not been tested", "not fully verified"]
+)
+def test_each_unproven_marker_in_proof_prose_should_be_denied(admission: str) -> None:
+    admission_line = f"The live dialer path is {admission}."
+    body = f"## Proof in practice\nRan `python run.py`.\n{admission_line}\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(admission=admission_line)
+
+
+def test_unproven_line_moved_under_a_not_covered_heading_should_pass() -> None:
+    body = (
+        "## Proof in practice\nRan `python run.py`.\n> PASS\n\n"
+        "## Not covered\n\nNot proven here: a run on an older session.\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_unproven_words_inside_quoted_output_should_pass() -> None:
+    body = (
+        "## Proof in practice\nRan `python run.py`, which printed `unverified sender denied`.\n"
+        "```\n$ python run.py\nstatus: not proven\n```\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_unproven_admission_after_a_one_line_triple_backtick_span_should_be_denied() -> None:
+    body = (
+        "## Proof in practice\nRan `python run.py`.\n```python run.py``` -> PASS\n"
+        "Not proven here: the live run on the target.\n"
+    )
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: the live run on the target."
+    )
+
+
+def test_test_run_after_a_one_line_triple_backtick_span_should_be_denied() -> None:
+    body = "## Proof in practice\n```pytest``` ok\nRan `pytest tests/`.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == TEST_ONLY_PROOF_REASON
+
+
+def test_unproven_words_in_a_fence_inside_a_blockquote_should_pass() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n> ```\n> status: not proven\n> ```\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_unproven_words_in_a_tilde_fence_should_pass() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n~~~\nstatus: not proven\n~~~\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_tilde_line_inside_a_backtick_fence_keeps_the_fence_open() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n```\n~~~\nstatus: not proven\n```\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) is None
+
+
+def test_admission_after_a_backtick_fence_holding_a_tilde_line_should_be_denied() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n```\n~~~\n```\nNot proven here: the live run.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: the live run."
+    )
+
+
+def test_unproven_deny_quotes_the_line_as_written() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\nNot proven here: the `convert.py` run on the target.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="Not proven here: the `convert.py` run on the target."
+    )
+
+
+def test_unproven_admission_inside_a_blockquote_should_be_denied() -> None:
+    body = "## Proof in practice\nRan `python run.py`.\n> Not proven here: the live dialer run.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == UNPROVEN_PROOF_REASON.format(
+        admission="> Not proven here: the live dialer run."
+    )
+
+
 def test_proof_with_a_test_run_piped_into_tee_should_be_denied() -> None:
     body = "## Proof in practice\nRan `pytest x | tee log`.\n"
     assert gate.missing_proof_reason(_mcp_create(body)) == TEST_ONLY_PROOF_REASON

package/hooks/blocking/test_turn_review_findings.py

@@ -0,0 +1,25 @@
+from turn_review_findings import finding_lines
+
+CHANGED_PATH = "src/service.py"
+
+
+def test_should_read_a_json_finding_on_a_changed_path() -> None:
+    review_text = (
+        'Review done.\n[{"file": "src/service.py", "line": 208, "summary": "drops the retry"},'
+        ' {"file": "src/other.py", "line": 3, "summary": "unchanged file"}]'
+    )
+    assert finding_lines(review_text, [CHANGED_PATH]) == ["src/service.py:208 drops the retry"]
+
+
+def test_should_read_a_prose_finding_that_opens_with_a_changed_path() -> None:
+    review_text = (
+        "- `src/service.py:208` - drops the retry\nThe change at src/service.py:12 is fine."
+    )
+    assert finding_lines(review_text, [CHANGED_PATH]) == [
+        "- `src/service.py:208` - drops the retry"
+    ]
+
+
+def test_should_report_nothing_for_a_review_that_opens_with_none() -> None:
+    review_text = "(none)\n- `src/service.py:208` - looked at the retry, it stays"
+    assert finding_lines(review_text, [CHANGED_PATH]) == []