claude-dev-env 8.6.1 → 8.8.0

package/.agents/skills/privacy-hygiene/reference/sweep-procedure.md

@@ -49,7 +49,7 @@ Review each hit. Ignore:
 
 - Stage only clean files
 - Prefer `--body-file` for `gh` posts (also required by the gh-cli-conventions rule)
-- Let `pii_prevention_blocker` re-run on the next Write / commit / post
+- No hook re-scans the next Write, commit, or post; `pii_prevention_blocker` was retired. Re-run this sweep before the next commit or post.
 
 ## Accepted residual (do not over-scrub)
 

package/.agents/skills/team-advisor/SKILL.md

@@ -25,7 +25,7 @@ One warm advisor at the strongest tier this session can reach. This session is t
 
 1. Name the session identity first (protocol **Host profiles**), then walk the model floor.
 2. Claude: when `advisor` is in this session's tool list, the built-in advisor tool is the advisor. Spawn nothing and call `advisor()` at each consult point. Otherwise spawn or resume `pstack:poteto-agent` at `ADVISOR_EFFORT` (default low) with the advisor response contract in the prompt. When the bound model is out of usage, use the configured fallback at the same effort. Codex: use the native advisor path. Third-party: use the headless advisor path. When the host's walk fails, fail closed.
-3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path, pass `flags: ["--advisor"]` with Astra.
+3. Name the warm instance `team-advisor-agent` and keep its advisor response contract in every first prompt. When a native Codex subagent spawn is the advisor path and the spawn tool has a `flags` field, pass `flags: ["--advisor"]` with Astra and record `advisor_flag: passed`. A spawn that skips an offered flag is a failed bind. When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `advisor_flag: unavailable`, and treat it as bound.
 4. Skip the multi-consumer "who you are" opener. This session is the sole consumer.
 5. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
@@ -49,7 +49,7 @@ Aim for two consults on a normal task: one after orientation and one after write
 - Bind at or above the protocol floor for this host.
 - The advisor only answers (messaging); the session runs tools and posts.
 - Keep an optional reference gap in the reference record: path, status, repair action, and repair result. A reference gap leaves bind status separate.
-- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`.
+- On Codex, select native Astra when its bind and reply validation pass. Record `selected_tier: Astra` and `reply_path: native`, plus `advisor_flag: passed` or `advisor_flag: unavailable`.
 - Mark `fallback_kind: broken` only when the selected bind or reply path fails. Record the selected tier, fallback reason, and reply path in the same evidence object.
 - Record first, recovery, and completion consults with changed evidence, validation, unresolved risks, and report-back status.
 - Write the evidence object to the session-controlled `model-tier-run.json` record described in `advisor-tool.md`.

package/_shared/advisor/reference/identity.md

@@ -19,7 +19,7 @@ When both `codex` and `claude` tokens appear, Codex wins. Empty text is ThirdPar
 
 **Claude.** Spawn `subagent_type: session-advisor` at Fable through the Agent tool. When Fable is out of usage, bind Astra through the Codex helper if `ADVISOR_ASTRA` is on. Fail closed when neither binds.
 
-**Codex.** Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`). Walk `candidate_tiers = ["Astra"]`. Record `{tier: "Astra", result: "spawned"}` on success. The `ADVISOR_ASTRA` flag is not required. Fail closed when Astra does not bind. Do not walk Fable on a Codex host.
+**Codex.** Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`). Walk `candidate_tiers = ["Astra"]`. When the spawn tool has a `flags` field, pass `flags: ["--advisor"]` and record `fallback.advisor_flag: "passed"`. When it has none, as in `codex exec`, spawn `gpt-6-astra` plainly and record `fallback.advisor_flag: "unavailable"`. Both count as a bind. Record `{tier: "Astra", result: "spawned"}` on success. The `ADVISOR_ASTRA` flag is not required. Fail closed when Astra does not bind, or when the spawn skips a flag the host offers. Do not walk Fable on a Codex host.
 
 **ThirdParty.** Bind Fable through the CLI Claude-chain. When Fable is out of usage, bind Astra through the Codex helper if `ADVISOR_ASTRA` is on. Fail closed when neither binds.
 

package/_shared/advisor/reference/spawn-walk-log.md

@@ -29,5 +29,5 @@ Exit code `1` means a ladder invariant failed.
 Exit code `2` means the path or JSON was unusable.
 The same checks are available in-process via `validate_model_tier_run(run)`.
 
-The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"`.
+The validator checks ladder shape and validates `evidence` when it is present. On Claude and ThirdParty, Astra is attempted after Fable when `astra_enabled` is enabled, and `selected_tier: "Astra"` requires `result: "codex"`. On Codex, the walk is Astra only, and `result: "spawned"` or `result: "codex"` counts as success. A Codex success record uses `reply_path: "native"` and `advisor_flag: "passed"` or `advisor_flag: "unavailable"`. A missing `advisor_flag` or `advisor_flag: "omitted"` fails validation.
 Host policy sits on top of it. See the Model floor section of the protocol.

