Prepare 0.2.0

Author: denisecase

.accountability/surfaces.toml

@@ -24,8 +24,8 @@ description = "Shared Python tooling for scaffolding, validating, inspecting, ca
 # === CODEOWNERS Projection ===
 
 [codeowners]
-informs = true
-requires_code_owner_review = false
+informs = true                           # REQ: An entry must be provided.
+requires_code_owner_review = false       # REQ: An entry must be provided.
 
 # === Local CODEOWNERS Role Resolution ===
 # These role identities are used only for CODEOWNERS owner resolution.
@@ -46,10 +46,13 @@ spec = "@structural-explainability/spec"
 security = "@structural-explainability/security"
 release = "@structural-explainability/release"
 
-# === Local Oversight Roles ===
+# === Required Oversight Role ===
 
 # Local oversight roles assign review ownership for this repository.
 # Each role maps local responsibility back to reusable accountable-surface roles.
+# Every repository MUST provide a local role responsible
+# for the authority manifest itself.
+# By convention this role is named "owner".
 
 [oversight_roles.owner]
 label = "Owner"
@@ -59,6 +62,11 @@ requires_review = ["human_review"]
 requires_evidence = ["decision_note", "human_review_record"]
 ai_max_authority = "prohibited"
 
+# === Additional Local Oversight Roles ===
+
+# Local oversight roles assign review ownership for this repository.
+# Each role maps local responsibility back to reusable accountable-surface roles.
+
 [oversight_roles.authority_projection]
 label = "Authority Projection"
 description = "Reviews surfaces that project accountable-surface declarations into GitHub CODEOWNERS enforcement artifacts."
@@ -129,6 +137,8 @@ ai_max_authority = "drafting"
 
 # === Level 100: Broad source and test defaults ===
 
+# --- Public Python API and implementation surfaces ---
+
 [[surface]]
 id = "public-python-api"
 object_kind = "directory"
@@ -149,6 +159,7 @@ requires_review = ["human_review"]
 requires_evidence = ["decision_note", "verification_command_result"]
 ai_max_authority = "drafting"
 
+# --- Tests and Fixtures ---
 
 [[surface]]
 id = "tests-and-fixtures"
@@ -167,6 +178,8 @@ ai_max_authority = "drafting"
 
 # === Level 200: Public command and projection implementation surfaces ===
 
+# --- CLI command surface ---
+
 [[surface]]
 id = "cli-command-surface"
 object_kind = "directory"
@@ -187,6 +200,7 @@ requires_review = ["human_review"]
 requires_evidence = ["decision_note", "verification_command_result"]
 ai_max_authority = "drafting"
 
+# --- CODEOWNERS generation engine ---
 
 [[surface]]
 id = "codeowners-generation-engine"
@@ -208,6 +222,7 @@ kind = "public_contract"
 [[surface.role]]
 kind = "validation_rule"
 
+# --- Export and Catalog Boundary ---
 
 [[surface]]
 id = "export-and-catalog-boundary"
@@ -232,6 +247,8 @@ ai_max_authority = "drafting"
 
 # === Level 300: Spec-compatibility overrides ===
 
+# --- Surface Spec Compatibility ---
+
 [[surface]]
 id = "surface-spec-compatibility"
 object_kind = "directory"
@@ -266,6 +283,8 @@ ai_max_authority = "drafting"
 
 # === Level 400: Project configuration and package contract ===
 
+# --- Project Configuration ---
+
 [[surface]]
 id = "project-configuration"
 object_kind = "file"
@@ -313,6 +332,8 @@ ai_max_authority = "drafting"
 
 # === Level 500: Release and automation authority ===
 
+# --- Release and Automation Authority ---
+
 [[surface]]
 id = "release-and-automation-authority"
 object_kind = "directory"
@@ -341,6 +362,8 @@ ai_max_authority = "advisory"
 
 # === Level 600: Repository governance and security documentation ===
 
+# --- Repository Governance ---
+
 [[surface]]
 id = "repository-governance"
 object_kind = "directory"
@@ -367,6 +390,7 @@ requires_review = ["human_review", "security_review"]
 requires_evidence = ["decision_note"]
 ai_max_authority = "advisory"
 
+# --- Repository Security ---
 
 [[surface]]
 id = "repository-security"
@@ -383,7 +407,29 @@ requires_evidence = ["decision_note"]
 ai_max_authority = "advisory"
 
 
