claude-dev-env 4.3.0 → 7.0.0

package/.agents/skills/pull-request/reference/publication-tasks.md

@@ -6,11 +6,11 @@ reason when the task is conditional. This file is a task seed catalog, not a
 markdown progress board.
 
 1. Resolve one repository, action, and selected author. For create, resolve the source branch, base, and head. For other actions, resolve one existing pull request target. Create actions publish drafts.
-2. Invoke the required `pr-description-writer` for create or full body rewrite, then record its title and body file. `pr-title-description` may assist. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
+2. Invoke the required `pr-description-writer` for create or full body rewrite, then record its title and body file. Mark `N/A` for comment or review bodies that do not rewrite the pull request description.
 3. Validate every title, body, artifact, and local path input. Reject inline body input.
-4. Run `_shared/pr-loop/scripts/durable_post_lint.py` for the matching action and record exit code `0` before credential lookup or network work.
+4. Resolve the active managed root and run `<managed-root>/scripts/durable_post_lint.py` for the matching action. Record exit code `0` before credential lookup or network work.
 5. Run `privacy-hygiene` before the GitHub post and record its clean result.
-6. Upload binary evidence through `scripts/gh_artifact_upload.py`, replace local references with permanent URLs, and rerun the shared body linter. Mark `N/A` when no binary evidence exists.
+6. Upload binary evidence through `scripts/gh_artifact_upload.py`, replace local references with permanent URLs, and rerun the body linter. Mark `N/A` when no binary evidence exists.
 7. Resolve the selected author in the child process environment and prove that the parent environment and global `gh` account remain unchanged.
 8. Run `.agents/skills/pull-request/scripts/pull_request.py` for exactly one action: `create`, `edit`, `comment`, or `review`.
 9. When the user selects a legacy state file, run `recover_legacy_author.py <exact-state-file> --confirm-inactive` for exactly that record. Preserve every other record and delete the selected record only after successful restore. Mark `N/A` otherwise.

package/.agents/skills/pull-request/scripts/github_pr_command_constants/config/constants.py

@@ -29,13 +29,21 @@ ALL_LINTER_ACTIONS_BY_COMMAND: dict[str, str] = {
 }
 
 SELECTED_ACCOUNT_ENVIRONMENT_KEY = "GITHUB_DEFAULT_ACCOUNT"
+CONFIG_DIR_OVERRIDE_ENVIRONMENT_KEY = "CLAUDE_CONFIG_DIR"
+DEFAULT_MANAGED_ROOT_DIRECTORY_NAME = ".claude"
+ALL_DURABLE_POST_LINTER_RELATIVE_PATH_PARTS = ("scripts", "durable_post_lint.py")
+GITHUB_TOKEN_ENVIRONMENT_KEY = "GITHUB" + "_TOKEN"
+GH_TOKEN_ENVIRONMENT_KEY = "GH" + "_TOKEN"
+ALL_GITHUB_AUTHORIZATION_ENVIRONMENT_KEYS = (
+    GITHUB_TOKEN_ENVIRONMENT_KEY,
+    GH_TOKEN_ENVIRONMENT_KEY,
+)
 
 ACCOUNT_LOOKUP_FAILED_MESSAGE = "error: GitHub account lookup failed\n"
 ACCOUNT_LOOKUP_EMPTY_MESSAGE = "error: GitHub account lookup returned no value\n"
 ACTION_FAILED_MESSAGE = "error: GitHub action failed\n"
 ACCOUNT_LOOKUP_FAILURE_EXIT_CODE = 1
 PACKAGE_ROOT_PARENT_INDEX = 4