package/_shared/advisor/reference/warm-up.md

@@ -31,7 +31,9 @@ The agent finishes its first turn standing by. `SendMessage` alone resumes it; b
 ## Codex host
 
 Spawn a native in-session Astra subagent at `resolve_codex_model_id("Astra")` (`gpt-6-astra`) with the charter as its prompt.
-Record `{tier: "Astra", result: "spawned"}` on success. Fail closed when that spawn does not bind.
+When the spawn tool has a `flags` field, pass `flags: ["--advisor"]` and record `fallback.advisor_flag: "passed"`.
+When the spawn tool has no `flags` field, as in `codex exec`, spawn `gpt-6-astra` plainly, record `fallback.advisor_flag: "unavailable"`, and treat the advisor as bound.
+Record `{tier: "Astra", result: "spawned"}` on success. Fail closed when that spawn does not bind, or when it skips a flag the host offers.
 The `ADVISOR_ASTRA` flag is not required. Do not walk Fable. Consults stay in-session with that Astra subagent.
 Identity routing: [`identity.md`](identity.md).
 

package/_shared/advisor/scripts/config/advisor_scripts_constants/model_tier_run_validator_constants.py

@@ -105,3 +105,19 @@ CLI_SUCCESS_EXIT_CODE: int = 0
 ALL_ADVISOR_REPLY_PATHS: frozenset[str] = frozenset(
     {"native", "sendmessage", "cli", "codex", "none"}
 )
+EVIDENCE_MUST_BE_OBJECT_MESSAGE: str = "evidence must be an object"
+ADVISOR_FLAG_PASSED: str = "passed"
+ADVISOR_FLAG_UNAVAILABLE: str = "unavailable"
+ADVISOR_FLAG_OMITTED: str = "omitted"
+ALL_ADVISOR_FLAG_STATES: frozenset[str] = frozenset(
+    {ADVISOR_FLAG_PASSED, ADVISOR_FLAG_UNAVAILABLE, ADVISOR_FLAG_OMITTED}
+)
+UNKNOWN_ADVISOR_FLAG_MESSAGE: str = (
+    "evidence.fallback.advisor_flag must be passed, unavailable, or omitted"
+)
+MISSING_ADVISOR_FLAG_MESSAGE: str = (
+    "Codex Astra success requires evidence.fallback.advisor_flag"
+)
+OMITTED_ADVISOR_FLAG_MESSAGE: str = (
+    "Codex Astra spawn skipped the --advisor flag the host offers"
+)

package/_shared/advisor/scripts/model_tier_run_validator.py