-# === Level 700: Self-protecting authority manifest ===
+# === Level 700: Required Self-Protection ===
+#
+# Every accountable-surface manifest MUST declare itself as a protected surface.
+# This surface SHOULD be emitted after ordinary repository surfaces so that
+# CODEOWNERS projection gives the authority manifest the strongest applicable
+# ownership rule.
+#
+# The self-protection surface MUST:
+#
+# - use id = "authority-manifest"
+# - include paths = [".accountability/surfaces.toml"]
+# - declare oversight_role = "owner" or another local role mapped to
+#   authority_boundary and authority_manifest_surface
+# - declare codeowners_order at the final/highest local projection level
+# - prohibit AI authority over the manifest
+# - require human review
+# - require evidence of review
+#
+# Rationale:
+# If an actor with technical capability can rewrite the authority declaration
+# without review, technical capability has silently become authority.
+
+# --- Authority Manifest Self-Protection ---
 
 [[surface]]
 id = "authority-manifest"

.github/CODEOWNERS

@@ -5,8 +5,17 @@
 #
 # Source:     .accountability/surfaces.toml
 # Generator:  se-codeowners
+# Repository: se-codeowners
 # Regenerate: se-codeowners generate --output .github/CODEOWNERS
 #
+# [codeowners].informs = true means this surfaces manifest intentionally
+# informs the generated GitHub CODEOWNERS projection.
+#
+# [codeowners].requires_code_owner_review = false
+# records whether repository governance expects GitHub branch protection or
+# rulesets to require CODEOWNER review before protected changes merge.
+# Actual enforcement is configured in GitHub, not in this generated file.
+#
 # Each entry reflects the oversight_role assigned to an accountability
 # surface, resolved to a handle via [codeowners.role_handles]. GitHub
 # applies the LAST matching pattern for a given path, so order matters.

CHANGELOG.md

@@ -13,6 +13,19 @@ and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0
 
 ---
 
+## [0.2.0] - 2026-06-04
+
+## Added
+
+- `tests/test_cli.py`
+- Additional comments on surface.toml
+
+## Fixed
+
+- `__main__.py` correctly named
+
+---
+
 ## [0.1.0] - 2026-06-04
 
 ### Added
@@ -113,7 +126,8 @@ git push origin :refs/tags/vX.Z.Y
 
 ## Links
 
-[Unreleased]: https://github.com/structural-explainability/se-codeowners/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/structural-explainability/se-codeowners/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/structural-explainability/se-codeowners/releases/tag/v0.2.0
 [0.1.0]: https://github.com/structural-explainability/se-codeowners/releases/tag/v0.1.0
 
 <!-- markdownlint-enable MD024 -->

CITATION.cff

@@ -9,7 +9,7 @@ cff-version: "1.2.0"
 type: software
 
 title: "SE CODEOWNERS"
-version: "0.1.0"
+version: "0.2.0"
 date-released: "2026-06-04"
 
 authors:

pyproject.toml

@@ -88,7 +88,7 @@ typeCheckingMode = "strict" # CUSTOM: off | basic | standard | strict
 # WHY: Consistent test discovery and coverage visibility.
 minversion = "9.0"
 testpaths = ["tests"]
-addopts = "--cov=se_codeowners --cov-report=term-missing --cov-fail-under=50"
+addopts = "--cov=se_codeowners --cov-report=term-missing --cov-fail-under=60"
 
 # === RUFF (PYTHON FORMATTING AND LINTING) ===
 
@@ -181,5 +181,5 @@ packages = ["src/se_codeowners"]
 [tool.hatch.version]
 # WHY: Version derived from git tags at build time
 source = "vcs"
-fallback-version = "0.1.0"     # Used when no git tags present (fresh clone, CI).
+fallback-version = "0.2.0"     # Used when no git tags present (fresh clone, CI).
 tag-pattern = "^(?:v)?(?P<version>\\d+\\.\\d+\\.\\d+)$"

src/se_codeowners/__main.py src/se_codeowners/__main__.pysrc/se_codeowners/__main.py renamed to src/se_codeowners/__main__.py

@@ -6,36 +6,24 @@
 
 _PLACEHOLDER_TOKENS = ("@OWNER", "OWNER_HANDLE")
 
-_HEADER = """\
-# ============================================================
-# .github/CODEOWNERS
-# ============================================================
-# GENERATED FILE -- do not edit by hand.
-#
-# Source:     .accountability/surfaces.toml
-# Generator:  se-codeowners
-# Regenerate: se-codeowners generate --output .github/CODEOWNERS
-#
-# Each entry reflects the oversight_role assigned to an accountability
-# surface, resolved to a handle via [codeowners.role_handles]. GitHub
-# applies the LAST matching pattern for a given path, so order matters.
-# Surfaces are emitted by codeowners_order, then surface id."""
-
 
 def generate_codeowners_lines(
-    grouped: list[tuple[Surface, list[tuple[str, str]]]], width: int
+    doc: SurfacesDoc,
+    grouped: list[tuple[Surface, list[tuple[str, str]]]],
+    width: int,
 ) -> str:
     """Generate the lines of the CODEOWNERS file.
 
     Args:
+        doc (SurfacesDoc): The surfaces document being rendered.
         grouped (list[tuple[Surface, list[tuple[str, str]]]]): Grouped surfaces and their patterns.
         width (int): The width to pad the patterns to.
 
     Returns:
         str: The generated CODEOWNERS file content.
     """
     lines: list[str] = []