-SKILLS_DIRECTORY_PARENT_INDEX = 2
 
 ALL_GH_AUTH_SWITCH_COMMAND_HEAD: tuple[str, ...] = (
     "gh",

package/.agents/skills/pull-request/scripts/pull_request.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import importlib
 import os
 import subprocess
 import sys
@@ -19,12 +18,17 @@ from github_pr_command_constants.config.constants import (
     ACTION_EDIT,
     ACTION_FAILED_MESSAGE,
     ACTION_REVIEW,
+    ALL_DURABLE_POST_LINTER_RELATIVE_PATH_PARTS,
+    ALL_GITHUB_AUTHORIZATION_ENVIRONMENT_KEYS,
     ALL_LINTER_ACTIONS_BY_COMMAND,
     ALL_REVIEW_FLAGS_BY_EVENT,
+    CONFIG_DIR_OVERRIDE_ENVIRONMENT_KEY,
+    DEFAULT_MANAGED_ROOT_DIRECTORY_NAME,
+    GH_TOKEN_ENVIRONMENT_KEY,
+    GITHUB_TOKEN_ENVIRONMENT_KEY,
     PACKAGE_ROOT_PARENT_INDEX,
     REVIEW_EVENT_COMMENT,
     SELECTED_ACCOUNT_ENVIRONMENT_KEY,
-    SKILLS_DIRECTORY_PARENT_INDEX,
 )
 
 CommandRunner = Callable[..., subprocess.CompletedProcess[str]]
@@ -60,17 +64,33 @@ def _build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _linter_path() -> Path:
-    return (
-        Path(__file__).resolve().parents[SKILLS_DIRECTORY_PARENT_INDEX]
-        / "_shared/pr-loop/scripts/durable_post_lint.py"
+def _configured_managed_root(all_environment: Mapping[str, str]) -> Path:
+    configured_root_text = all_environment.get(CONFIG_DIR_OVERRIDE_ENVIRONMENT_KEY, "").strip()
+    if not configured_root_text:
+        return Path.home() / DEFAULT_MANAGED_ROOT_DIRECTORY_NAME
+    configured_root = Path(configured_root_text).expanduser()
+    if configured_root.is_absolute():
+        return configured_root
+    return Path.home() / configured_root
+
+
+def _linter_path(all_environment: Mapping[str, str]) -> Path:
+    source_candidate = Path(__file__).resolve().parents[PACKAGE_ROOT_PARENT_INDEX].joinpath(
+        *ALL_DURABLE_POST_LINTER_RELATIVE_PATH_PARTS
+    )
+    if source_candidate.is_file():
+        return source_candidate
+    return _configured_managed_root(all_environment).joinpath(
+        *ALL_DURABLE_POST_LINTER_RELATIVE_PATH_PARTS
     )
 
 
-def _linter_arguments(arguments: argparse.Namespace) -> list[str]:
+def _linter_arguments(
+    arguments: argparse.Namespace, all_environment: Mapping[str, str]
+) -> list[str]:
     all_arguments = [
         sys.executable,
-        str(_linter_path()),
+        str(_linter_path(all_environment)),
         "--action",
         ALL_LINTER_ACTIONS_BY_COMMAND[arguments.action],
     ]
@@ -138,28 +158,9 @@ def _post_arguments(arguments: argparse.Namespace) -> list[str]:
     ]
 
 
-def _shared_environment_key_names() -> tuple[str, str, tuple[str, ...]]:
-    shared_directory = (
-        Path(__file__).resolve().parents[PACKAGE_ROOT_PARENT_INDEX]
-        / "_shared/pr-loop/scripts"
-    )
-    shared_directory_text = str(shared_directory)
-    if shared_directory_text not in sys.path:
-        sys.path.insert(0, shared_directory_text)
-    constants_module = importlib.import_module(
-        "pr_loop_shared_constants.post_audit_thread_constants"
-    )
-    return (
-        constants_module.GITHUB_TOKEN_ENV_VAR_NAME,
-        constants_module.GH_TOKEN_ENV_VAR_NAME,
-        constants_module.ALL_GH_TOKEN_ENV_VAR_NAMES,
-    )
-
-
 def _lookup_environment(all_environment: Mapping[str, str]) -> dict[str, str]:
     lookup_environment = dict(all_environment)
-    _, _, all_authorization_names = _shared_environment_key_names()
-    for each_name in all_authorization_names:
+    for each_name in ALL_GITHUB_AUTHORIZATION_ENVIRONMENT_KEYS:
         lookup_environment.pop(each_name, None)
     return lookup_environment
 
@@ -203,12 +204,9 @@ def _action_environment(
     )
     if account_authorization is None:
         return None
-    parent_authorization_name, child_authorization_name, _ = (
-        _shared_environment_key_names()
-    )
     action_environment = dict(all_environment)
-    action_environment.pop(parent_authorization_name, None)
-    action_environment[child_authorization_name] = account_authorization
+    action_environment.pop(GITHUB_TOKEN_ENVIRONMENT_KEY, None)
+    action_environment[GH_TOKEN_ENVIRONMENT_KEY] = account_authorization
     return action_environment
 
 
@@ -247,19 +245,10 @@ def main(
     all_environment: Mapping[str, str],
     command_runner: CommandRunner,
 ) -> int:
-    """Run one validated pull request action.
-
-    Args:
-        all_arguments: Command arguments after the script name.
-        all_environment: Parent environment copied for child processes.
-        command_runner: Process runner used by tests and production.
-
-    Returns:
-        The linter, account lookup, or GitHub action exit status.
-    """
+    """Run one validated pull request action."""
     arguments = _build_parser().parse_args(list(all_arguments))
     completed_lint = command_runner(
-        _linter_arguments(arguments), check=False, shell=False
+        _linter_arguments(arguments, all_environment), check=False, shell=False
     )
     if completed_lint.returncode != 0:
         return completed_lint.returncode

package/.agents/skills/pull-request/scripts/test_github_pr_command_constants.py

@@ -34,6 +34,15 @@ def test_account_boundary_constants_are_safe_and_stable() -> None:
     assert constants.ACCOUNT_LOOKUP_EMPTY_MESSAGE.endswith("returned no value\n")
 
 
+def test_durable_post_linter_location_uses_managed_root() -> None:
+    assert constants.CONFIG_DIR_OVERRIDE_ENVIRONMENT_KEY == "CLAUDE_CONFIG_DIR"
+    assert constants.DEFAULT_MANAGED_ROOT_DIRECTORY_NAME == ".claude"
+    assert constants.ALL_DURABLE_POST_LINTER_RELATIVE_PATH_PARTS == (
+        "scripts",
+        "durable_post_lint.py",
+    )
+
+
 def test_legacy_recovery_constants_define_one_record_boundary() -> None:
     assert constants.ALL_GH_AUTH_SWITCH_COMMAND_HEAD == (
         "gh",

package/.agents/skills/pull-request/scripts/test_pull_request.py

@@ -25,9 +25,7 @@ PR_TITLE = "feat(skills): add guarded pull request publication"
 ACCOUNT_A = "JonEcho"
 ACCOUNT_B = "ReviewBot"
 BODY_FILENAME = "pull-request-body.md"
-LINTER_PATH = (
-    _SCRIPTS_DIRECTORY.parents[1] / "_shared/pr-loop/scripts/durable_post_lint.py"
-)
+LINTER_PATH = _SCRIPTS_DIRECTORY.parents[3] / "scripts/durable_post_lint.py"
 COMMENT_CLI = ["comment", "--repo", REPOSITORY, "--number", PR_NUMBER, "--body-file"]
 ACTION_CASES = [
     (

package/.agents/skills/skill-builder/SKILL.md

@@ -1,202 +1,9 @@
 ---
 name: skill-builder
 disable-model-invocation: true
-description: >-
-  Skill lifecycle: classify, scaffold, write via the skill-writer-agent, self-audit, compose
-  sub-skills, polish description triggers, enforce deterministic scripts. Triggers:
-  build a skill, new skill workflow, improve this skill, optimize skill description,
-  skill development lifecycle, skill modularity, skill composition, description
-  trigger catalog, deterministic skill scripts.
+description: Placeholder for the skill-builder rework to follow pstack philosophy.
 ---
 
-# Skill Builder
+# Skill builder
 
-**Core principle:** Best-practice-driven craftsman. Knows every proven pattern, applies them intentionally, self-audits after building. The expert that enforces craft standards.
-
-Sources: [Anthropic best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices), [Lessons from Building Claude Code](references/thariq-x-post-skills.json), model skills (bugteam, pr-converge).
-
-## Gotchas
-
-Highest-signal content. Append a bullet each time a skill build fails in a new way.
-
-> "The highest-signal content in any skill is the Gotchas section. These sections should be built up from common failure points that Claude runs into when using your skill."
-
-- Story-form `description` burns always-on context and weakens selection — rewrite to capability stem + `Triggers:` list (`description-field.md`).
-- Multi-capability packages fail modularity audit — split or thin orchestrator + named sub-skills (`skill-modularity.md`).
-- Skipping the composition plan before Write reintroduces silent reimplementation of peer skills.
-- Deterministic steps written only as prose (fenced source, giant `rg` lines, multi-step mechanical sequences) fail audit — extract to `scripts/` / `workflow/` / `templates/` / `reference/` (`deterministic-elements.md`).
-- Markdown `- [ ]` checklists as the agent's progress board fail audit when a task tool exists — seed tasks via `TaskCreate` / `TodoWrite` (`deterministic-elements.md`).
-
-## When this skill applies
-
-Trigger for requests to **build**, **improve**, or **polish** a skill. This skill orchestrates the process — it classifies, scaffolds, gathers context, delegates writing to the `skill-writer-agent` agent, and self-audits the result.
-
-For quick skill syntax questions or one-off SKILL.md edits, spawn the `skill-writer-agent` agent directly.
-
-**Refusal cases — first match wins:**
-
-- **No clear task or domain.** Respond exactly: `What should this skill do? Give me a one-sentence description of the capability.`
-
-## The Process
-
-Each workflow file provides step-by-step instructions. After routing below, open the corresponding workflow file and follow it.
-
-### Routing
-
-Assess the user’s intent:
-
-**Creating a new skill?**
-Read `${CLAUDE_SKILL_DIR}/workflows/new-skill.md` and follow it.
-
-**Improving an existing skill?**
-Read `${CLAUDE_SKILL_DIR}/workflows/improve-skill.md` and follow it.
-
-**Final polish only (description optimization, trigger audit)?**
-Read `${CLAUDE_SKILL_DIR}/workflows/polish-skill.md` and follow it.
-
-**Ambiguous?** Ask: "Are you creating a new skill, improving an existing one, or doing a final polish pass?"
-
-### The Claude A / Claude B pattern
-
-You and the user are **Claude A** — the expert who designs and refines the skill. Subagents running the built skill on real tasks are **Claude B** — the agent using the skill to perform actual work.
-
-> "Work with one instance of Claude (‘Claude A’) to create a Skill that is used by other instances (‘Claude B’). Claude A helps you design and refine instructions, while Claude B tests them in real tasks."
-
-The feedback loop: observe Claude B’s behavior, bring insights back, refine the skill, test again.
-
-## Skill type routing
-
-> "After cataloging all of our skills, we noticed they cluster into a few recurring categories."
-
-Classify into one of 9 types — type sets folder structure. Taxonomy and layouts: [`references/skill-types.md`](references/skill-types.md).
-
-## Principles
-
-These are non-negotiable. Every skill must satisfy them. Enforce via [`references/self-audit-checklist.md`](references/self-audit-checklist.md).
-
-### Concision and defaults
-
-> "Default assumption: Claude is already very smart. Only add context Claude doesn’t already have."
-
-> "Don’t State the Obvious — focus on information that pushes Claude out of its normal way of thinking."
-
-Challenge each sentence: "Does Claude really need this?"
-
-### Degree of freedom
-
-> "Match the level of specificity to the task’s fragility and variability."
-
-High freedom (text guidance) for open fields. Low freedom (exact scripts, no parameters) for narrow bridges with cliffs.
-
-> "Avoid Railroading Claude — give Claude the information it needs, but give it the flexibility to adapt."
-
-### Progressive disclosure
-
-Hub pattern, line caps, one-level references, TOC and path rules: [`references/progressive-disclosure.md`](references/progressive-disclosure.md).
-
-### Modularity and composition
-
-One skill = one capability. Multi-step work invokes **sub-skills** (peer skills) by name. Prefer compose over reimplement. Full rules: [`references/skill-modularity.md`](references/skill-modularity.md).
-
-> "You can just reference other skills by name, and the model will invoke them if they are installed."
-
-New-skill Gather records a composition plan before write. Self-audit modularity items are mandatory.
-
-### Description field (trigger catalog)
-
-The frontmatter `description` is **selection metadata** pre-loaded for every skill. Write a **trigger catalog**, not a story: short capability stem + concrete trigger phrases. No narrative, benefits language, or process dump.
-
-Full rules: [`references/description-field.md`](references/description-field.md). Polish workflow Step 1 is the dedicated rewrite pass.
-
-> "The description field is not a summary — it’s a description of when to trigger."
-
-### Gotchas
-
-Mandatory highest-signal section (see Gotchas above). Capture real failure modes; self-audit requires the section present and actionable.
-
-### Templates and examples
-
-> "Provide templates for output format" and "Examples help Claude understand the desired style and level of detail more clearly than descriptions alone."
-
-Use the template pattern for structured outputs. Use the examples pattern (input/output pairs) for style-dependent work.
-
-### Workflows and task seeds
-
-Multi-step required work is a **task seed list** (plain bullets in a reference file) plus an instruction to register each item on the host task tool (`TaskCreate`, `TodoWrite`, or equivalent). Agents work the task list and mark complete with evidence.
-
-Do **not** ship markdown `- [ ]` boards as the completion protocol when a task tool is available. Do **not** say "copy this checklist into your response and check it off."
-
-Quality-critical operations still use feedback loops (run validator → fix → repeat). Spec: [`references/deterministic-elements.md`](references/deterministic-elements.md) (Task-tool tracking).
-
-### Scripts
-
-> "Handle error conditions rather than punting to Claude." "Make clear whether Claude should execute the script or read it as reference."
-
-> "One of the most powerful tools you can give Claude is code — letting Claude spend its turns on composition rather than reconstructing boilerplate."
-
-### Deterministic elements (mandatory classification)
-
-Any skill element that is **deterministic** (same inputs → same outputs; machine-checkable success) ships as code, a fixed artifact, or a **session task seed** — not prose-only steps or markdown checkbox boards. Judgment, routing, and refusals stay in markdown.
-
-Full rules, inventory table, task-tool tracking, CODE_RULES bar for skill scripts, and anti-patterns: [`references/deterministic-elements.md`](references/deterministic-elements.md).
-
-New-skill Gather records a deterministic-elements inventory before write. Self-audit items register as session tasks and are mandatory on every delivery (pure-judgment skills mark script rows N/A with evidence).
-
-### Setup and memory
-
-> "Think through the Setup — some skills may need to be set up with context from the user. A good pattern is to store this in a config.json file."
-
-> "Data stored in the skill directory may be deleted when you upgrade the skill, so store persistent data in `${CLAUDE_PLUGIN_DATA}`."
-
-### Constraints and refusal cases
-
-> bugteam pattern — non-negotiables separated from guidance, with design rationale. Explicit "first match wins" refusal conditions.
-
-### Anti-patterns
-
-> No Windows paths. Don’t offer too many options — provide a default with escape hatch. Avoid time-sensitive claims. Use consistent terminology. No deeply nested references.
-
-Also: story-form descriptions; monolith multi-capability skills; silent reimplementation of peer skills; nested folders used as fake sub-skills; deterministic logic only in prose or fenced source; markdown `- [ ]` as the agent's work tracker.
-
-## Self-audit
-
-After every build, improvement, or polish pass, load `${CLAUDE_SKILL_DIR}/references/self-audit-checklist.md`, **register every bullet as a session task**, and complete each with evidence. Every item must pass before delivery. Fix failures, then re-audit.
-
-## Delegation to skill-writer-agent
-
-skill-builder orchestrates; the `skill-writer-agent` agent authors. The caller spawns it with `Agent(subagent_type="skill-writer-agent", ...)`. The handoff packet from Step 4 must include:
-
-- Skill type and folder structure
-- Gap analysis or observation findings (composition plan + description triggers + deterministic inventory)
-- Degree of freedom assessment
-- Initial gotchas
-- Composition plan: related skills, sub-skills to invoke, split decisions
-- Description trigger catalog: capability stem + trigger phrases (not prose)
-- Deterministic elements inventory: each process step classified; code paths + paired tests
-- Any constraints
-
-See `${CLAUDE_SKILL_DIR}/references/delegation-map.md` for exact patterns.
-
-## File index
-
-| File | Purpose |
-|------|---------|
-| `SKILL.md` | This hub — principles, process, routing, file index |
-| `references/skill-types.md` | 9-type taxonomy with folder structures per type |
-| `references/progressive-disclosure.md` | Folder conventions, hub pattern, hard rules |
-| `references/skill-modularity.md` | Cross-skill modularity, sub-skills, composition plan |
-| `references/description-field.md` | Description as trigger catalog (not story prose) |
-| `references/deterministic-elements.md` | Deterministic steps as code/task seeds; CODE_RULES; no markdown checkbox boards |
-| `references/self-audit-checklist.md` | Post-build audit task seeds (register via TaskCreate / TodoWrite) |
-| `references/delegation-map.md` | Subagent handoff patterns and transcript guidance |
-| `workflows/new-skill.md` | Full lifecycle for new skills (6 steps) |
-| `workflows/improve-skill.md` | Observation-first flow for existing skills (6 steps) |
-| `workflows/polish-skill.md` | Description trigger-catalog audit and final validation (5 steps) |
-| `templates/gap-analysis.md` | Gaps, composition plan, description triggers, deterministic inventory |
-
-## Folder map
-
-- `SKILL.md` — hub.
-- `references/` — best-practice specifications and the audit checklist.
-- `workflows/` — step-by-step workflows for each lifecycle phase.
-- `templates/` — reusable templates for skill artifacts.
+TODO: Rework to follow pstack philosophy.

package/_shared/pr-loop/scripts/pr_loop_shared_constants/terminology_sweep_constants.py

@@ -107,6 +107,12 @@ ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND: tuple[str, ...] = (
     "--unified=0",
 )
 
+ALL_GIT_DIFF_UNIFIED_ZERO_COMMAND: tuple[str, ...] = (
+    "git",
+    "diff",
+    "--unified=0",
+)
+
 GIT_DIFF_SUBPROCESS_TIMEOUT_SECONDS: int = 30
 
 GIT_NO_MATCH_EXIT_CODE: int = 1

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

@@ -32,6 +32,7 @@ from pr_loop_shared_constants.terminology_sweep_constants import (
     ALL_COMMON_ENGLISH_COMPOUND_TAIL_WORDS,
     ALL_DIFF_FILE_PATH_STRIP_PREFIXES,
     ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND,
+    ALL_GIT_DIFF_UNIFIED_ZERO_COMMAND,
     ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
     ALL_PROSE_STOPWORD_TOKENS,
     ALL_STRING_ESCAPE_SEQUENCES,
@@ -622,21 +623,23 @@ def _identifier_names_on_added_code_lines(diff_text: str) -> frozenset[str]:
 
 
 def _base_tree_names(
-    repository_root: Path, all_names: frozenset[str]
+    repository_root: Path,
+    all_names: frozenset[str],
+    tree_revision: str,
 ) -> frozenset[str]:
-    """Return the names the repository's base tree already contains.
+    """Return the names the comparison tree already contains.
 
-    Each name is looked up as a whole word in the base revision's tree. A
-    repository with no commits yet, or a lookup that git cannot run, reports
-    the name as absent, so the sweep then treats it as newly introduced.
-    That is the behaviour the sweep has with no base-tree check at all.
+    Each name is looked up as a whole word in ``tree_revision``. A repository
+    with no commits yet, or a lookup that git cannot run, reports the name as
+    absent, so the sweep treats it as newly introduced.
 
     Args:
         repository_root: The repository root the lookups run in.
         all_names: The identifier names to look up.
+        tree_revision: The revision whose tree is searched.
 
     Returns:
-        The subset of names present in the base tree.
+        The subset of names present in that tree.
     """
     all_present_names: set[str] = set()
     for each_name in sorted(all_names):
@@ -645,7 +648,7 @@ def _base_tree_names(
                 [
                     *ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
                     each_name,
-                    GIT_BASE_TREE_REVISION,
+                    tree_revision,
                 ],
                 cwd=str(repository_root),
                 capture_output=True,
@@ -695,14 +698,16 @@ def _raise_for_git_failure(
 
 
 def _strict_base_tree_names(
-    repository_root: Path, all_names: frozenset[str]
+    repository_root: Path,
+    all_names: frozenset[str],
+    tree_revision: str,
 ) -> frozenset[str]:
     all_present_names: set[str] = set()
     for each_name in sorted(all_names):
         all_arguments = (
             *ALL_GIT_GREP_BASE_TREE_COMMAND_PREFIX,
             each_name,
-            GIT_BASE_TREE_REVISION,
+            tree_revision,
         )
         grep_process = _run_strict_git(repository_root, all_arguments)
         if grep_process.returncode == 0:
@@ -728,14 +733,53 @@ def strict_staged_terminology_findings(repository_root: Path) -> list[str]:
         RuntimeError: Git could not read the staged diff or look up an
             identifier in HEAD.
     """
-    diff_process = _run_strict_git(
-        repository_root, ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND
+    return _strict_terminology_findings(
+        repository_root,
+        ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND,
+        GIT_BASE_TREE_REVISION,
     )
+
+
+def strict_base_terminology_findings(
+    repository_root: Path, base_revision: str
+) -> list[str]:
+    """Return near-miss findings for worktree changes against a base revision.
+
+    Args:
+        repository_root: The repository root the worktree diff is read from.
+        base_revision: The tree that worktree changes are compared against.
+
+    Returns:
+        One finding string per near-miss term on an added prose line.
+
+    Raises:
+        RuntimeError: Git could not read the committed diff or look up an
+            identifier in the comparison tree.
+    """
+    all_arguments = (
+        *ALL_GIT_DIFF_UNIFIED_ZERO_COMMAND,
+        base_revision,
+    )
+    return _strict_terminology_findings(
+        repository_root,
+        all_arguments,
+        base_revision,
+    )
+
+
+def _strict_terminology_findings(
+    repository_root: Path,
+    all_diff_arguments: Sequence[str],
+    tree_revision: str,
+) -> list[str]:
+    diff_process = _run_strict_git(repository_root, all_diff_arguments)
     _raise_for_git_failure(diff_process, GIT_DIFF_OPERATION)
     all_added_names = _identifier_names_on_added_code_lines(diff_process.stdout)
     preexisting_tuples = frozenset(
         _identifier_token_tuple(each_name)
-        for each_name in _strict_base_tree_names(repository_root, all_added_names)
+        for each_name in _strict_base_tree_names(
+            repository_root, all_added_names, tree_revision
+        )
     )
     return _find_terminology_near_misses(diff_process.stdout, preexisting_tuples)
 
@@ -743,16 +787,15 @@ def strict_staged_terminology_findings(repository_root: Path) -> list[str]:
 def staged_terminology_findings(repository_root: Path) -> list[str]:
     """Return terminology near-miss findings for a repository's staged diff.
 
-    An identifier the base tree already names is not one the staged diff
-    introduces, so no prose is flagged against it. Only genuinely new
-    identifiers are swept.
+    An identifier already present in HEAD is not treated as introduced, so
+    prose is not flagged against it.
 
     Args:
         repository_root: The repository root the staged diff is read from.
 
     Returns:
-        One finding string per near-miss term on a staged added prose line, or
-        an empty list when the staged diff is empty or git cannot be run.
+        One finding string per near-miss term on a staged prose line, or an
+        empty list when the staged diff is empty or git cannot be run.
     """
     diff_process = subprocess.run(
         list(ALL_GIT_DIFF_CACHED_UNIFIED_ZERO_COMMAND),
@@ -770,7 +813,9 @@ def staged_terminology_findings(repository_root: Path) -> list[str]:
     all_added_names = _identifier_names_on_added_code_lines(diff_process.stdout)
     preexisting_tuples = frozenset(
         _identifier_token_tuple(each_name)
-        for each_name in _base_tree_names(repository_root, all_added_names)
+        for each_name in _base_tree_names(
+            repository_root, all_added_names, GIT_BASE_TREE_REVISION
+        )
     )
     return _find_terminology_near_misses(diff_process.stdout, preexisting_tuples)
 

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

@@ -31,6 +31,7 @@ sweep_module = _load_sweep_module()
 sweep_diff = sweep_module.sweep_diff
 staged_terminology_findings = sweep_module.staged_terminology_findings
 strict_staged_terminology_findings = sweep_module.strict_staged_terminology_findings
+strict_base_terminology_findings = sweep_module.strict_base_terminology_findings
 main = sweep_module.main
 parse_added_lines = sweep_module._parse_added_lines
 
@@ -53,6 +54,54 @@ def _init_git_repository(repository_path: Path) -> None:
         )
 
 
+def _run_repository_git(repository_path: Path, all_arguments: list[str]) -> str:
+    completed = subprocess.run(
+        all_arguments,
+        cwd=repository_path,
+        check=True,
+        capture_output=True,
+        text=True,
+        env=_hermetic_git_environment(),
+    )
+    return completed.stdout.strip()
+
+
+def _write_repository_text(
+    repository_path: Path, relative_path: str, text: str
+) -> None:
+    (repository_path / relative_path).write_text(text, encoding="utf-8")
+
+
+def _commit_all(repository_path: Path, message: str) -> None:
+    _run_repository_git(repository_path, ["git", "add", "-A"])
+    _run_repository_git(repository_path, ["git", "commit", "-m", message])
+
+
+def _head_revision(repository_path: Path) -> str:
+    return _run_repository_git(repository_path, ["git", "rev-parse", "HEAD"])
+
+
+def _committed_near_miss_repository(repository_path: Path) -> str:
+    _init_git_repository(repository_path)
+    _write_repository_text(repository_path, "quota.py", "baseline = 1\n")
+    _write_repository_text(repository_path, "README.md", "Baseline quota text.\n")
+    _commit_all(repository_path, "base")
+    comparison_revision = _head_revision(repository_path)
+    _write_repository_text(
+        repository_path,
+        "quota.py",
+        "baseline = 1\npremium_request_interactions = 5\n",
+    )
+    _commit_all(repository_path, "identifier")
+    _write_repository_text(
+        repository_path,
+        "README.md",
+        "The premium-request-budget field gates the run.\n",
+    )
+    _commit_all(repository_path, "documentation")
+    return comparison_revision
+
+
 CODE_AND_PROSE_DIFF = (
     "diff --git a/api/quota.py b/api/quota.py\n"
     "--- a/api/quota.py\n"
@@ -310,6 +359,16 @@ def test_staged_terminology_findings_empty_when_clean(tmp_path: Path) -> None:
     assert staged_terminology_findings(tmp_path) == []
 
 
+def test_strict_base_terminology_findings_reports_committed_near_miss(
+    tmp_path: Path,
+) -> None:
+    comparison_revision = _committed_near_miss_repository(tmp_path)
+    all_findings = strict_base_terminology_findings(tmp_path, comparison_revision)
+    assert len(all_findings) == 1
+    assert "README.md:1" in all_findings[0]
+    assert "premium-request-budget" in all_findings[0]
+
+
 def test_parse_added_lines_counts_pre_increment_content_as_added_line() -> None:
     diff_with_pre_increment = (
         "diff --git a/app.mjs b/app.mjs\n"