agent-code-guard 0.3.1__tar.gz → 0.4.0__tar.gz

{agent_code_guard-0.3.1/src/agent_code_guard.egg-info → agent_code_guard-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-code-guard
-Version: 0.3.1
+Version: 0.4.0
 Summary: Deterministic cross-language guardrails for agent-assisted development
 License-Expression: MIT
 Project-URL: Source, https://github.com/stef-k/agent-code-guard
@@ -21,9 +21,13 @@ Dynamic: license-file
 Deterministic maintainability guardrails for source code and Markdown changed by
 a human or coding agent.
 
+[Documentation](https://stef-k.github.io/agent-code-guard/) ·
+[Get started](https://stef-k.github.io/agent-code-guard/#get-started) ·
+[Releases](https://github.com/stef-k/agent-code-guard/releases)
+
 [![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
-[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://stef-k.github.io/agent-code-guard/platform-support.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
 
 Agent Code Guard measures file size, callable size, structural nesting,
@@ -75,7 +79,7 @@ code-guard doctor
 ```
 
 `--version` confirms the installed distribution identity. `doctor` checks the
-active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+active installation's health. See the [usage guide](https://stef-k.github.io/agent-code-guard/usage.html) for virtual
 environment, uv, and developer alternatives.
 
 ### Ask your agent to adopt it
@@ -89,13 +93,13 @@ Copy this prompt to a coding agent:
 > activating or exporting its installed, version-matched skill for the current
 > agent environment. Verify `code-guard --version` and run `code-guard doctor`,
 > then locate the skill with `code-guard --skill-path`. Follow the
-> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> [skill activation guide](https://stef-k.github.io/agent-code-guard/skill-distribution.html):
 > activate that installed path when the platform supports it, or export it with
 > `code-guard --export-skill <target-directory>` to the platform's documented
 > skill directory. Do not guess a target or overwrite an existing export; verify
 > that `.agent-code-guard-version` matches the installed distribution. Follow the
-> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> [agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+> without creating an adoption baseline. After meaningful source or Markdown edits, run
 > `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
 > exact edited files. Inspect REVIEW and FAIL findings, make only genuine
 > improvements, rerun the check, and report the result. Never weaken thresholds,
@@ -118,7 +122,7 @@ No configuration is needed. A REVIEW asks for inspection and judgment, not an
 automatic refactor. Outside Git, pass the exact edited files instead, such as
 `code-guard src/app.py docs/guide.md`.
 
-See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+See the [agent workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) for repeated human and
 agent use.
 
 ## Recommended workflow
@@ -140,7 +144,7 @@ report the result before completion
 Use `code-guard . --changed-only --json --json-mode compact` for a structured,
 low-noise manual agent check. Hooks are optional, platform-owned, and require
 user authorization; Code Guard does not install them. The
-[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+[workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) owns the complete manual and
 hook-assisted process.
 
 ## Interpreting results
@@ -177,7 +181,7 @@ measurement. A REVIEW is not proof of a defect or a mandatory refactor.
 Comparisons are strictly greater-than, so equality passes. All guards except
 file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
 distinct, deterministic value rather than duplicate conventional tooling. See
-[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+[Guard admission](https://stef-k.github.io/agent-code-guard/guard-admission.html).
 
 ### Result and JSON reference
 
@@ -186,7 +190,7 @@ all-guard-excluded file counts. Bare `--json` is the compatible full output;
 `--json-mode debug` is byte-identical for the same completed invocation, while
 `--json-mode compact` removes only normalized `pass` findings and retains the
 result, scope, required policies, guards, ordering, and actionable findings.
-Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
+Named modes require `--json`. See [Usage](https://stef-k.github.io/agent-code-guard/usage.html) for the schema and
 option contract.
 
 Known per-file syntax or provider failures instead produce `overall:
@@ -221,7 +225,7 @@ Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
 failure is unavailable evidence, distinct from both an inapplicable file and a
-completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+completed FAIL finding. See [Language support](https://stef-k.github.io/agent-code-guard/language-support.html).
 
 ### Skill integration
 
@@ -233,38 +237,45 @@ code-guard --export-skill <target-directory>
 ```
 
 Skill activation is platform-specific and is not performed by pipx or Code
-Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+Guard. See [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html). The checkout
 compatibility runner is for repository development, not normal installation.
 
 ### Configuration
 
 Built-in defaults require no configuration. Configure a project only for a
-concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
+concrete policy reason; see the [configuration guide](https://stef-k.github.io/agent-code-guard/configuration.html).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
 Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
 `ratchetAt: "review"` only when every established file above `warnAt` must be
 non-increasing while ordinary findings in that range remain REVIEW.
 
+Reviewed oversized Markdown documents have a separate, explicit
+[document-size ratchet](https://stef-k.github.io/agent-code-guard/usage.html#reviewed-markdown-document-ratchet).
+`--create-markdown-baseline` records accepted physical-line counts;
+`--update-markdown-baseline` only lowers or prunes them. Documents within their
+allowance pass the document-size guard; growth produces REVIEW. Section
+findings remain active, and ordinary analysis never writes either baseline.
+
 ## Trust, CI, and platform support
 
 CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
 remain visible but non-blocking, while FAIL findings and tool errors block the
-workflow; the repository intentionally uses no LOC baseline.
+workflow; the repository intentionally uses no adoption baseline.
 
 The maintained interpreter range is **CPython 3.10–3.14**. See
-[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+[Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html) for supported binary platforms and
 source-build boundaries.
 
 ## Documentation
 
-- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
-- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
-- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
-- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
-- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
-- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+- [Documentation index](https://stef-k.github.io/agent-code-guard/)
+- [Agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+- [Usage and CLI reference](https://stef-k.github.io/agent-code-guard/usage.html)
+- [Configuration](https://stef-k.github.io/agent-code-guard/configuration.html)
+- [Language support](https://stef-k.github.io/agent-code-guard/language-support.html)
+- [Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html)
+- [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html)
 
 ## Feedback, security, and license
 

{agent_code_guard-0.3.1 → agent_code_guard-0.4.0}/README.md

@@ -7,9 +7,13 @@
 Deterministic maintainability guardrails for source code and Markdown changed by
 a human or coding agent.
 
+[Documentation](https://stef-k.github.io/agent-code-guard/) ·
+[Get started](https://stef-k.github.io/agent-code-guard/#get-started) ·
+[Releases](https://github.com/stef-k/agent-code-guard/releases)
+
 [![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
-[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://stef-k.github.io/agent-code-guard/platform-support.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
 
 Agent Code Guard measures file size, callable size, structural nesting,
@@ -61,7 +65,7 @@ code-guard doctor
 ```
 
 `--version` confirms the installed distribution identity. `doctor` checks the
-active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+active installation's health. See the [usage guide](https://stef-k.github.io/agent-code-guard/usage.html) for virtual
 environment, uv, and developer alternatives.
 
 ### Ask your agent to adopt it
@@ -75,13 +79,13 @@ Copy this prompt to a coding agent:
 > activating or exporting its installed, version-matched skill for the current
 > agent environment. Verify `code-guard --version` and run `code-guard doctor`,
 > then locate the skill with `code-guard --skill-path`. Follow the
-> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> [skill activation guide](https://stef-k.github.io/agent-code-guard/skill-distribution.html):
 > activate that installed path when the platform supports it, or export it with
 > `code-guard --export-skill <target-directory>` to the platform's documented
 > skill directory. Do not guess a target or overwrite an existing export; verify
 > that `.agent-code-guard-version` matches the installed distribution. Follow the
-> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> [agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+> without creating an adoption baseline. After meaningful source or Markdown edits, run
 > `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
 > exact edited files. Inspect REVIEW and FAIL findings, make only genuine
 > improvements, rerun the check, and report the result. Never weaken thresholds,
@@ -104,7 +108,7 @@ No configuration is needed. A REVIEW asks for inspection and judgment, not an
 automatic refactor. Outside Git, pass the exact edited files instead, such as
 `code-guard src/app.py docs/guide.md`.
 
-See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+See the [agent workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) for repeated human and
 agent use.
 
 ## Recommended workflow
@@ -126,7 +130,7 @@ report the result before completion
 Use `code-guard . --changed-only --json --json-mode compact` for a structured,
 low-noise manual agent check. Hooks are optional, platform-owned, and require
 user authorization; Code Guard does not install them. The
-[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+[workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) owns the complete manual and
 hook-assisted process.
 
 ## Interpreting results
@@ -163,7 +167,7 @@ measurement. A REVIEW is not proof of a defect or a mandatory refactor.
 Comparisons are strictly greater-than, so equality passes. All guards except
 file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
 distinct, deterministic value rather than duplicate conventional tooling. See
-[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+[Guard admission](https://stef-k.github.io/agent-code-guard/guard-admission.html).
 
 ### Result and JSON reference
 
@@ -172,7 +176,7 @@ all-guard-excluded file counts. Bare `--json` is the compatible full output;
 `--json-mode debug` is byte-identical for the same completed invocation, while
 `--json-mode compact` removes only normalized `pass` findings and retains the
 result, scope, required policies, guards, ordering, and actionable findings.
-Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
+Named modes require `--json`. See [Usage](https://stef-k.github.io/agent-code-guard/usage.html) for the schema and
 option contract.
 
 Known per-file syntax or provider failures instead produce `overall:
@@ -207,7 +211,7 @@ Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
 failure is unavailable evidence, distinct from both an inapplicable file and a
-completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+completed FAIL finding. See [Language support](https://stef-k.github.io/agent-code-guard/language-support.html).
 
 ### Skill integration
 
@@ -219,38 +223,45 @@ code-guard --export-skill <target-directory>
 ```
 
 Skill activation is platform-specific and is not performed by pipx or Code
-Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+Guard. See [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html). The checkout
 compatibility runner is for repository development, not normal installation.
 
 ### Configuration
 
 Built-in defaults require no configuration. Configure a project only for a
-concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
+concrete policy reason; see the [configuration guide](https://stef-k.github.io/agent-code-guard/configuration.html).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
 Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
 `ratchetAt: "review"` only when every established file above `warnAt` must be
 non-increasing while ordinary findings in that range remain REVIEW.
 
+Reviewed oversized Markdown documents have a separate, explicit
+[document-size ratchet](https://stef-k.github.io/agent-code-guard/usage.html#reviewed-markdown-document-ratchet).
+`--create-markdown-baseline` records accepted physical-line counts;
+`--update-markdown-baseline` only lowers or prunes them. Documents within their
+allowance pass the document-size guard; growth produces REVIEW. Section
+findings remain active, and ordinary analysis never writes either baseline.
+
 ## Trust, CI, and platform support
 
 CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
 remain visible but non-blocking, while FAIL findings and tool errors block the
-workflow; the repository intentionally uses no LOC baseline.
+workflow; the repository intentionally uses no adoption baseline.
 
 The maintained interpreter range is **CPython 3.10–3.14**. See
-[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+[Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html) for supported binary platforms and
 source-build boundaries.
 
 ## Documentation
 
-- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
-- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
-- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
-- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
-- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
-- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+- [Documentation index](https://stef-k.github.io/agent-code-guard/)
+- [Agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+- [Usage and CLI reference](https://stef-k.github.io/agent-code-guard/usage.html)
+- [Configuration](https://stef-k.github.io/agent-code-guard/configuration.html)
+- [Language support](https://stef-k.github.io/agent-code-guard/language-support.html)
+- [Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html)
+- [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html)
 
 ## Feedback, security, and license
 

{agent_code_guard-0.3.1 → agent_code_guard-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-code-guard"
-version = "0.3.1"
+version = "0.4.0"
 description = "Deterministic cross-language guardrails for agent-assisted development"
 readme = "README.md"
 requires-python = ">=3.10"

{agent_code_guard-0.3.1 → agent_code_guard-0.4.0}/skills/code-guard/SKILL.md

@@ -148,8 +148,9 @@ reviews and never fails. Load `references/complexity-policy.md` only when
 
 Markdown document and direct-section size count all physical lines. Sections
 run from a supported heading through the line before the next heading of any
-level, or EOF. Exact effective thresholds pass; greater measurements review and
-never fail. Load `references/markdown-size-policy.md` when either
+level, or EOF. Exact effective thresholds pass; greater measurements normally
+review and never fail. A document measurement within an explicitly accepted
+Markdown document baseline passes the document-size guard. Load `references/markdown-size-policy.md` when either
 `markdownDocumentSize` or `markdownSectionSize` appears in `requiredPolicies`.
 Review navigation and responsibility without mechanically splitting coherent
 specifications or gaming headings/formatting.
@@ -161,3 +162,20 @@ REVIEW requires inspection and justification, not mandatory refactoring.
 Agent Code Guard is the canonical LOC implementation. Agent LOC Guard is the completed prototype/reference whose mature behavior was migrated from commit `75ab39d261dbc65f78815836fac90add16d265d1`.
 
 Project-specific architecture rules, framework-specific checks, arbitrary style preferences, security scanners, and dependency auditing are outside the universal core.
+
+## Reviewed Markdown document baselines
+
+After explicit acceptance of a cohesive oversized document, use
+`code-guard docs/architecture.md --create-markdown-baseline` to record its current
+physical-line count in `.agent-tools/code-guard.markdown-baseline.json` at the
+analysis root. Normal analysis reads this file without writing. Unchanged or
+smaller accepted documents pass `markdownDocumentSize`; growth above both the
+allowance and effective threshold returns REVIEW. `markdownSectionSize` remains
+independent and has no baseline support.
+
+`--update-markdown-baseline` only lowers or prunes existing allowances within
+positional bounds; it never adds or increases one. Neither write command is
+part of routine checks. Do not create, replace, remove, or increase allowances
+merely to silence findings. Review and commit explicit acceptance decisions.
+Human/full JSON output retains acceptance context; compact omits accepted PASS
+findings. Load the Markdown policy for actionable document or section reviews.

agent_code_guard-0.4.0/skills/code-guard/references/markdown-size-policy.md

@@ -0,0 +1,33 @@
+# Markdown Size Review Policy
+
+Use this policy when `markdownDocumentSize` or `markdownSectionSize` appears in
+`requiredPolicies`.
+
+A Markdown size REVIEW is an instruction to inspect navigation and
+responsibility, not an automatic instruction to split the document or section.
+`reviewed; coherent; keep` is a valid outcome for cohesive specifications,
+reference material, tables, procedures, and code-heavy sections.
+
+Improve navigation or responsibility boundaries only when the result is
+genuinely clearer. Do not add meaningless headings to lower section size,
+mechanically split coherent material, compress formatting or remove useful
+blank lines, or hide content in fenced code. Agents must not raise thresholds or
+disable either guard merely to silence a finding; project or user authority is
+required for configuration changes.
+
+## Explicit document acceptance
+
+An explicitly reviewed, cohesive oversized document may use a source-controlled
+allowance created with `--create-markdown-baseline`. The separate
+`.agent-tools/code-guard.markdown-baseline.json` records exact root-relative paths
+and current physical-line counts. Within that allowance the document finding
+passes; growth above both the allowance and effective threshold is REVIEW,
+never FAIL. At or below the ordinary threshold, an allowance is no longer needed.
+
+This applies only to `markdownDocumentSize`. Inspect section REVIEW findings
+independently; document acceptance does not exempt sections. Normal analysis
+never changes a baseline. After reductions or deletions,
+`--update-markdown-baseline` can explicitly lower or prune existing entries but
+cannot add or increase allowances. Agents must not create or replace baselines,
+remove allowances, raise thresholds, or add exclusions merely to silence growth.
+Baseline acceptance requires explicit authority and source-control review.

agent_code_guard-0.4.0/src/agent_code_guard/baseline_files.py

@@ -0,0 +1,139 @@
+"""Filesystem safety shared by explicit source-controlled baseline workflows."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from .file_selection import is_within
+
+
+def validate_paths(root: Path, entries: dict[str, int], label: str = "LOC") -> None:
+    for relative in entries:
+        candidate = root / Path(relative)
+        resolved = candidate.resolve(strict=False)
+        if not is_within(resolved, root):
+            raise ValueError(f"{label} baseline path escapes analysis root: {relative}")
+        current = root
+        for part in Path(relative).parts:
+            current = current / part
+            if current.is_symlink():
+                raise ValueError(f"{label} baseline path traverses a symlink: {relative}")
+
+
+def validate_explicit_scope(
+    values: list[str], invocation: Path, root: Path, selected_files: tuple[Path, ...],
+) -> set[Path]:
+    """Validate raw bounds before resolution erases empty directories and file-link identity."""
+    linked_targets: set[Path] = set()
+    directly_reached: set[Path] = set()
+    for value in values or ["."]:
+        path = Path(value) if Path(value).is_absolute() else invocation / value
+        resolved = path.resolve()
+        if not is_within(resolved, root):
+            raise ValueError(f"baseline scope is outside analysis root: {value}")
+        if path.is_symlink() and path.is_file():
+            linked_targets.add(resolved)
+        elif path.is_file():
+            directly_reached.add(resolved)
+        elif path.is_dir():
+            directly_reached.update(
+                selected.resolve() for selected in selected_files if is_within(selected, resolved)
+            )
+    return linked_targets - directly_reached
+
+
+def atomic_replace(target: Path, content: bytes) -> None:
+    temporary = _write_temporary(target, content)
+    try:
+        os.replace(temporary, target)
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def atomic_create(target: Path, content: bytes, label: str = "LOC") -> None:
+    temporary = _write_temporary(target, content)
+    try:
+        os.link(temporary, target)
+    except FileExistsError as exc:
+        raise ValueError(f"{label} baseline already exists: {target.parent.name}/{target.name}") from exc
+    finally:
+        try:
+            temporary.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def _write_temporary(target: Path, content: bytes) -> Path:
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        return temporary
+    except Exception:
+        temporary.unlink(missing_ok=True)
+        raise
+
+
+def resolve_bounds(values: list[str], invocation: Path, root: Path) -> list[tuple[Path, bool]]:
+    bounds = []
+    for value in values or ["."]:
+        path = Path(value) if Path(value).is_absolute() else invocation / value
+        if not path.exists():
+            raise FileNotFoundError(f"explicit path does not exist: {value}")
+        if path.is_symlink():
+            raise ValueError(f"baseline bounds may not be symlinks: {value}")
+        resolved = path.resolve()
+        if not is_within(resolved, root):
+            raise ValueError(f"baseline scope is outside analysis root: {value}")
+        bounds.append((resolved, path.is_dir()))
+    return bounds
+
+
+def in_bounds(relative: str, bounds: list[tuple[Path, bool]], root: Path) -> bool:
+    candidate = (root / Path(relative)).resolve(strict=False)
+    return any(
+        is_within(candidate, bound) if is_directory else candidate == bound
+        for bound, is_directory in bounds
+    )
+
+
+def require_regular_inside(path: Path, root: Path) -> None:
+    if path.is_symlink() or not path.is_file() or not is_within(path, root):
+        raise ValueError(f"baseline scope contains an unsafe or outside-root path: {path}")
+
+
+def canonical_path(value: str) -> bool:
+    if not value or "\\" in value or value.endswith("/") or "//" in value:
+        return False
+    path = Path(value)
+    if path.is_absolute() or path.drive or value.startswith("//"):
+        return False
+    return all(part not in {"", ".", ".."} for part in value.split("/"))
+
+
+def validate_analysis_scope(root: Path, files: tuple[Path, ...]) -> None:
+    """Recheck physical containment before applying any persisted allowance."""
+    error = "baseline analysis scope is outside analysis root"
+    try:
+        current_root = root.resolve(strict=True)
+    except OSError as exc:
+        raise ValueError(f"{error}: {root}") from exc
+    for path in files:
+        try:
+            current_path = path.resolve(strict=True)
+            valid = (
+                not path.is_symlink() and current_path.is_file()
+                and current_path.is_relative_to(current_root)
+            )
+        except OSError:
+            valid = False
+        if not valid:
+            raise ValueError(f"{error}: {path}")