code-standards 8.144.0__tar.gz → 8.147.0__tar.gz

{code_standards-8.144.0 → code_standards-8.147.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-standards
-Version: 8.144.0
+Version: 8.147.0
 Summary: One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy.
 Project-URL: Homepage, https://code-standards.sarj.ai/
 Project-URL: Documentation, https://code-standards.sarj.ai/cli/
@@ -28,7 +28,7 @@ Requires-Dist: pre-commit==4.7.0
 Requires-Dist: pydantic==2.14.1
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: referencing==0.37.0
-Requires-Dist: repo-standards==6.13.0
+Requires-Dist: repo-standards==6.14.0
 Requires-Dist: ruff==0.17.2
 Requires-Dist: sarj-iac-lint==0.30.3
 Requires-Dist: sarj-python-lint==1.84.0
@@ -67,6 +67,8 @@ New ESLint setups use `eslint.config.ts` and the compiler-checked `eslint.strict
 
 Use repeatable `check --rule ENGINE:ID` selectors to select native rules, ESLint rules, or managed security audits. Exclusions, baselines, and severities still apply; Ruff selectors are not supported. Native linters and ESLint execute only selected rules. ESLint retains configured parsers, options, severities, and suppression directives.
 
+For a history-free initial import, set `SARJ_STANDARDS_INITIAL_IMPORT_SOURCE` only on the initial commit process to the full lowercase object ID of an available source commit with exactly one available parent. HEAD must be an unborn branch; the entire staged tree must equal that commit, tracked worktree files must match the index without hidden index flags, and nonignored files must be staged. Native staged checks compare the source commit with its parent, preserving the usual changed-line failures for findings introduced in that commit while allowing inherited diagnostic budgets. Validation runs before and after analysis; all analyzers and baseline limits still apply. The caller must qualify the source commit separately. Git replacement objects and lazy fetching are disabled; explicitly supplied temporary object alternates may provide the source history without copying it into the new repository. Remove the input and alternates before subsequent commits, pushes, and CI. Invalid or changed import context fails analysis, including clean reports; ordinary checks without this input retain their existing behavior.
+
 Selected ESLint checks apply live inline suppressions and validate selected bulk suppression counts. The complete lint gate owns unused inline-directive and inline-configuration checks: a partial run cannot establish whether an unselected rule's directive is needed.
 
 The complete Python and JavaScript/TypeScript source gate requires named, line-local exceptions with concrete reasons. SARJ523 rejects blanket Python waivers, scoped Ruff file/range disables and weakened Pyright source settings; SARJ419 also rejects missing explanations. Bare sarj-noqa markers cannot waive Python, SQL or IaC findings. Required Ruff blanket-ignore checks and an independent ESLint suppression-policy pass remain active despite source disables, consumer rule configuration, rule exclusions and diagnostic baselines. The ESLint pass bans file/range disables, ts-ignore and ts-nocheck while retaining described local ts-expect-error exceptions. Generated-source headers cannot authorize their own waiver; explicit whole-path exclusions retain that boundary. A reason is not proof that an exception is justified. Native parse/read/size failures make checks incomplete. Explicit tool delegation, partial and own-CI options retain their declared scope and coverage notices.

{code_standards-8.144.0 → code_standards-8.147.0}/README.md

@@ -27,6 +27,8 @@ New ESLint setups use `eslint.config.ts` and the compiler-checked `eslint.strict
 
 Use repeatable `check --rule ENGINE:ID` selectors to select native rules, ESLint rules, or managed security audits. Exclusions, baselines, and severities still apply; Ruff selectors are not supported. Native linters and ESLint execute only selected rules. ESLint retains configured parsers, options, severities, and suppression directives.
 
+For a history-free initial import, set `SARJ_STANDARDS_INITIAL_IMPORT_SOURCE` only on the initial commit process to the full lowercase object ID of an available source commit with exactly one available parent. HEAD must be an unborn branch; the entire staged tree must equal that commit, tracked worktree files must match the index without hidden index flags, and nonignored files must be staged. Native staged checks compare the source commit with its parent, preserving the usual changed-line failures for findings introduced in that commit while allowing inherited diagnostic budgets. Validation runs before and after analysis; all analyzers and baseline limits still apply. The caller must qualify the source commit separately. Git replacement objects and lazy fetching are disabled; explicitly supplied temporary object alternates may provide the source history without copying it into the new repository. Remove the input and alternates before subsequent commits, pushes, and CI. Invalid or changed import context fails analysis, including clean reports; ordinary checks without this input retain their existing behavior.
+
 Selected ESLint checks apply live inline suppressions and validate selected bulk suppression counts. The complete lint gate owns unused inline-directive and inline-configuration checks: a partial run cannot establish whether an unselected rule's directive is needed.
 
 The complete Python and JavaScript/TypeScript source gate requires named, line-local exceptions with concrete reasons. SARJ523 rejects blanket Python waivers, scoped Ruff file/range disables and weakened Pyright source settings; SARJ419 also rejects missing explanations. Bare sarj-noqa markers cannot waive Python, SQL or IaC findings. Required Ruff blanket-ignore checks and an independent ESLint suppression-policy pass remain active despite source disables, consumer rule configuration, rule exclusions and diagnostic baselines. The ESLint pass bans file/range disables, ts-ignore and ts-nocheck while retaining described local ts-expect-error exceptions. Generated-source headers cannot authorize their own waiver; explicit whole-path exclusions retain that boundary. A reason is not proof that an exception is justified. Native parse/read/size failures make checks incomplete. Explicit tool delegation, partial and own-CI options retain their declared scope and coverage notices.

{code_standards-8.144.0 → code_standards-8.147.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "code-standards"
-version = "8.144.0"
+version = "8.147.0"
 description = "One deterministic quality gate for Sarj Python, TypeScript, Swift, Kotlin, shell, SQL, IaC, and repository policy."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -28,7 +28,7 @@ dependencies = [
   "PyYAML==6.0.3",
   "jsonschema==4.26.0",
   "referencing==0.37.0",
-  "repo-standards==6.13.0",
+  "repo-standards==6.14.0",
   "ruff==0.17.2",
   "shellcheck-py==0.11.0.1; (sys_platform == 'darwin' and platform_machine == 'arm64') or (sys_platform == 'darwin' and platform_machine == 'x86_64') or (sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')",
   "sarj-iac-lint==0.30.3",

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/api.py

@@ -47,6 +47,7 @@ from .libs.diagnostics import (
     ToolReport as ToolReport,
     TrustMode as TrustMode,
     baseline as diagnostic_baseline,
+    initial_import,
     to_github as to_github,
     to_json as to_json,
     to_sarif as to_sarif,
@@ -266,6 +267,10 @@ class Standards:
         python_type_check: bool = True,
         eslint: bool = True,
     ) -> AnalysisReport:
+        try:
+            import_context = initial_import.load(self.root, staged=staged)
+        except ValueError as exc:
+            return _failed_analysis(self.root, "invalid-input", str(exc))
         if jobs not in {1, 2}:
             return _failed_analysis(self.root, "invalid-input", "analysis jobs must be 1 or 2")
         external = external or bool(upstream_rules.ids)
@@ -279,8 +284,18 @@ class Standards:
         except (OSError, TypeError, ValueError) as exc:
             return _failed_analysis(self.root, "invalid-input", str(exc))
         if prepared_only:
-            return _prepared_only_analysis(
-                self.root, adopted, prepared_devops, prepared_targets, paths=paths, rules=rules, trust=normalized_trust
+            return _validated_initial_import(
+                _prepared_only_analysis(
+                    self.root,
+                    adopted,
+                    prepared_devops,
+                    prepared_targets,
+                    paths=paths,
+                    rules=rules,
+                    trust=normalized_trust,
+                ),
+                import_context,
+                staged=staged,
             )
         try:
             selection_policy = _selection_policy(self.root, adopted, normalized_mode)
@@ -321,16 +336,24 @@ class Standards:
         )
         coverage.extend(_prepared_coverage(adopted, prepared_devops))
         if not external:
-            native = report_from_tools(self.root, native_analysis())
-            changed_scope = _analysis_changed_scope(self.root, native, baseline_budget, staged=staged)
+            combined = report_from_tools(self.root, native_analysis())
+            changed_scope = _analysis_changed_scope(self.root, combined, baseline_budget, staged=staged)
             _native_typescript_coverage(selected_groups, adopted, rule_selection, coverage)
             if normalized_mode in {AnalysisMode.POLICY, AnalysisMode.OBSERVE}:
-                native = _with_warning_severity(native, _warning_rule_keys(normalized_mode, rule_selection))
-            return _with_coverage(
-                _without_baselined_diagnostics(
-                    native, baseline_budget.counts, changed_scope=changed_scope, provenance=baseline_budget.provenance
+                combined = _with_warning_severity(combined, _warning_rule_keys(normalized_mode, rule_selection))
+            return _validated_initial_import(
+                _with_coverage(
+                    _without_baselined_diagnostics(
+                        combined,
+                        baseline_budget.counts,
+                        changed_scope=changed_scope,
+                        provenance=baseline_budget.provenance,
+                    ),
+                    coverage,
                 ),
-                coverage,
+                import_context,
+                staged=staged,
+                changed_scope=changed_scope,
             )
         coverage.extend(
             _source_analyzer_coverage(
@@ -375,11 +398,16 @@ class Standards:
             else frozenset(),
             upstream_rules=upstream_rules,
         )
-        return _with_coverage(
-            _without_baselined_diagnostics(
-                combined, baseline_budget.counts, changed_scope=changed_scope, provenance=baseline_budget.provenance
+        return _validated_initial_import(
+            _with_coverage(
+                _without_baselined_diagnostics(
+                    combined, baseline_budget.counts, changed_scope=changed_scope, provenance=baseline_budget.provenance
+                ),
+                coverage,
             ),
-            coverage,
+            import_context,
+            staged=staged,
+            changed_scope=changed_scope,
         )
 
     def run(
@@ -670,6 +698,28 @@ def _failed_analysis(root: Path, kind: str, message: str) -> AnalysisReport:
     return AnalysisReport(root, Completion.FAILED, Conclusion.INCONCLUSIVE, (tool,))
 
 
+def _validated_initial_import(
+    report: AnalysisReport,
+    context: initial_import.InitialImport | None,
+    *,
+    staged: bool,
+    changed_scope: diagnostic_baseline.ChangedLineScope | None = None,
+) -> AnalysisReport:
+    failure: str | None = None
+    try:
+        initial_import.validate(report.root, context, staged=staged)
+    except ValueError as exc:
+        failure = str(exc)
+    if failure is None and context is not None and changed_scope is not None and changed_scope.failed:
+        failure = "initial-import changed-line comparison failed"
+    if failure is None:
+        return report
+    return _with_coverage(
+        report_from_tools(report.root, (*report.tools, *_failed_analysis(report.root, "invalid-input", failure).tools)),
+        report.coverage,
+    )
+
+
 def _analysis_changed_scope(
     root: Path,
     report: AnalysisReport,

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/configs/cli-reference.v1.json

@@ -3316,6 +3316,6 @@
   },
   "program": "code-standards",
   "schemaVersion": 1,
-  "summary": "Adopt, check, fix, diagnose, and update sarj-ai standards (v8.144.0).",
-  "version": "8.144.0"
+  "summary": "Adopt, check, fix, diagnose, and update sarj-ai standards (v8.147.0).",
+  "version": "8.147.0"
 }

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/libs/adoption/manifest.py

@@ -55,7 +55,7 @@ class _UpstreamRuleEngine(StrEnum):
 LINT_CONFIGS: Final = "code-standards"
 _PYTHON_LINT: Final = "sarj-python-lint"
 SIBLING_PACKAGES: Final = (_PYTHON_LINT, "sarj-sql-lint", "sarj-iac-lint")
-REPO_STANDARDS_VERSION: Final = "6.13.0"
+REPO_STANDARDS_VERSION: Final = "6.14.0"
 # Actions can receive delivery fixes independently of the consumer topology policy.
 REPO_STANDARDS_ACTION_VERSION: Final = "6.13.0"
 REPO_STANDARDS_REVISION: Final = "c61146c7137c764ac1371a99508771fc255a1767"

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/libs/adoption/repository_baseline.py

@@ -28,7 +28,10 @@ PATH = ".repo-standards/baseline.json"
 # enabling it still leaves every new finding unaccepted by the warning ratchet.
 # Policy 28 changes operational-script-tests identities; only empty policy 27
 # baselines remain compatible. Accepted debt still requires a separate review.
-_COMPATIBLE_TRANSITIONS = frozenset({(18, 19), (18, 20), (19, 20), (25, 26), (25, 27), (26, 27)})
+# Policy 29 adds a default-disabled migration warning. Existing finding
+# identities and manifest scope remain unchanged; preserve all accepted debt.
+# Empty policy 27 baselines may compose the reviewed 27 -> 28 -> 29 steps.
+_COMPATIBLE_TRANSITIONS = frozenset({(18, 19), (18, 20), (19, 20), (25, 26), (25, 27), (26, 27), (28, 29)})
 _POLICY_VERSION = re.compile(rb'("policy_version"\s*:\s*)[0-9]+(?=\s*[,}])')
 
 
@@ -59,7 +62,7 @@ def migrate(contents: bytes, manifest: bytes, *, target_policy_version: int) ->
     if baseline.policy_version == target_policy_version:
         return contents
     transition = (baseline.policy_version, target_policy_version)
-    empty_compatible = transition == (27, 28) and not baseline.fingerprints
+    empty_compatible = transition in {(27, 28), (27, 29)} and not baseline.fingerprints
     if transition not in _COMPATIBLE_TRANSITIONS and not empty_compatible:
         msg = (
             f"repository baseline migration {baseline.policy_version} -> {target_policy_version} "

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/libs/adoption/scaffold.py

@@ -2399,8 +2399,13 @@ def github_ci_workflow(root: Path, *, ecosystems: Ecosystems | None = None) -> s
     lines.extend(
         (
             "      - name: Run standards",
+            "        shell: bash",
             "        env:",
-            "          SARJ_STANDARDS_BASE: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}",
+            "          SARJ_STANDARDS_BASE: >-",
+            "            ${{ !(github.event_name == 'push' && github.event.created &&",
+            "            github.event.before == '0000000000000000000000000000000000000000') &&",
+            "            (github.event.pull_request.base.sha || github.event.merge_group.base_sha ||",
+            "            github.event.before) || '' }}",
             f"        run: {runner} check --trust-repository-code --format github",
         )
     )

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/libs/diagnostics/baseline.py

@@ -10,7 +10,7 @@ from pathlib import Path
 import re
 import shutil
 import subprocess  # ruff: ignore[suspicious-subprocess-import] -- fixed read-only git argv.
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypedDict
 
 from pydantic import JsonValue
 
@@ -18,6 +18,8 @@ from sarj_standards.libs.filesystem import is_link_like
 from sarj_standards.libs.json_boundary import parse_unique_json
 from sarj_standards.libs.typed_containers import is_object_mapping
 
+from . import initial_import
+
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Mapping, Sequence
@@ -48,6 +50,10 @@ class _ChangedPaths:
     renamed: bool
 
 
+class _DiffOptions(TypedDict, total=False):
+    env: dict[str, str]
+
+
 @dataclass(frozen=True, slots=True)
 class RuleRemoval:
     contents: str
@@ -83,9 +89,17 @@ def changed_line_scope(root: Path, *, staged: bool, paths: Iterable[str] | None
     git = shutil.which("git")
     if git is None:
         return ChangedLineScope(frozenset(), {}, failed=True)
+    try:
+        context = initial_import.load(root, staged=staged)
+    except ValueError:
+        return ChangedLineScope(frozenset(), {}, failed=True)
+    # The validated index equals source; immutable endpoints keep both patch reads on that exact delta.
     comparison = ("--cached",) if staged else (f"{base}...HEAD",)
+    if context is not None:
+        comparison = (context.parent, context.source)
     common = (
         git,
+        *(("--no-replace-objects", "--no-lazy-fetch") if context is not None else ()),
         "--literal-pathspecs",
         "-c",
         "core.quotePath=true",
@@ -101,6 +115,18 @@ def changed_line_scope(root: Path, *, staged: bool, paths: Iterable[str] | None
         return None
     if sum(len(os.fsencode(path)) + 1 for path in selected) > _MAX_DIFF_PATH_BYTES:
         selected = ()
+    return _read_changed_scope(root, common, selected, staged=staged, context=context)
+
+
+def _read_changed_scope(
+    root: Path,
+    common: tuple[str, ...],
+    selected: tuple[str, ...],
+    *,
+    staged: bool,
+    context: initial_import.InitialImport | None,
+) -> ChangedLineScope:
+    options: _DiffOptions = {"env": initial_import.git_environment()} if context is not None else {}
     try:
         names = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed Git argv with literal repository-relative paths.
             (*common, "--name-status", "-z", "--"),
@@ -108,6 +134,7 @@ def changed_line_scope(root: Path, *, staged: bool, paths: Iterable[str] | None
             check=False,
             capture_output=True,
             timeout=30,
+            **options,
         )
         changes = _changed_paths(names.stdout)
         if changes.renamed:
@@ -119,11 +146,16 @@ def changed_line_scope(root: Path, *, staged: bool, paths: Iterable[str] | None
             check=False,
             capture_output=True,
             timeout=30,
+            **options,
         )
     except OSError, ValueError, subprocess.TimeoutExpired:
         return ChangedLineScope(frozenset(), {}, failed=True)
     if names.returncode != 0 or patch.returncode != 0:
         return ChangedLineScope(frozenset(), {}, failed=True)
+    try:
+        initial_import.validate(root, context, staged=staged)
+    except ValueError:
+        return ChangedLineScope(frozenset(), {}, failed=True)
     affected = changes.paths & frozenset(selected) if selected else changes.paths
     return ChangedLineScope(affected, _changed_lines_from_patch(patch.stdout.decode("utf-8", errors="surrogateescape")))
 

code_standards-8.147.0/src/sarj_standards/libs/diagnostics/initial_import.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess  # ruff: ignore[suspicious-subprocess-import] -- bounded, fixed read-only Git argv except index tree materialization.
+
+
+_SOURCE_ENV = "SARJ_STANDARDS_INITIAL_IMPORT_SOURCE"
+_OID = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
+_GIT_INPUTS = frozenset({"GIT_INDEX_FILE", "GIT_ALTERNATE_OBJECT_DIRECTORIES"})
+
+
+@dataclass(frozen=True, slots=True)
+class InitialImport:
+    source: str
+    tree: str
+    parent: str
+
+
+def git_environment() -> dict[str, str]:
+    return {
+        name: value
+        for name, value in os.environ.items()  # ruff: ignore[banned-api] -- bind reads to the analyzed checkout while retaining explicit prospective index and object access.
+        if not name.startswith("GIT_") or name in _GIT_INPUTS
+    }
+
+
+def load(root: Path, *, staged: bool) -> InitialImport | None:
+    source = os.environ.get(_SOURCE_ENV)  # ruff: ignore[banned-api] -- explicit process-scoped native initial-import input, never inferred from repository settings.
+    if source is None:
+        return None
+    if not staged or _OID.fullmatch(source) is None:
+        msg = f"{_SOURCE_ENV} requires --staged and a full lowercase commit object ID"
+        raise ValueError(msg)
+    top = _git(root, "rev-parse", "--show-toplevel").removesuffix(b"\n").decode("utf-8", errors="surrogateescape")
+    if Path(top).resolve() != root.resolve():
+        msg = "initial import requires the analyzed Git worktree root"
+        raise ValueError(msg)
+    # A symbolic, missing HEAD distinguishes an initial commit from a broken detached checkout.
+    branch = _git(root, "symbolic-ref", "--quiet", "HEAD").removesuffix(b"\n").decode("utf-8", errors="surrogateescape")
+    if not branch.startswith("refs/heads/"):
+        msg = "initial import requires an unborn branch HEAD"
+        raise ValueError(msg)
+    _git(root, "show-ref", "--verify", "--quiet", branch, allowed=(1,))
+    context = _source_commit(root, source)
+    if _git(root, "write-tree").strip().decode("ascii") != context.tree:
+        msg = "initial-import index must exactly match the source commit tree"
+        raise ValueError(msg)
+    flags = _git(root, "ls-files", "-v", "-z").split(b"\0")
+    if any(entry and entry[:1] != b"H" for entry in flags):
+        msg = "initial import requires verifiable index flags"
+        raise ValueError(msg)
+    # Stat-only differences can return one with no content diff; numstat also captures mode/type changes.
+    if _git(
+        root,
+        "-c",
+        "core.filemode=true",
+        "diff",
+        "--exit-code",
+        "--numstat",
+        "-z",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--ignore-submodules=none",
+        "--",
+        allowed=(0, 1),
+    ):
+        msg = "initial-import tracked worktree must match the index"
+        raise ValueError(msg)
+    if _git(root, "ls-files", "--others", "--exclude-standard", "-z"):
+        msg = "initial import requires all nonignored worktree files to be staged"
+        raise ValueError(msg)
+    _git(
+        root,
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--ignore-submodules=none",
+        "--numstat",
+        "-z",
+        context.parent,
+        context.source,
+        "--",
+    )
+    return context
+
+
+def validate(root: Path, context: InitialImport | None, *, staged: bool) -> None:
+    source = os.environ.get(_SOURCE_ENV)  # ruff: ignore[banned-api] -- reject context activation as well as removal during an analysis transaction.
+    if (context is None and source is not None) or (context is not None and load(root, staged=staged) != context):
+        msg = "initial-import source context changed during analysis"
+        raise ValueError(msg)
+
+
+def _source_commit(root: Path, source: str) -> InitialImport:
+    if _git(root, "cat-file", "-t", source) != b"commit\n":
+        msg = "initial-import source must be an available commit"
+        raise ValueError(msg)
+    headers = _git(root, "cat-file", "commit", source).split(b"\n\n", 1)[0].splitlines()
+    trees = [line.removeprefix(b"tree ").decode("ascii") for line in headers if line.startswith(b"tree ")]
+    parents = [line.removeprefix(b"parent ").decode("ascii") for line in headers if line.startswith(b"parent ")]
+    if len(trees) != 1 or len(parents) != 1 or any(_OID.fullmatch(oid) is None for oid in (*trees, *parents)):
+        msg = "initial-import source must have exactly one available parent"
+        raise ValueError(msg)
+    if _git(root, "cat-file", "-t", parents[0]) != b"commit\n":
+        msg = "initial-import source parent must be an available commit"
+        raise ValueError(msg)
+    return InitialImport(source, trees[0], parents[0])
+
+
+def _git(root: Path, *arguments: str, allowed: tuple[int, ...] = (0,)) -> bytes:
+    git = shutil.which("git")
+    if git is None:
+        msg = "initial import requires Git"
+        raise ValueError(msg)
+    try:
+        result = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed Git argv, no shell, replacement objects or network fetches.
+            (
+                git,
+                "--no-replace-objects",
+                "--no-lazy-fetch",
+                "--literal-pathspecs",
+                "-c",
+                "diff.autoRefreshIndex=false",
+                *arguments,
+            ),
+            cwd=root,
+            check=False,
+            capture_output=True,
+            timeout=30,
+            env=git_environment(),
+        )
+    except (OSError, ValueError, subprocess.TimeoutExpired) as error:
+        msg = "cannot validate initial-import Git state"
+        raise ValueError(msg) from error
+    if result.returncode not in allowed:
+        msg = f"cannot validate initial-import Git state: {arguments[0]} failed"
+        raise ValueError(msg)
+    return result.stdout

{code_standards-8.144.0 → code_standards-8.147.0}/src/sarj_standards/libs/repository/docs.py

@@ -318,6 +318,17 @@ def _package_usage(name: str, engine: str | None) -> str:
             "Exclusions, baselines, and severities still apply; Ruff selectors are not supported. "
             "Native linters and ESLint execute only selected rules. ESLint retains configured parsers, options, "
             "severities, and suppression directives.\n\n"
+            "For a history-free initial import, set `SARJ_STANDARDS_INITIAL_IMPORT_SOURCE` only on the initial "
+            "commit process to the full lowercase object ID of an available source commit with exactly one available "
+            "parent. HEAD must be an unborn branch; the entire staged tree must equal that commit, tracked worktree "
+            "files must match the index without hidden index flags, and nonignored files must be staged. Native staged "
+            "checks compare the source commit with its parent, preserving the usual changed-line failures for findings "
+            "introduced in that commit while allowing inherited diagnostic budgets. Validation runs before and after "
+            "analysis; all analyzers and baseline limits still apply. The caller must qualify the source commit "
+            "separately. Git replacement objects and lazy fetching are disabled; explicitly supplied temporary object "
+            "alternates may provide the source history without copying it into the new repository. Remove the input "
+            "and alternates before subsequent commits, pushes, and CI. Invalid or changed import context fails "
+            "analysis, including clean reports; ordinary checks without this input retain their existing behavior.\n\n"
             "Selected ESLint checks apply live inline suppressions and validate selected bulk suppression "
             "counts. The complete lint gate owns unused inline-directive and inline-configuration checks: "
             "a partial run cannot establish whether an unselected rule's directive is needed.\n\n"