@@ -67,6 +67,8 @@ from advisor_scripts_constants.astra_advisor_constants import (
     ASTRA_FALLBACK_KIND_DECLINED,
 )
 from advisor_scripts_constants.model_tier_run_validator_constants import (
+    ADVISOR_FLAG_OMITTED,
+    ALL_ADVISOR_FLAG_STATES,
     ALL_ADVISOR_REPLY_PATHS,
     ATTEMPT_ORDER_MISMATCH_MESSAGE,
     ATTEMPT_TIER_OUT_OF_SLICE_MESSAGE,
@@ -76,15 +78,19 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (
     CLI_SUCCESS_EXIT_CODE,
     CLI_USAGE_MESSAGE,
     CLI_VALIDATION_FAILURE_EXIT_CODE,
+    EVIDENCE_MUST_BE_OBJECT_MESSAGE,
     HOST_PROFILE_CLAUDE,
     HOST_PROFILE_CODEX,
     HOST_PROFILE_JSON_KEY,
     HOST_PROFILE_MUST_BE_STRING_MESSAGE,
     INCOMPLETE_FALLBACK_WALK_MESSAGE,
+    MISSING_ADVISOR_FLAG_MESSAGE,
     MISSING_FALLBACK_REASON_MESSAGE,
+    OMITTED_ADVISOR_FLAG_MESSAGE,
     SELECTED_TIER_MISMATCH_MESSAGE,
     SELECTED_TIER_NOT_NULL_MESSAGE,
     THIRD_PARTY_MODEL_TIER,
+    UNKNOWN_ADVISOR_FLAG_MESSAGE,
     UNKNOWN_HOST_PROFILE_ERROR,
     UNKNOWN_OWN_TIER_MESSAGE,
 )
@@ -211,14 +217,26 @@ def _validate_fallback_reply_path(
         raise ModelTierRunError(
             "evidence.fallback.reply_path is not a known advisor path"
         )
-    if (
+    is_codex_astra_success = (
         canonical_host_profile(run.host_profile) == HOST_PROFILE_CODEX
         and maybe_run_selected_tier == ADVISOR_MODEL_TIER
-        and reply_path != "native"
-    ):
+    )
+    if is_codex_astra_success and reply_path != "native":
         raise ModelTierRunError(
             "Codex Astra success requires the native reply path"
         )
+    raw_advisor_flag = fallback_by_name.get("advisor_flag")
+    if raw_advisor_flag is None:
+        if is_codex_astra_success:
+            raise ModelTierRunError(MISSING_ADVISOR_FLAG_MESSAGE)
+        return
+    if (
+        not isinstance(raw_advisor_flag, str)
+        or raw_advisor_flag not in ALL_ADVISOR_FLAG_STATES
+    ):
+        raise ModelTierRunError(UNKNOWN_ADVISOR_FLAG_MESSAGE)
+    if is_codex_astra_success and raw_advisor_flag == ADVISOR_FLAG_OMITTED:
+        raise ModelTierRunError(OMITTED_ADVISOR_FLAG_MESSAGE)
 
 
 def _validate_fallback_evidence(
@@ -242,7 +260,7 @@ def _validate_advisor_evidence(
     run: ModelTierRun,
 ) -> None:
     if not isinstance(evidence, Mapping):
-        raise ModelTierRunError("evidence must be an object")
+        raise ModelTierRunError(EVIDENCE_MUST_BE_OBJECT_MESSAGE)
     raw_schema_version = evidence.get("schema_version")
     if isinstance(raw_schema_version, bool) or raw_schema_version != 1:
         raise ModelTierRunError("evidence.schema_version must be 1")
@@ -415,7 +433,7 @@ def load_model_tier_run_from_json_path(from_path: Path) -> ModelTierRun:
         raise TypeError(HOST_PROFILE_MUST_BE_STRING_MESSAGE)
     raw_evidence = parsed_payload.get("evidence")
     if raw_evidence is not None and not isinstance(raw_evidence, dict):
-        raise TypeError("evidence must be an object")
+        raise TypeError(EVIDENCE_MUST_BE_OBJECT_MESSAGE)
     return ModelTierRun(
         own_tier=parsed_payload["own_tier"],
         candidate_tiers=list(parsed_payload["candidate_tiers"]),

package/_shared/advisor/scripts/tests/test_model_tier_run_validator.py

@@ -35,13 +35,25 @@ load_model_tier_run_from_json_path = (
 )
 ADVISOR_MODEL_TIER = model_tier_run_validator.ADVISOR_MODEL_TIER
 CODEX_BIND_SUCCESS_TOKEN = model_tier_run_validator.CODEX_BIND_SUCCESS_TOKEN
+EVIDENCE_MUST_BE_OBJECT_MESSAGE = (
+    model_tier_run_validator.EVIDENCE_MUST_BE_OBJECT_MESSAGE
+)
 
 
 def _native_codex_evidence(
     *,
     reply_path: str = "native",
     reference_status: str = "missing",
+    advisor_flag: str | None = "passed",
 ) -> dict[str, object]:
+    fallback: dict[str, object] = {
+        "selected_tier": "Astra",
+        "fallback_kind": None,
+        "fallback_reason": None,
+        "reply_path": reply_path,
+    }
+    if advisor_flag is not None:
+        fallback["advisor_flag"] = advisor_flag
     return {
         "schema_version": 1,
         "reference": {
@@ -50,12 +62,7 @@ def _native_codex_evidence(
             "repair_action": "use the projected docs root",
             "repair_result": "read",
         },
-        "fallback": {
-            "selected_tier": "Astra",
-            "fallback_kind": None,
-            "fallback_reason": None,
-            "reply_path": reply_path,
-        },
+        "fallback": fallback,
         "consult": {
             "changed_evidence": ["native bind returned a reply"],
             "validation": ["signal and session id read back"],
@@ -93,6 +100,46 @@ def test_codex_native_success_rejects_non_native_reply_path() -> None:
         validate_model_tier_run(run)
 
 
+def _codex_astra_success_run(evidence: dict[str, object]) -> ModelTierRun:
+    return ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        host_profile="Codex",
+        evidence=evidence,
+    )
+
+
+def test_codex_plain_astra_spawn_binds_when_host_lacks_advisor_flag() -> None:
+    run = _codex_astra_success_run(
+        _native_codex_evidence(advisor_flag="unavailable")
+    )
+
+    assert validate_model_tier_run(run) is None
+
+
+def test_codex_astra_spawn_that_skips_offered_advisor_flag_fails_closed() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag="omitted"))
+
+    with pytest.raises(ModelTierRunError, match="--advisor"):
+        validate_model_tier_run(run)
+
+
+def test_codex_astra_success_without_advisor_flag_record_fails_closed() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag=None))
+
+    with pytest.raises(ModelTierRunError, match="advisor_flag"):
+        validate_model_tier_run(run)
+
+
+def test_unknown_advisor_flag_state_is_rejected() -> None:
+    run = _codex_astra_success_run(_native_codex_evidence(advisor_flag="skipped"))
+
+    with pytest.raises(ModelTierRunError, match="advisor_flag"):
+        validate_model_tier_run(run)
+
+
 def test_broken_bind_keeps_fallback_evidence_separate_from_reference_gap() -> None:
     evidence = _native_codex_evidence()
     evidence["fallback"] = {
@@ -136,6 +183,38 @@ def test_cli_reads_versioned_advisor_evidence(tmp_path: Path) -> None:
     assert loaded_run.evidence["consult"]["report_back_status"] == "recorded"
 
 
+def test_non_object_evidence_reports_the_same_message_at_validate_and_load(
+    tmp_path: Path,
+) -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        host_profile="Codex",
+        evidence=["not", "an", "object"],
+    )
+    with pytest.raises(ModelTierRunError, match=EVIDENCE_MUST_BE_OBJECT_MESSAGE):
+        validate_model_tier_run(run)
+
+    log_path = tmp_path / "model-tier-run.json"
+    log_path.write_text(
+        json.dumps(
+            {
+                "own_tier": "Opus",
+                "candidate_tiers": [ADVISOR_MODEL_TIER],
+                "attempts": [{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+                "selected_tier": ADVISOR_MODEL_TIER,
+                "host_profile": "Codex",
+                "evidence": "not an object",
+            }
+        ),
+        encoding="utf-8",
+    )
+    with pytest.raises(TypeError, match=EVIDENCE_MUST_BE_OBJECT_MESSAGE):
+        load_model_tier_run_from_json_path(from_path=log_path)
+
+
 def test_clean_single_spawn_at_top_of_slice_passes() -> None:
     run = ModelTierRun(
         own_tier="Opus",

package/_shared/pr-loop/scripts/terminology_sweep.py

@@ -175,9 +175,7 @@ def _collect_introduced_identifiers(
     """
     all_identifier_tuples: set[IdentifierTuple] = set()
     for each_file_path, _, each_text in all_added_lines:
-        if _file_extension(
-            each_file_path
-        ) in ALL_SWEEP_CODE_FILE_EXTENSIONS and not _is_test_file(each_file_path):
+        if _is_swept_non_test_code_file(each_file_path):
             all_identifier_tuples.update(_identifier_tuples_in_text(each_text))
     return frozenset(all_identifier_tuples)
 
@@ -301,6 +299,13 @@ def _is_test_file(file_path: str) -> bool:
     )
 
 
+def _is_swept_non_test_code_file(file_path: str) -> bool:
+    """Return whether a diff path names a swept code file outside a test module."""
+    return _file_extension(
+        file_path
+    ) in ALL_SWEEP_CODE_FILE_EXTENSIONS and not _is_test_file(file_path)
+
+
 def _comment_fragments(line_text: str) -> list[str]:
     """Return the comment tail of a code line, or an empty list when absent."""
     all_fragments: list[str] = []
@@ -616,9 +621,7 @@ def _stem_identifier_tuple_for_code_file(each_file_path: str) -> IdentifierTuple
     ``None`` when the path is not a swept code file, is a test file, or its
     stem carries fewer than the minimum identifier token count.
     """
-    if _file_extension(each_file_path) not in ALL_SWEEP_CODE_FILE_EXTENSIONS or _is_test_file(
-        each_file_path
-    ):
+    if not _is_swept_non_test_code_file(each_file_path):
         return None
     stem_tuple = _identifier_token_tuple(Path(each_file_path).stem)
     if len(stem_tuple) < MINIMUM_IDENTIFIER_TOKEN_COUNT:
@@ -747,9 +750,7 @@ def _identifier_names_on_added_code_lines(diff_text: str) -> frozenset[str]:
     """
     all_names: set[str] = set()
     for each_file_path, _, each_text in _parse_added_lines(diff_text):
-        if _file_extension(
-            each_file_path
-        ) not in ALL_SWEEP_CODE_FILE_EXTENSIONS or _is_test_file(each_file_path):
+        if not _is_swept_non_test_code_file(each_file_path):
             continue
         all_found_names = SNAKE_CASE_IDENTIFIER_PATTERN.findall(each_text)
         all_found_names += CAMEL_CASE_IDENTIFIER_PATTERN.findall(each_text)

package/_shared/pr-loop/scripts/tests/test_terminology_sweep.py

@@ -759,3 +759,16 @@ def test_flags_near_miss_when_second_leading_token_is_plural_variant() -> None:
     findings = sweep_diff(diff)
     assert len(findings) == 1
     assert "retry policies limit" in findings[0]
+
+
+def test_a_swept_code_file_outside_the_test_modules_reads_as_swept() -> None:
+    assert sweep_module._is_swept_non_test_code_file("api/store.py") is True
+
+
+def test_a_test_module_does_not_read_as_a_swept_code_file() -> None:
+    assert sweep_module._is_swept_non_test_code_file("api/test_store.py") is False
+    assert sweep_module._is_swept_non_test_code_file("api/tests/store.py") is False
+
+
+def test_a_markdown_document_does_not_read_as_a_swept_code_file() -> None:
+    assert sweep_module._is_swept_non_test_code_file("docs/README.md") is False

package/bin/install.test.mjs

@@ -2928,6 +2928,31 @@ test('retired skills leave install groups and stay in the cleanup registry', ()
     }
 });
 
+test('the README agents section names the shipped agent, not archived personal agents', () => {
+    const readme = readFileSync(new URL('../../../README.md', import.meta.url), 'utf8');
+    const agentsSection = readme.slice(
+        readme.indexOf('### Agents'),
+        readme.indexOf('### Commands'),
+    );
+    assert.match(agentsSection, /`poteto-agent`/);
+    for (const archivedAgentName of [
+        'clean-coder',
+        'code-quality-agent',
+        'git-commit-crafter',
+        'issue-tracker',
+        'plan-packet-validator',
+        'pr-description-writer',
+        'session-advisor',
+        'skill-writer-agent',
+    ]) {
+        assert.equal(
+            agentsSection.includes(`\`${archivedAgentName}\``),
+            false,
+            `${archivedAgentName} is archived and should not appear as a shipped agent`,
+        );
+    }
+});
+
 test('the README names current session tools', () => {
     const readme = readFileSync(new URL('../../../README.md', import.meta.url), 'utf8');
     assert.doesNotMatch(readme, /--only journal|session-log|session-tidy/);

package/docs/high-trust-agent-delivery.md

@@ -0,0 +1,132 @@
+# Building a high trust system for agent driven software delivery
+
+Source: https://x.com/poteto/status/2102050467505430555/video/1
+
+This document carries the model behind [`rules/correction-lens.md`](../rules/correction-lens.md).
+
+## The central idea
+
+Lauren's 2,000 pull requests came after she built a system that let agents do useful work while she was away.
+
+The system had several parts. The codebase showed agents the preferred patterns. Tools let agents run the product and gather evidence. Continuous integration, or CI, checked every proposed change. Rules and review bots caught repeated mistakes. Skills taught agents how to perform work in the team's preferred way. Automations connected incoming problems to agents that could investigate them.
+
+These parts created trust over time. An agent earned more freedom by showing that it could make a change, check the result, respond to failures, and open a pull request that met the repository's standards.
+
+The goal for a repository is clear. An agent should be able to take a task through the full path to a pull request. The repository should provide enough evidence for a merge decision without requiring a person to inspect every changed line.
+
+## Why high volume exposes weak systems
+
+When people first work with agents, they often watch every conversation. They correct the agent's approach, stop mistakes, and supply missing context. That works for a small number of tasks. It breaks when many agents work at the same time.
+
+A large group of agents multiplies whatever the repository already permits. If the checks are weak, the team receives many noisy pull requests. Regressions and bugs spread faster. The team spends its time repairing agent output, and the product waits.
+
+The answer is to build trust before adding more agents. Start with a small workflow that an agent can repeat. Watch the failures. Turn each repeated correction into a stronger control. Increase the number of agents after the controls catch the common mistakes.
+
+The high pull request count is the result of this work. The first target is a system that can check changes without waiting for one person.
+
+## Verification gives the agent evidence
+
+Verification asks whether the code does what the feature needs. A checkout button should complete a checkout. A changed screen should respond to the user's action. A performance change should meet a measured limit.
+
+Teach the agent how to start the product, reach a feature, perform the relevant action, and inspect the result. The agent can collect a browser trace, a memory snapshot, a test result, or a performance measurement. The evidence should come from a repeatable procedure.
+
+A useful verification setup has two parts. The first is a command line tool that runs the product and collects the required evidence. The second is a feature map that explains how the product works.
+
+The command line tool gives every agent session the same procedure. Agents do not invent a new test script for every task. The tool supplies the commands, inputs, and output format. Invest in the important product paths so the tool can handle the work agents perform often.
+
+The feature map gives the agent context that a short bug report often lacks. It describes the product's features, the paths a user takes to reach them, the controls that matter, and the expected result. Keep the map with the repository and maintain it as the product changes.
+
+The tool and the map work together. The agent can reproduce a report, inspect the product, collect evidence, and explain the result. This turns verification into a shared team capability.
+
+Verification does not answer every quality question. It shows that the feature works during the check. It does not by itself show that the code is easy to maintain, that the performance will stay within limits, or that the change follows the team's design rules.
+
+Add skills for those questions. A skill can teach an agent how to debug, develop a feature, refactor code, inspect performance, or review a change. Keep the skills in a shared repository. Combine them with verification so the agent can check behavior and code quality.
+
+Measured data makes this process stronger. Performance numbers, memory measurements, error counts, and test results give the agent something to inspect. The agent can respond to a number more reliably than to a vague instruction such as "make this faster."
+
+## The codebase is part of the control system
+
+Agents extend the patterns they find in the files they read. The codebase becomes working memory for the agent. An agent usually adapts an existing structure to a new task. It rarely redesigns the whole system during each pull request.
+
+This gives the codebase a direct effect on future changes. One clear pattern reduces guessing. Several conflicting patterns force the agent to choose. The repository should make the safe choice easy to find and easy to repeat.
+
+Start with the code structure. Change the design so that a bad pattern cannot be expressed, or so that the preferred pattern is the easiest path. Good data structures and clear boundaries can remove entire classes of errors.
+
+Make each feature easy to locate. Define where its code lives. Define how it connects to other parts of the product. Define which parts may import each other. A clear layout gives the agent a smaller search space and fewer decisions.
+
+The framework Lauren describes follows this idea. It sets conventions for code location and dependency boundaries. A performance problem caused by code crossing into the wrong process can become impossible through import rules. The method carries. Put team knowledge into code structure so agents find it while they work.
+
+Strict conventions may feel inconvenient to people who already know the system. They help agents and new contributors because the repository answers more questions by itself. A designer, product manager, or busy engineer can ask an agent to make a change and still benefit from the same safe paths.
+
+## Build controls in layers
+
+The controls work best in a clear order. Each layer handles a different kind of mistake.
+
+First, make the mistake impossible through the code structure, architecture, or data model. This is the strongest control because the agent cannot choose the bad pattern.
+
+Second, add static checks. Linters, compiler diagnostics, type checks, and CI inspect every proposed change. Continuous integration means that the repository runs the required checks for each pull request. When an agent repeats a mistake, turn the mistake into a check that runs every time.
+
+Third, add rules, automated review, and skills. These explain how the team wants work done. They help with decisions that are difficult to encode in code or static checks. A rule can describe a preferred pattern. A review bot can point out a problem. A skill can give the agent a repeatable procedure.
+
+Fourth, keep human review for judgment that the lower layers cannot express. People can decide whether a change fits the product, whether the design is sound, or whether a tradeoff is acceptable. People should not spend every review repeating the same correction that a check could catch.
+
+Every repeated review comment is evidence that a lower layer needs improvement. Move that lesson into the code structure, a static check, CI, an automated review, or a skill. This gives the next agent the lesson without requiring a person to repeat it.
+
+## Turn corrections into repository improvements
+
+An agent correction should change the system when the same mistake can happen again. Fixing one pull request removes one symptom. Adding a control protects later pull requests.
+
+Suppose an agent copies a workaround. Remove the workaround where possible. Add a rule that prevents new copies. Add a skill that explains the preferred solution. Ask an agent to clean the old copies so the repository presents better examples.
+
+Lauren gives comments as one example. Comments can explain an edge case or a temporary workaround. In the Cursor codebase, agents began using comments as permission to keep workarounds, and the underlying problem stayed. The team chose to ban comments in Dune so agents would stop copying that pattern.
+
+The same reasoning applies to any pattern that creates poor code. When a pattern keeps appearing, decide which control should own the correction. Put the knowledge in the repository, where every later session reads it.
+
+This maintenance role is like gardening. Someone needs to look for small workarounds, weak patterns, and new code debt before they spread. That person removes old debt, keeps one conventional path for common work, and adds a check when a bad pattern appears.
+
+The standard is simple. Keep the repository in a state that you would want an agent to copy. Every example teaches the next agent what to do.
+
+## The inner delivery loop
+
+The inner loop is the path from a task to a pull request. A dependable repository gives the agent a repeatable sequence.
+
+1. The agent receives a task with enough context to identify the relevant feature and code.
+2. The agent makes the smallest change that solves the task.
+3. The agent runs the product or the relevant tests through the shared verification tools.
+4. The agent collects evidence about behavior, performance, and other required limits.
+5. CI, static checks, repository rules, and automated review inspect the change.
+6. The agent responds to failures, repairs the change, and runs the checks again.
+7. The agent opens or updates the pull request with the evidence.
+8. The repository grants merge permission after the required checks pass and the remaining judgment calls are settled.
+
+The agent earns freedom through this loop. The system depends on the agent producing evidence that the repository can inspect.
+
+## The outer delivery loop
+
+Work can begin outside the code editor. A message, error report, performance alert, or product signal can start the next task.
+
+Connect an agent to the tools that hold this information. The talk mentions Slack, an error tracker, performance data, and a database service. The exact tools depend on the repository. The important point is that the agent can gather enough context to decide what happened and what task should follow.
+
+A routine can watch a message or an alert and start an agent. The agent can reproduce the problem, make a change, run the checks, and open a pull request. Other bots can call the same verification tools, repository rules, and skills for more complex work.
+
+A set of small connections can start useful work. The repository supplies the controls. The agent calls the tools. CI and review inspect the result.
+
+## How the pieces compound
+
+Each control improves the next one. A clear code pattern gives the agent a safe starting point. The verification tool gives it product evidence. CI catches repeatable mistakes. Automated review finds code quality problems. Skills give the agent procedures for work that needs more judgment. The outer loop supplies new tasks.
+
+Together, these controls let many agents work in parallel. The agents do not need a person to approve every small action because the environment checks the work. People can focus on product decisions, system design, and questions that the checks cannot settle.
+
+The result is a repository where an agent with limited context can still make a good change. The environment carries the team's knowledge. The agent follows the safe paths. The pull request provides evidence for its merge decision.
+
+## A practical way to apply the model
+
+Start with one recurring task. Give an agent a fixed way to run the relevant part of the product and collect evidence. Record the expected result. Run the same procedure for several changes and study the failures.
+
+When a failure repeats, ask where the correction belongs. Change the code structure if the pattern can be removed. Add a static check or CI step if the problem can be detected. Add a rule, review bot, or skill when the decision needs guidance. Improve human review when the question still needs judgment.
+
+Keep the codebase clean as the agent population grows. Remove workarounds. Reduce competing patterns. Add one clear path for common work. Maintain the feature map and verification tools as part of the repository.
+
+Then connect incoming signals to the same workflow. Let an agent start from a bug report or alert, reproduce the problem, make the change, run the checks, and open the pull request. Increase parallel work after the system can catch the mistakes that matter.
+
+The key lesson is to move knowledge out of individual conversations and into the environment. A person teaches the system once. The repository, checks, tools, and skills carry that lesson into every later pull request.

package/docs/references/advisor-tool.md

@@ -40,7 +40,7 @@ Work a disagreement in this order: keep the observed evidence in the record, nam
 
 ## Recovery record
 
-Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"` and `reply_path: "native"`.
+Keep one versioned `evidence` object in the session-controlled `model-tier-run.json` record. A missing optional reference belongs in `reference.status`; it keeps the bind result independent. `fallback_kind: "broken"` identifies a bind or reply failure. On a Codex host, a successful native route records `selected_tier: "Astra"`, `reply_path: "native"`, and `advisor_flag`. The value is `"passed"` when the spawn tool offers the `--advisor` flag and the spawn passed it, or `"unavailable"` when the spawn tool has no flag field. `"omitted"` fails the bind.
 
 ```json
 {
@@ -56,7 +56,8 @@ Keep one versioned `evidence` object in the session-controlled `model-tier-run.j
       "selected_tier": "Astra",
       "fallback_kind": null,
       "fallback_reason": null,
-      "reply_path": "native"
+      "reply_path": "native",
+      "advisor_flag": "passed"
     },
     "consult": {
       "changed_evidence": ["native bind returned a reply"],

package/docs/second-claude-account.md

@@ -0,0 +1,50 @@
+# Second Claude account
+
+A second Claude subscription runs agents on the same machine as the main one. It
+shares every skill, rule, plugin, setting and doc in the main Claude home, and it
+keeps its own sign-in and history.
+
+## Pieces
+
+| File | What it does |
+|---|---|
+| `scripts/claude_account_profile.py` | Links each shared entry of `~/.claude` into the profile `~/.claude-profiles/ev`, moves stale copies into `.replaced/<time>/`, and writes the `claude-ev.cmd` launcher into `~/.local/bin` |
+| `scripts/claude_account_choice.py` | Reads both accounts' 5-hour and weekly meters and prints which account a job runs on |
+| `scripts/dev_env_scripts_constants/claude_account_constants.py` | The profile name, the entries that stay per account, and the picker thresholds |
+
+The launcher sets `CLAUDE_CONFIG_DIR` to the profile and passes every argument to
+`claude`, so `claude-ev -p "..."` runs like `claude -p "..."` on the second
+account.
+
+These entries stay per account and are never linked: `.credentials.json` and
+`.claude.json` with their backups, `projects`, `sessions`, `todos`, `history.jsonl`,
+and the other state folders named in the constants file.
+
+## Sign in once
+
+```
+python packages/claude-dev-env/scripts/claude_account_profile.py
+claude-ev auth login
+```
+
+The sign-in lives in `~/.claude-profiles/ev/.credentials.json` on that machine.
+Claude refreshes it on each run.
+
+## Which account a job uses
+
+The main account belongs to the person who works on it, so a job borrows it only
+to spend leftover usage that expires soon.
+
+| Condition | Account |
+|---|---|
+| Main week resets within 24 hours, main under 90% of its week, main under 50% of its 5-hour window | main |
+| Otherwise, second under 95% of its week and under 90% of its 5-hour window | second |
+| Second meter unreadable | second, whose own run refreshes the sign-in |
+| Otherwise | wait, with the next reset time |
+
+An unreadable main meter never picks main.
+
+```
+python packages/claude-dev-env/scripts/claude_account_choice.py
+{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "..."}
+```

package/hooks/advisory/refactor_guard.py

@@ -23,14 +23,14 @@ try:
         sys.path.insert(0, hooks_root_directory)
 
     from hooks_constants.multi_edit_reconstruction import edits_for_tool
-    from hooks_constants.precommit_code_rules_gate_constants import GIT_COMMAND_TIMEOUT_SECONDS
     from hooks_constants.refactor_guard_constants import (
         ALL_PYTHON_KEYWORDS,
         CHANGED_SURFACE_MATCH_RATIO,
+        GIT_COMMAND_TIMEOUT_SECONDS,
+        GIT_EXECUTABLE_TOKEN,
         MAXIMUM_REFACTOR_LINE_DELTA,
         REFACTOR_LINE_DELTA_DIVISOR,
     )
-    from hooks_constants.session_edit_stage_gate_constants import GIT_EXECUTABLE_TOKEN
 except ImportError as import_error:
     raise ImportError(
         "refactor_guard: cannot import its sibling modules; "

package/hooks/advisory/test_refactor_guard.py

@@ -125,3 +125,24 @@ def test_untracked_probe_should_start_without_a_console_window(
 
     assert refactor_guard.is_new_file(str(tmp_path / "module.py")) is True
     assert all_recorded_keyword_arguments["creationflags"] == EXPECTED_HIDDEN_WINDOW_FLAGS
+
+
+def test_the_git_query_carries_the_advisory_s_own_executable_and_timeout(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """refactor_guard_constants supplies both names the git call is built from."""
+    all_calls: list[tuple[list[str], object]] = []
+
+    def record_call(
+        command: list[str], **keyword_arguments: object
+    ) -> subprocess.CompletedProcess[str]:
+        all_calls.append((command, keyword_arguments["timeout"]))
+        return subprocess.CompletedProcess(command, 1, "", "")
+
+    monkeypatch.setattr(refactor_guard.subprocess, "run", record_call)
+
+    refactor_guard.is_new_file(str(tmp_path / "module.py"))
+
+    command, timeout = all_calls[0]
+    assert command[:2] == ["git", "ls-files"]
+    assert timeout == refactor_guard.GIT_COMMAND_TIMEOUT_SECONDS