code-standards 8.129.11__tar.gz → 8.131.0__tar.gz

{code_standards-8.129.11 → code_standards-8.131.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-standards
-Version: 8.129.11
+Version: 8.131.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/
@@ -30,10 +30,10 @@ Requires-Dist: pyyaml==6.0.3
 Requires-Dist: referencing==0.37.0
 Requires-Dist: repo-standards==6.12.9
 Requires-Dist: ruff==0.17.2
-Requires-Dist: sarj-iac-lint==0.29.1
-Requires-Dist: sarj-python-lint==1.74.2
-Requires-Dist: sarj-rule-contracts==0.2.6
-Requires-Dist: sarj-sql-lint==0.25.1
+Requires-Dist: sarj-iac-lint==0.30.1
+Requires-Dist: sarj-python-lint==1.76.0
+Requires-Dist: sarj-rule-contracts==0.4.1
+Requires-Dist: sarj-sql-lint==0.26.1
 Requires-Dist: 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')
 Requires-Dist: typer==0.27.3
 Description-Content-Type: text/markdown
@@ -50,7 +50,7 @@ uv tool install --python 3.15 code-standards
 
 Adopt the repository once with `code-standards setup`. It installs one canonical staged gate that includes semantic lint and repository policy, plus commit-message and pull-request history enforcement. Do not install Repo Standards separately.
 
-The pre-commit gate runs once on every commit and discovers paths directly from the Git index, including mixed file types and deletion-only commits. The shared dispatcher selects applicable rules and retains type analysis, repository policy, exclusions and suppression accountability. Errors and incomplete analysis block the commit; warning-stage findings stay visible even when the hook passes. Agents should address the diagnostics, run `code-standards fix --staged` for safe mechanical fixes, review and stage intended edits, then retry. Staged fixes never fall back to the whole repository and refuse files with unstaged changes.
+The pre-commit gate runs once on every commit and discovers paths directly from the Git index, including mixed file types and deletion-only commits. The shared dispatcher selects applicable rules and retains type analysis, repository policy, exclusions and suppression accountability. Errors and incomplete analysis block the commit; warning-stage findings stay visible even when the hook passes. Generated hooks apply safe custom-rule, Ruff and ESLint fixes automatically. When a fix changes a staged file, the gate stops so you can review and stage the edit, then retry. Use `code-standards fix --staged` to apply fixes separately, or `check --fix` to fix before checking. Staged fixes never fall back to the whole repository and refuse files with unstaged changes.
 
 Setup installs the selected hook manager. In a fresh checkout, run `code-standards doctor --repair` before committing; doctor checks installation and the exact unconditional command. Conditional Lefthook jobs must be moved to an unconditional job without changing unrelated hooks. Git can bypass local hooks with `--no-verify`; the canonical CI gate independently enforces policy.
 

{code_standards-8.129.11 → code_standards-8.131.0}/README.md

@@ -10,7 +10,7 @@ uv tool install --python 3.15 code-standards
 
 Adopt the repository once with `code-standards setup`. It installs one canonical staged gate that includes semantic lint and repository policy, plus commit-message and pull-request history enforcement. Do not install Repo Standards separately.
 
-The pre-commit gate runs once on every commit and discovers paths directly from the Git index, including mixed file types and deletion-only commits. The shared dispatcher selects applicable rules and retains type analysis, repository policy, exclusions and suppression accountability. Errors and incomplete analysis block the commit; warning-stage findings stay visible even when the hook passes. Agents should address the diagnostics, run `code-standards fix --staged` for safe mechanical fixes, review and stage intended edits, then retry. Staged fixes never fall back to the whole repository and refuse files with unstaged changes.
+The pre-commit gate runs once on every commit and discovers paths directly from the Git index, including mixed file types and deletion-only commits. The shared dispatcher selects applicable rules and retains type analysis, repository policy, exclusions and suppression accountability. Errors and incomplete analysis block the commit; warning-stage findings stay visible even when the hook passes. Generated hooks apply safe custom-rule, Ruff and ESLint fixes automatically. When a fix changes a staged file, the gate stops so you can review and stage the edit, then retry. Use `code-standards fix --staged` to apply fixes separately, or `check --fix` to fix before checking. Staged fixes never fall back to the whole repository and refuse files with unstaged changes.
 
 Setup installs the selected hook manager. In a fresh checkout, run `code-standards doctor --repair` before committing; doctor checks installation and the exact unconditional command. Conditional Lefthook jobs must be moved to an unconditional job without changing unrelated hooks. Git can bypass local hooks with `--no-verify`; the canonical CI gate independently enforces policy.
 

{code_standards-8.129.11 → code_standards-8.131.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "code-standards"
-version = "8.129.11"
+version = "8.131.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"
@@ -17,7 +17,7 @@ classifiers = [
   "Topic :: Software Development :: Quality Assurance",
 ]
 dependencies = [
-  "sarj-rule-contracts==0.2.6",
+  "sarj-rule-contracts==0.4.1",
   "pathspec==1.1.1",
   "basedpyright==1.40.2",
   "deptry==0.25.1",
@@ -31,9 +31,9 @@ dependencies = [
   "repo-standards==6.12.9",
   "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.29.1",
-  "sarj-python-lint==1.74.2",
-  "sarj-sql-lint==0.25.1",
+  "sarj-iac-lint==0.30.1",
+  "sarj-python-lint==1.76.0",
+  "sarj-sql-lint==0.26.1",
   "typer==0.27.3",
 ]
 

{code_standards-8.129.11 → code_standards-8.131.0}/src/sarj_standards/api.py

@@ -391,31 +391,19 @@ class Standards:
     ) -> AnalysisReport:
         return self.analyze(paths, external=external, trust=trust, mode=mode, rules=rules, staged=staged, jobs=jobs)
 
-    def fix(self) -> Result:
-        from .libs.adoption import (  # ruff: ignore[import-outside-top-level] -- selected operation only
-            lifecycle,
-            scaffold,
-        )
-        from .libs.linting.python_fixes import fix_python  # ruff: ignore[import-outside-top-level] -- only fix needs native edit application.
+    def fix(self, paths: Sequence[str] | None = None) -> Result:
+        from .libs.linting import autofix  # ruff: ignore[import-outside-top-level] -- selected operation only.
 
         try:
-            adopted = load_manifest(self.root)
-            ecosystems = scaffold.detect(self.root) if adopted is None else scaffold.detect_adopted(self.root, adopted)
-            if ecosystems.python_root is not None:
-                selected = [str(self.root / path) for path in (adopted.verify_paths if adopted is not None else (".",))]
-                fix_python(
-                    selected,
-                    root=self.root,
-                    policy=Policy.from_manifest(self.root, adopted),
-                    python_root=ecosystems.python_root,
-                )
+            selected = [str(self.root / path) for path in paths] if paths is not None else [str(self.root)]
+            result = autofix.run(self.root, selected, trusted=True, default_scope=paths is None)
         except (OSError, SyntaxError, TypeError, UnicodeError, ValueError) as exc:
             return Result(
                 Status.INVALID,
                 findings=(Finding("fix.input.invalid", "error", str(exc)),),
                 exit_code=_INVALID_EXIT,
             )
-        return _operation_result(lifecycle.execute(lifecycle.format_commands(ecosystems, root=self.root)))
+        return _operation_result(result.status)
 
     def doctor(self) -> Result:
         diagnosed = diagnose(self.root)

{code_standards-8.129.11 → code_standards-8.131.0}/src/sarj_standards/cli/main.py

@@ -40,6 +40,7 @@ if TYPE_CHECKING:
 
     from sarj_standards.libs.adoption import doctor, lifecycle, service, upgrade
     from sarj_standards.libs.diagnostics import AnalysisReport, Diagnostic, ExecutionIssue
+    from sarj_standards.libs.linting import autofix
     from sarj_standards.libs.linting.external import UpstreamESLintRules
     from sarj_standards.libs.repository import rule_catalog_artifact
 
@@ -180,6 +181,7 @@ class _Args:
     exclude_kind: str = ""
     value: str = ""
     staged: bool = False
+    fix: bool = False
     release_commit: str = ""
     max_annotations_per_level: int = 10
     analysis_mode: str = "policy"
@@ -1119,9 +1121,15 @@ def cmd_library_policy(args: _Args, *, selected_paths: Iterable[str] | None = No
 
 
 def cmd_check(args: _Args) -> int:
-    from sarj_standards.libs.linting import runner  # ruff: ignore[import-outside-top-level] -- load sarj_standards.libs.linting only when this selected operation executes.
-
     root = _resolve_dest(args.dest)
+    if args.fix and args.selected_rules:
+        print(
+            "error: --fix applies the complete configured rule set; omit --rule or run check without --fix",
+            file=sys.stderr,
+        )
+        return 2
+    if args.fix and _validate_analysis_output(args, root):
+        return 2
     catalog_status = 0 if args.selected_rules else _check_conventional_slack_catalog(args, root)
     if catalog_status:
         return catalog_status
@@ -1134,14 +1142,29 @@ def cmd_check(args: _Args) -> int:
         scope.repository_wide = True
     if args.selected_rules:
         return _check_selected_rules(args, root, scope)
+    preparation_status = _prepare_check_inputs(args, root, scope)
+    if preparation_status is not None:
+        return preparation_status
+    if args.output_format != "text":
+        return _check_machine_output(args, root, scope)
+    return _check_text_output(args, root, scope)
+
+
+def _prepare_check_inputs(args: _Args, root: Path, scope: _CheckScope) -> int | None:
+    from sarj_standards.libs.linting import runner  # ruff: ignore[import-outside-top-level] -- source routing is needed only for check execution.
+
     if args.staged:
         health_status = _check_staged_adoption_health(root, args.files, args=args)
         if health_status:
             return health_status
         args.files = [path for path in args.files if runner.accepts_hook_path(Path(path), root=root)]
-    if args.output_format != "text":
-        return _check_machine_output(args, root, scope)
-    return _check_text_output(args, root, scope)
+    if args.fix:
+        result = _apply_safe_fixes(root, args.files, args=args, scoped=args.staged or scope.pull_request_scoped)
+        if result.status > 1:
+            return _emit_fix_failure(args, root, result.status)
+        if result.changed and args.staged:
+            return _emit_fix_review_required(args, root)
+    return None
 
 
 def _check_selected_rules(args: _Args, root: Path, scope: _CheckScope) -> int:
@@ -1236,7 +1259,7 @@ def _select_staged_check(args: _Args, root: Path, scope: _CheckScope) -> int | N
     try:
         staged_names = _staged_file_names(root)
         scope.react_doctor_triggered = _react_doctor_triggered_by(staged_names)
-        staged = _safe_staged_paths(root, staged_names)
+        staged = _safe_staged_paths(root, _staged_file_names(root, include_deleted=False))
     except (OSError, subprocess.SubprocessError) as exc:
         if args.output_format != "text":
             return _emit_analysis_report(args, root, _machine_input_error(root, f"cannot read staged files: {exc}"))
@@ -1246,15 +1269,21 @@ def _select_staged_check(args: _Args, root: Path, scope: _CheckScope) -> int | N
         requested = frozenset(_repository_relative_names(root, args.files))
         selected_staged_names = [name for name in staged_names if name in requested]
         staged_set = frozenset(staged)
-        args.files = [path for path in _safe_staged_paths(root, args.files) if path in staged_set]
+        args.files = _requested_staged_paths(root, args.files, staged=staged_set)
     else:
         selected_staged_names = staged_names
         args.files = staged
-    drifted = _unstaged_versions(root, selected_staged_names)
+    try:
+        drifted = _unstaged_versions(root, selected_staged_names)
+    except (OSError, subprocess.SubprocessError) as exc:
+        if args.output_format != "text":
+            return _emit_analysis_report(args, root, _machine_input_error(root, f"cannot read staged files: {exc}"))
+        print(f"error: cannot read staged files: {exc}", file=sys.stderr)
+        return 2
     if drifted:
         message = (
-            "--staged found files with unstaged content; run through pre-commit "
-            "(which safely stashes it) or stage the intended versions: " + ", ".join(drifted)
+            "--staged found files with unstaged content or unverifiable Git index flags; "
+            "stage the intended versions and clear assume-unchanged/skip-worktree flags: " + ", ".join(drifted)
         )
         if args.output_format != "text":
             return _emit_analysis_report(args, root, _machine_input_error(root, message))
@@ -1263,6 +1292,10 @@ def _select_staged_check(args: _Args, root: Path, scope: _CheckScope) -> int | N
     return None
 
 
+def _requested_staged_paths(root: Path, files: Sequence[str], *, staged: frozenset[str]) -> list[str]:
+    return [path for path in _safe_staged_paths(root, files) if path in staged]
+
+
 def _select_explicit_check(args: _Args, root: Path) -> int | None:
     try:
         args.files = _selected_paths(root, args.files)
@@ -2069,13 +2102,16 @@ def _emit_staged_adoption_health(args: _Args, root: Path, drifted: list[doctor.F
     return _emit_analysis_report(args, root, report)
 
 
-def _staged_file_names(root: Path) -> list[str]:
+def _staged_file_names(root: Path, *, include_deleted: bool = True) -> list[str]:
     git = shutil.which("git")
     if git is None:
         msg = "git is required for --staged"
         raise OSError(msg)
+    command = [git, "diff", "--cached", "--name-only", "-z"]
+    if not include_deleted:
+        command.append("--diff-filter=ACMRT")
     completed = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- fixed argv, no shell.
-        [git, "diff", "--cached", "--name-only", "-z"],
+        command,
         cwd=root,
         check=True,
         capture_output=True,
@@ -2152,6 +2188,19 @@ def _unstaged_versions(root: Path, staged_paths: Iterable[str]) -> tuple[str, ..
     )
     unstaged = {part.decode("utf-8", errors="surrogateescape") for part in completed.stdout.split(b"\0") if part}
     selected = set(_repository_relative_names(root, staged_paths))
+    if selected:
+        tracked = subprocess.run(  # ruff: ignore[subprocess-without-shell-equals-true] -- literal selected paths and NUL records preserve authored filenames.
+            [git, "--literal-pathspecs", "ls-files", "-v", "-z", "--", *sorted(selected)],
+            cwd=root,
+            check=True,
+            capture_output=True,
+            env=_git_environment(),
+        )
+        unstaged.update(
+            entry[2:].decode("utf-8", errors="surrogateescape")
+            for entry in tracked.stdout.split(b"\0")
+            if entry and (b"a" <= entry[:1] <= b"z" or entry[:1] == b"S")
+        )
     return tuple(sorted(unstaged & selected))
 
 
@@ -2211,7 +2260,7 @@ def _selected_paths(root: Path, paths: Iterable[str]) -> list[str]:
 
 
 def cmd_format(args: _Args) -> int:
-    from sarj_standards.libs.adoption import doctor  # ruff: ignore[import-outside-top-level] -- selected operation only.
+    from sarj_standards.libs.adoption import doctor  # ruff: ignore[import-outside-top-level] -- diagnosis gates an explicit fix operation.
 
     root = _resolve_dest(args.dest)
     diagnosed = doctor.diagnose(root)
@@ -2234,45 +2283,84 @@ def cmd_format(args: _Args) -> int:
         except ValueError as exc:
             print(f"error: {exc}", file=sys.stderr)
             return 2
-    return _execute_fixes(root, args.files, _declared_manifest(args))
+    return _apply_safe_fixes(root, args.files, args=args, trusted=True).status
 
 
-def _execute_fixes(root: Path, files: list[str], adopted: manifest.Manifest | None) -> int:
-    from sarj_standards.libs.adoption import lifecycle, scaffold  # ruff: ignore[import-outside-top-level] -- selected operation only.
-    from sarj_standards.libs.linting.python_fixes import fix_python  # ruff: ignore[import-outside-top-level] -- native edits precede upstream rewrites.
+def _apply_safe_fixes(
+    root: Path, files: Sequence[str], *, args: _Args, trusted: bool = False, scoped: bool = False
+) -> autofix.FixResult:
+    from sarj_standards.libs.linting import autofix  # ruff: ignore[import-outside-top-level] -- native fixers are not needed for read-only checks.
 
-    ecosystems = scaffold.detect(root) if adopted is None else scaffold.detect_adopted(root, adopted)
-    selected = files or [str(root / path) for path in (adopted.verify_paths if adopted is not None else (".",))]
+    requested = files if files or scoped else [str(root)]
     try:
-        if files:
-            fix_python(
-                [path for path in files if Path(path).is_file()], root=root, policy=Policy.from_manifest(root, adopted)
-            )
-        elif ecosystems.python_root is not None:
-            fix_python(
-                selected, root=root, policy=Policy.from_manifest(root, adopted), python_root=ecosystems.python_root
-            )
+        return autofix.run(
+            root,
+            requested,
+            trusted=trusted or args.trust_repository_code,
+            eslint=args.eslint,
+            machine_output=args.output_format != "text",
+            default_scope=not files and not scoped,
+        )
     except (OSError, SyntaxError, UnicodeError, ValueError) as exc:
-        print(f"error: native Python fixes failed: {exc}", file=sys.stderr)
-        return 2
-    commands = (
-        lifecycle.selected_format_commands(root, files) if files else lifecycle.format_commands(ecosystems, root=root)
+        print(f"error: cannot apply safe fixes: {exc}", file=sys.stderr)
+        return autofix.FixResult(2, ())
+
+
+def _emit_fix_failure(args: _Args, root: Path, status: int) -> int:
+    if args.output_format == "text":
+        return status
+    from sarj_standards.libs.diagnostics import (  # ruff: ignore[import-outside-top-level] -- failed fixes must preserve the requested machine report contract.
+        Completion,
+        ExecutionIssue,
+        ToolReport,
+    )
+    from sarj_standards.libs.linting.analysis import report_from_tools  # ruff: ignore[import-outside-top-level] -- use the existing analysis output contract.
+
+    issue = ExecutionIssue(
+        "sarj-standards-autofix",
+        "autofix-failed",
+        "Safe-fix execution failed. Review any applied changes and the tool error output, then retry.",
+        exit_code=status,
+    )
+    report = report_from_tools(root, (ToolReport("sarj-standards-autofix", Completion.FAILED, issues=(issue,)),))
+    return _emit_analysis_report(args, root, report)
+
+
+def _emit_fix_review_required(args: _Args, root: Path) -> int:
+    message = "Safe fixes applied. Review and stage the changes, then retry the commit."
+    if args.output_format == "text":
+        print(message, file=sys.stderr)
+        return 1
+    from sarj_standards.libs.diagnostics import (  # ruff: ignore[import-outside-top-level] -- structured results are needed only for machine output.
+        Completion,
+        Diagnostic,
+        Location,
+        Severity,
+        ToolReport,
+    )
+    from sarj_standards.libs.linting.analysis import report_from_tools  # ruff: ignore[import-outside-top-level] -- use the existing analysis output contract.
+
+    diagnostic = Diagnostic(
+        "fix.review-required",
+        message,
+        Severity.ERROR,
+        "sarj-standards-autofix",
+        Location("."),
+        rule_id="fix.review-required",
+        help="Review and stage the changes, then retry the commit.",
     )
-    return lifecycle.execute(commands)
+    report = report_from_tools(
+        root, (ToolReport("sarj-standards-autofix", Completion.COMPLETE, diagnostics=(diagnostic,)),)
+    )
+    return _emit_analysis_report(args, root, report)
 
 
 def _select_staged_fix(args: _Args, root: Path) -> int | None:
     try:
-        staged_names = _staged_file_names(root)
-        drifted = _unstaged_versions(root, staged_names)
-        if drifted:
-            print(
-                "error: --staged found files with unstaged content; stage the intended versions before fixing: "
-                + ", ".join(drifted),
-                file=sys.stderr,
-            )
-            return 2
-        args.files = _safe_staged_paths(root, staged_names)
+        args.files = _staged_fix_paths(root, args.files)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
     except (OSError, subprocess.SubprocessError) as exc:
         print(f"error: cannot read staged files: {exc}", file=sys.stderr)
         return 2
@@ -2282,8 +2370,23 @@ def _select_staged_fix(args: _Args, root: Path) -> int | None:
     return None
 
 
+def _staged_fix_paths(root: Path, files: Sequence[str]) -> list[str]:
+    staged_names = _staged_file_names(root, include_deleted=False)
+    if files:
+        requested = set(_repository_relative_names(root, files))
+        staged_names = [name for name in staged_names if name in requested]
+    if drifted := _unstaged_versions(root, staged_names):
+        msg = (
+            "--staged found files with unstaged content or unverifiable Git index flags; "
+            "stage the intended versions and clear assume-unchanged/skip-worktree flags before fixing: "
+            + ", ".join(drifted)
+        )
+        raise ValueError(msg)
+    return _safe_staged_paths(root, staged_names)
+
+
 def _staged_files(root: Path) -> list[str]:
-    return _safe_staged_paths(root, _staged_file_names(root))
+    return _safe_staged_paths(root, _staged_file_names(root, include_deleted=False))
 
 
 def cmd_inspect(args: _Args) -> int:
@@ -3167,6 +3270,10 @@ def build_app(handler: Callable[[_Args], int] = _dispatch) -> typer.Typer:
                 help="run the complete gate on staged files; optional paths narrow the staged selection",
             ),
         ] = False,
+        fix: Annotated[
+            bool,
+            typer.Option("--fix", help="apply safe fixes before checking; staged edits remain unstaged for review"),
+        ] = False,
         selected_rules: Annotated[
             list[RuleSelector] | None,
             typer.Option(
@@ -3189,6 +3296,7 @@ def build_app(handler: Callable[[_Args], int] = _dispatch) -> typer.Typer:
                 eslint=not skip_eslint,
                 trust_repository_code=trust_repository_code,
                 staged=staged,
+                fix=fix,
                 selected_rules=selected_rules if selected_rules is not None else [],
                 output_format=output_format.value,
                 output=output if output is not None else None,

{code_standards-8.129.11 → code_standards-8.131.0}/src/sarj_standards/configs/cli-reference.v1.json

@@ -454,6 +454,17 @@
           "required": false,
           "summary": "run the complete gate on staged files; optional paths narrow the staged selection"
         },
+        {
+          "choices": [],
+          "kind": "option",
+          "metavar": null,
+          "names": [
+            "--fix"
+          ],
+          "repeatable": false,
+          "required": false,
+          "summary": "apply safe fixes before checking; staged edits remain unstaged for review"
+        },
         {
           "choices": [],
           "kind": "option",
@@ -519,7 +530,7 @@
         "check"
       ],
       "summary": "run the complete quality gate or check selected paths or custom rules",
-      "usage": "code-standards check [-h] [--trust-repository-code] [--jobs JOBS] [--skip-python-type-check] [--skip-eslint] [--staged] [--rule SELECTED_RULES ...] [--format OUTPUT_FORMAT] [--output OUTPUT] [--max-annotations-per-level MAX_ANNOTATIONS_PER_LEVEL] [FILES ...]"
+      "usage": "code-standards check [-h] [--trust-repository-code] [--jobs JOBS] [--skip-python-type-check] [--skip-eslint] [--staged] [--fix] [--rule SELECTED_RULES ...] [--format OUTPUT_FORMAT] [--output OUTPUT] [--max-annotations-per-level MAX_ANNOTATIONS_PER_LEVEL] [FILES ...]"
     },
     {
       "commands": [],
@@ -3305,6 +3316,6 @@
   },
   "program": "code-standards",
   "schemaVersion": 1,
-  "summary": "Adopt, check, fix, diagnose, and update sarj-ai standards (v8.129.11).",
-  "version": "8.129.11"
+  "summary": "Adopt, check, fix, diagnose, and update sarj-ai standards (v8.131.0).",
+  "version": "8.131.0"
 }

{code_standards-8.129.11 → code_standards-8.131.0}/src/sarj_standards/configs/eslint.peers.json

@@ -19,7 +19,7 @@
     "@eslint-community/eslint-plugin-eslint-comments": "4.8.1",
     "@eslint/compat": "2.1.1",
     "@eslint/js": "10.0.1",
-    "@sarj/eslint-plugin": "16.29.0",
+    "@sarj/eslint-plugin": "16.30.0",
     "@shadcn/lint": "0.2.3",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/eslint-plugin": "1.6.28",
@@ -46,7 +46,7 @@
     "eslint-plugin-regexp": "3.3.1"
   },
   "ageGatePreapprovals": {
-    "@sarj/eslint-plugin": "16.29.0"
+    "@sarj/eslint-plugin": "16.30.0"
   },
   "yarnIdentityPins": {
     "@typescript-eslint/eslint-plugin": "8.72.0",

{code_standards-8.129.11 → code_standards-8.131.0}/src/sarj_standards/configs/rule-calibration-campaign.v1.json

@@ -805,8 +805,8 @@
       "family": "python",
       "ruleId": "prefer-fstring-over-concat",
       "state": "complete",
-      "evidence": "Three independent reviews ran 75 focused cases and scanned 7,098 tracked first-party Python files across 85 repositories plus a normalized 462-file Pygments and pytest corpus. The original broad rule produced 39 first-party findings with 17 bad recommendations and 130 popular-source findings dominated by regex, style-table, ANSI, path, identifier, and protocol fragments. Final calibration produced seven first-party and eleven popular-source warnings; all 18 were inspected as defensible human-readable interpolation improvements, with zero observed false positives or scanner errors. Additional strict-policy campaign (2026-10-13): pass 10 of 30 is hold-warning. Annotated str may be a subclass with different __add__ and __format__ behavior; current broad detector does not prove builtin-string operands. Reproducible final calibration, judge and performance evidence is recorded in packages/python/benchmarks/error-promotion-third-30-passes.json.",
-      "outcome": "Kept the compatible prefer-fstring-over-concat name and staged SARJ068 as a warning. Narrowed it to short prose-like interpolation inside callable scopes with proven string operands; added conservative binding and import provenance, late-rebinding kills, and exclusions for generated code, logging, common SQL and regex forms, long literals, module and class declarations, URL and path fragments, units, filenames, identifiers, protocol punctuation, lazy strings, and ORM expressions. Removed arbitrary operand-count join advice and comment bypasses. The UI now preserves explicit str and repr semantics with !s and !r instead of claiming wrappers can disappear."
+      "evidence": "Three independent reviews ran 75 focused cases and scanned 7,098 tracked first-party Python files across 85 repositories plus a normalized 462-file Pygments and pytest corpus. The original broad rule produced 39 first-party findings with 17 bad recommendations and 130 popular-source findings dominated by regex, style-table, ANSI, path, identifier, and protocol fragments. Final calibration produced seven first-party and eleven popular-source warnings; all 18 were inspected as defensible human-readable interpolation improvements, with zero observed false positives or scanner errors. Additional strict-policy campaign (2026-10-13): pass 10 of 30 is hold-warning. Annotated str may be a subclass with different __add__ and __format__ behavior; current broad detector does not prove builtin-string operands. Reproducible final calibration, judge and performance evidence is recorded in packages/python/benchmarks/error-promotion-third-30-passes.json. Follow-up: packages/python/benchmarks/service-contracts-and-ids-100-passes.json records 100 distinct semantic cases (39 true positives, 61 true negatives, no labeled false positives/negatives), five exact motivating blocking findings, deterministic three-trial cold/warm measurements on 296 guarded sample files, and completed local canonical gates. Private source and identifying pins remain local. Exact-head CI and broader review remain separate gates.",
+      "outcome": "Enforce supported short human-readable interpolation at ERROR, including stable named literal prefixes. This is a stricter reviewed style policy; str annotations do not prove custom operator/formatting equivalence, so required custom semantics retain exact reasoned exceptions. Source/configuration fragments, stable join aliases and other documented structural exclusions remain valid. Keep only the proven native-primitive builtin-conversion safe-fix subset; other repairs are manual."
     },
     {
       "task": "rule-audit/python/prefer-immutable-module-constant",
@@ -893,8 +893,8 @@
       "family": "python",
       "ruleId": "prefer-nominal-id-types",
       "state": "complete",
-      "evidence": "Three independent reviews ran the original 73 focused cases plus precedence coverage and scanned up to 7,120 tracked Python files plus a 443-file Pygments, packaging, and pytest corpus. The original matcher produced 373 fleet findings and reproduced false positives for unlike carriers, scalar versus collection roles, shadowed primitives, unrelated UUID and wrapper types, raw TypedDict and Pydantic wire models, decorated overrides, private boundaries, SQLAlchemy Mapped fields, and operational logging payloads. Post-change validation ran 78 focused cases and 87 with precedence; the broad fleet scan fell to 199 warning candidates, a focused three-repository scan fell from 120 to 21 manually reviewed credible domain boundaries, and the popular corpus remained at zero findings. September 2026 expansion: 58 focused cases (24 positive and 34 negative, zero unexpected matches or misses) plus 17 precedence cases cover imported carriers, declared-dependency and workspace isolation, canonical non-ID roles, shadowing, suppression, and error preservation. Pinned isolated evaluation scanned 2,624 tracked Python files (21,650,669 bytes) in two private corpora with fresh processes and at most 250 files per batch. All 41 existing errors retained their locations, severity, and messages; 100 additional warnings were inspected as credible nominal-domain opportunities, with no duplicate locations or known false positives. Calibration rejected 14 earlier cross-workspace candidates: matching distribution names do not establish a shared domain. This is local consumer evidence, not fleet-wide or public-project calibration. Final rule-only baseline/candidate passes took 5.61/18.40 seconds, with peak process memory 62.3/115.6 MiB. Alternating all-rule passes over the deterministic first 250 tracked files from each corpus took 23.325/21.907 seconds for baseline and 24.710/24.577 seconds for candidate (median ratio 1.090, below the 1.25 budget); peaks were 419.8/459.8 MiB. Shared host load remains a measurement limitation. Follow-up expert type-design fifty-pass review2026-10-16: source-proven literal/domain contract gaps and inherited, runtime-factory or compiler-policy boundaries were reviewed. packages/standards/benchmarks/expert-type-design-50-passes.json records decisions, finite calibration, exact pins, robustness closures, performance scope and validation. Conservative withdrawals of legacy policy diagnostics are not counts of demonstrated runtime defects.",
-      "outcome": "Promoted SARJ093 to error and expanded it to private, decorated, method, fake, override, and test boundaries after the motivating regressions escaped the former narrow scope. Primitive, UUID, wrapper, NewType, TypeAliasType, SQLAlchemy, Pydantic, and TypedDict decisions still require import provenance; unlike carrier shapes do not report. Generated, operational, raw-schema, SQLAlchemy Mapped, and direct Pydantic wire aliases remain excluded. Imported carrier and established non-ID coverage is staged per diagnostic as warning; shipped file-local errors, fingerprint messages, and default error metadata are unchanged. Candidate types are bounded to the owning distribution and unambiguous explicitly declared first-party dependencies, respecting nearest uv workspace members and exclusions. Canonical candidates require real typing.NewType provenance, exact role/carrier agreement, and unique production declarations. Conditional/relative imports, optional/transitive dependencies, unsupported workspace layouts, unresolved ownership, cycles, and ambiguous or mutated bindings deliberately remain unresolved. Imports are resolved only when demanded by carrier annotations or alias definitions. No autofix."
+      "evidence": "Three independent reviews ran the original 73 focused cases plus precedence coverage and scanned up to 7,120 tracked Python files plus a 443-file Pygments, packaging, and pytest corpus. The original matcher produced 373 fleet findings and reproduced false positives for unlike carriers, scalar versus collection roles, shadowed primitives, unrelated UUID and wrapper types, raw TypedDict and Pydantic wire models, decorated overrides, private boundaries, SQLAlchemy Mapped fields, and operational logging payloads. Post-change validation ran 78 focused cases and 87 with precedence; the broad fleet scan fell to 199 warning candidates, a focused three-repository scan fell from 120 to 21 manually reviewed credible domain boundaries, and the popular corpus remained at zero findings. September 2026 expansion: 58 focused cases (24 positive and 34 negative, zero unexpected matches or misses) plus 17 precedence cases cover imported carriers, declared-dependency and workspace isolation, canonical non-ID roles, shadowing, suppression, and error preservation. Pinned isolated evaluation scanned 2,624 tracked Python files (21,650,669 bytes) in two private corpora with fresh processes and at most 250 files per batch. All 41 existing errors retained their locations, severity, and messages; 100 additional warnings were inspected as credible nominal-domain opportunities, with no duplicate locations or known false positives. Calibration rejected 14 earlier cross-workspace candidates: matching distribution names do not establish a shared domain. This is local consumer evidence, not fleet-wide or public-project calibration. Final rule-only baseline/candidate passes took 5.61/18.40 seconds, with peak process memory 62.3/115.6 MiB. Alternating all-rule passes over the deterministic first 250 tracked files from each corpus took 23.325/21.907 seconds for baseline and 24.710/24.577 seconds for candidate (median ratio 1.090, below the 1.25 budget); peaks were 419.8/459.8 MiB. Shared host load remains a measurement limitation. Follow-up expert type-design fifty-pass review2026-10-16: source-proven literal/domain contract gaps and inherited, runtime-factory or compiler-policy boundaries were reviewed. packages/standards/benchmarks/expert-type-design-50-passes.json records decisions, finite calibration, exact pins, robustness closures, performance scope and validation. Conservative withdrawals of legacy policy diagnostics are not counts of demonstrated runtime defects. Follow-up: packages/python/benchmarks/service-contracts-and-ids-100-passes.json records 100 distinct semantic cases (39 true positives, 61 true negatives, no labeled false positives/negatives), five exact motivating blocking findings, deterministic three-trial cold/warm measurements on 296 guarded sample files, and completed local canonical gates. Private source and identifying pins remain local. Exact-head CI and broader review remain separate gates.",
+      "outcome": "Enforce SARJ093 at ERROR for existing two-role coverage, previously advisory imported/established-domain coverage and raw singleton IDs with a unique matching established nominal type. Preserve exact carrier and distribution/dependency ownership proof, ambiguity/shadowing/escape guards, inherited APIs, raw schemas and operational boundaries. No autofix."
     },
     {
       "task": "rule-audit/python/prefer-non-nullable-collection",
@@ -2485,8 +2485,8 @@
       "family": "python",
       "ruleId": "require-explicit-service-contract",
       "state": "pending",
-      "evidence": "Precision follow-up (2026-10-02): two independent policy/contract reviews reproduced existing Protocol, ABCMeta, abstract-declaration, value-dependency and unreachable-call misclassification. The refined rule passes 466 focused cases with SARJ071/466/467, full Python type checking, Ruff and all registered native rules on its source/tests. Generic adversarial regressions preserve services backed by stores and pools, a single operation and no substitution consumer. Private corpus evaluation is scoped separately; no fleet-wide precision claim. The pinned local-code reviewer caught a false negative where child-state assignment was mistaken for collaborator replacement; the fix preserves direct injected identity and four additional mutation regressions. The 96-case focused/combined/precedence suite passes after that correction. Follow-up 2026-10-12 additional thirty-pass campaign: Five judge rounds review strict typing and maintainability admission; bounded native WARNING tiers preserve runtime special signatures, source-visible model effects, variance/Self and frame/regex lifetime where relevant. Exact verification, corpus controls, sampling, performance and CI gate evidence is recorded in packages/python/benchmarks/error-promotion-next-30-passes.json.",
-      "outcome": "Retain SARJ465 as an explicitly requested proactive service-interface warning, without autofix or consumer-count gating. Reuse resolvable ABC or Protocol surfaces, including private, generic, inherited and imported aliased contracts; signatures remain the type checker responsibility. Only retained behavioral constructor collaborators and reachable public operations establish a candidate. Proven value/logging types, abstract declarations, static/class helpers and uncertain rewriting decorators/metaclasses are excluded. Structural Protocols visible only at external consumer/factory sites and dynamic aliases remain documented limits; do not manufacture a nominal duplicate or unnecessary public export. Promotion follow-up 2026-10-12: Enable the supported default at ERROR in Python 1.33.0 / TypeScript 16.8.0 / Standards 8.52.0. A retained collaborator and invoked public operations establish a service boundary whose operations lack a declared ABC or Protocol; reuse or declare a focused contract. No unsafe autofix or universal semantic-precision claim; preserve required contracts with the documented alternative or reasoned exact-code exception."
+      "evidence": "Precision follow-up (2026-10-02): two independent policy/contract reviews reproduced existing Protocol, ABCMeta, abstract-declaration, value-dependency and unreachable-call misclassification. The refined rule passes 466 focused cases with SARJ071/466/467, full Python type checking, Ruff and all registered native rules on its source/tests. Generic adversarial regressions preserve services backed by stores and pools, a single operation and no substitution consumer. Private corpus evaluation is scoped separately; no fleet-wide precision claim. The pinned local-code reviewer caught a false negative where child-state assignment was mistaken for collaborator replacement; the fix preserves direct injected identity and four additional mutation regressions. The 96-case focused/combined/precedence suite passes after that correction. Follow-up 2026-10-12 additional thirty-pass campaign: Five judge rounds review strict typing and maintainability admission; bounded native WARNING tiers preserve runtime special signatures, source-visible model effects, variance/Self and frame/regex lifetime where relevant. Exact verification, corpus controls, sampling, performance and CI gate evidence is recorded in packages/python/benchmarks/error-promotion-next-30-passes.json. Follow-up: packages/python/benchmarks/service-contracts-and-ids-100-passes.json records 100 distinct semantic cases (39 true positives, 61 true negatives, no labeled false positives/negatives), five exact motivating blocking findings, deterministic three-trial cold/warm measurements on 296 guarded sample files, and completed local canonical gates. Private source and identifying pins remain local. Exact-head CI and broader review remain separate gates.",
+      "outcome": "Retain SARJ465 at ERROR without autofix. Native retained-callback dispatch and per-call HTTP operations establish a service boundary regardless of Queue/Client suffixes. Reuse an ABC or Protocol that covers the operations. Preserve value/lifecycle exclusions, proven contract ancestry and unresolved/escaping ownership guards."
     },
     {
       "task": "rule-audit/typescript/require-explicit-service-contract",
@@ -2853,6 +2853,14 @@
       "state": "complete",
       "evidence": "Final supported-scope evaluation scans 2,830 pinned TypeScript files across nine isolated sources, capped at 250 files per fresh process with four cold/warm scans. All 74 target warnings are exhaustively inspected: 65 JSX, three dependency and six union findings, all labeled synthetic positives; zero confirmed false positives in the inspected final set and zero new real-code findings across 2,673 real files. Sixty-four ordinary-function JSX false negatives and 128 accepted explicit-forwarding sites remain recorded separately. The run has no parser failures and deterministic complete diagnostics. Its 7,440 missing-information occurrences are not unique dependencies or files and do not constitute a clean semantic scan. Generated, suppressed, incomplete, escaping, contextual and domain cases remain separate exclusions or unsupported cases. Three earlier fresh trials on 2,829 files remain historical evidence; their candidate was not qualified after an additional optional-covering-property counterexample was confirmed. The final narrower proof preserves every inspected warning tuple and accepts the separately appended regression. Exact source, corpus pins and raw evidence remain local; public reports omit private identities, source and identifying pins. Performance, full native verification, independent review and exact-head CI remain separate merge gates. Finite inspected precision is not universal absence of false positives. Native TypeScript 6.0.3 probes establish proper Dog-to-Animal coverage and independently reproduce Extract, in-narrowing and fresh-literal changes. Native assignability alone is insufficient: a covering-only optional property rejects an existing identifier, and global Object Any can supply an implicit witness. The corrected rule requires every covering member, including optional members, in the covered declared surface. Two ordinary/implicit-Any regressions and the shared erased-eval controls pass.",
       "outcome": "Ship the initial scope as WARNING without fixes or suggestions: an inline binary parameter union in the same proven private scalar-consumer boundary, complete readonly broad primitive object surfaces, proper one-way native assignability and all covering members explicitly present in the covered surface. Retain the covering type, never blindly the narrower subtype. Preserve public/type-level alternatives, producers, Any, unknown, generics, variance/callbacks, overloads, nominal/branded and incomplete contracts. General union simplification and Python imported-subtype approximation are withdrawn; error promotion needs a separate qualified change."
+    },
+    {
+      "task": "rule-audit/python/prefer-grouped-settings",
+      "family": "python",
+      "ruleId": "prefer-grouped-settings",
+      "state": "pending",
+      "evidence": "Twenty-eight focused settings checks cover repeated Python field namespaces, environment-alias independence, owned and inherited fields, ClassVar and Final metadata, private fields, generated and test exclusions, imported BaseSettings ancestry, stable locations and exact suppressions. Private source, paths and identifying pins stay outside public artifacts. Follow-up: packages/python/benchmarks/service-contracts-and-ids-100-passes.json records 100 distinct semantic cases (39 true positives, 61 true negatives, no labeled false positives/negatives), five exact motivating blocking findings, deterministic three-trial cold/warm measurements on 296 guarded sample files, and completed local canonical gates. Private source and identifying pins remain local. Exact-head CI and broader review remain separate gates.",
+      "outcome": "Stage SARJ532 at WARNING without autofix. At least two directly owned public BaseSettings fields must share a complete Python namespace token; environment aliases alone do not qualify. Forty-four matching groups in the private sample remain API/environment review advisories. Preserve existing loading, aliases, defaults and source precedence when grouping manually."
     }
   ]
 }