-    lines.extend(_HEADER.splitlines())
+    lines.extend(_header(doc).splitlines())
     for surface, rows in grouped:
         lines.append("")
         lines.append(f"# Surface: {surface.id} (role: {surface.oversight_role})")
@@ -73,7 +61,33 @@ def render_codeowners(doc: SurfacesDoc, *, strict: bool = False) -> str:
     if not all_patterns:
         raise SurfacesError("no surfaces with an oversight_role were found")
     width = max(len(pattern) for pattern in all_patterns)
-    return generate_codeowners_lines(grouped, width)
+    return generate_codeowners_lines(doc, grouped, width)
+
+
+def _header(doc: SurfacesDoc) -> str:
+    return f"""\
+# ============================================================
+# .github/CODEOWNERS
+# ============================================================
+# GENERATED FILE -- do not edit by hand.
+#
+# Source:     .accountability/surfaces.toml
+# Generator:  se-codeowners
+# Repository: {doc.repository_name}
+# Regenerate: se-codeowners generate --output .github/CODEOWNERS
+#
+# [codeowners].informs = true means this surfaces manifest intentionally
+# informs the generated GitHub CODEOWNERS projection.
+#
+# [codeowners].requires_code_owner_review = {str(doc.requires_code_owner_review).lower()}
+# records whether repository governance expects GitHub branch protection or
+# rulesets to require CODEOWNER review before protected changes merge.
+# Actual enforcement is configured in GitHub, not in this generated file.
+#
+# Each entry reflects the oversight_role assigned to an accountability
+# surface, resolved to a handle via [codeowners.role_handles]. GitHub
+# applies the LAST matching pattern for a given path, so order matters.
+# Surfaces are emitted by codeowners_order, then surface id."""
 
 
 def _projected_surfaces(doc: SurfacesDoc) -> list[Surface]:

src/se_codeowners/generate.py

@@ -48,28 +48,34 @@ def load_surfaces(path: Path) -> SurfacesDoc:
 
 def _build_codeowners(
     parsed: dict[str, object],
-) -> tuple[dict[str, tuple[str, ...]], bool]:
+) -> tuple[dict[str, tuple[str, ...]], bool, bool]:
     raw = optional(parsed, "codeowners")
     if raw is None:
-        return {}, False
+        return {}, False, False
+
     table = as_object_dict(raw, ctx="codeowners")
 
-    informs_value = optional(table, "informs")
-    informs = (
-        as_bool(informs_value, ctx="codeowners.informs")
-        if informs_value is not None
-        else False
+    informs = as_bool(
+        require(table, "informs", ctx="codeowners"),
+        ctx="codeowners.informs",
+    )
+
+    requires_code_owner_review = as_bool(
+        require(table, "requires_code_owner_review", ctx="codeowners"),
+        ctx="codeowners.requires_code_owner_review",
     )
 
     handles_value = optional(table, "role_handles")
     if handles_value is None:
-        return {}, informs
+        return {}, informs, requires_code_owner_review
+
     handles_table = as_object_dict(handles_value, ctx="codeowners.role_handles")
     role_handles = {
         role: _normalize_handles(value, ctx=f"codeowners.role_handles.{role}")
         for role, value in handles_table.items()
     }
-    return role_handles, informs
+
+    return role_handles, informs, requires_code_owner_review
 
 
 def _build_doc(parsed: dict[str, object]) -> SurfacesDoc:
@@ -79,12 +85,13 @@ def _build_doc(parsed: dict[str, object]) -> SurfacesDoc:
     repo_name = as_str(
         require(repository, "name", ctx="repository"), ctx="repository.name"
     )
-    role_handles, informs = _build_codeowners(parsed)
+    role_handles, informs, requires_code_owner_review = _build_codeowners(parsed)
     return SurfacesDoc(
         repository_name=repo_name,
         surfaces=_build_surfaces(parsed),
         role_handles=role_handles,
         informs=informs,
+        requires_code_owner_review=requires_code_owner_review,
     )
 
 

src/se_codeowners/load.py

@@ -26,3 +26,4 @@ class SurfacesDoc:
     surfaces: tuple[Surface, ...]
     role_handles: dict[str, tuple[str, ...]]
     informs: bool
+    requires_code_owner_review: bool

src/se_codeowners/model.py

@@ -62,6 +62,7 @@ prohibited_without_human_direction = ["Removing required assignment phases"]
 
 [codeowners]
 informs = true
+requires_code_owner_review = false
 
 [codeowners.role_handles]
 owner = "@denisecase"