audit_agent_setup Namespace Reference

Functions
dict[str, str]	frontmatter (Path path)
	Parse the simple YAML front matter used by a skill file.
dict[str, Path]	skill_entries (Path root)
	Return skill directories directly below one discovery root.
set[str]	entry_names (Path root)
	Return every direct child name under a skill discovery root.
None	remove_entry (Path path)
	Remove one skill-tree entry without following a directory symlink.
None	synchronize ()
	Materialize byte-identical Claude skill copies from the canonical tree.
subprocess.CompletedProcess[str]	git (*str args)
	Run Git with machine-global excludes disabled.
list[str]	audit ()
	Validate shared instructions, skill discovery copies, and local-settings hygiene.
argparse.Namespace	parse_args (list[str] argv)
	Parse audit command-line arguments.
int	main (list[str]|None argv=None)
	Synchronize when requested, then fail closed on portability drift.

Variables
	REPO_ROOT = Path(__file__).resolve().parents[2]
str	CANONICAL_ROOT = REPO_ROOT / ".agents" / "skills"
str	CLAUDE_ROOT = REPO_ROOT / ".claude" / "skills"
dict	EXPECTED_SKILLS
str	LOCAL_SETTINGS = ".claude/settings.local.json"
str	LOCAL_SETTINGS_PATTERN = "/.claude/settings.local.json"

Detailed Description

Audit and synchronize the repository-portable agent instruction setup.

Function Documentation

frontmatter()

dict[str, str] audit_agent_setup.frontmatter

(

Path

path

)

Parse the simple YAML front matter used by a skill file.

Parameters

[in]

path

Skill file to inspect.

Returns

Parsed scalar front-matter fields.

Definition at line 26 of file audit_agent_setup.py.

def frontmatter(path: Path) -> dict[str, str]:
    """!
    @brief Parse the simple YAML front matter used by a skill file.
    @param[in] path Skill file to inspect.
    @return Parsed scalar front-matter fields.
    """
 
    lines = path.read_text(encoding="utf-8").splitlines()
    if not lines or lines[0] != "---":
        return {}
    fields: dict[str, str] = {}
    for line in lines[1:]:
        if line == "---":
            return fields
        if ":" in line:
            key, value = line.split(":", 1)
            fields[key.strip()] = value.strip()
    return {}
 
 

Here is the caller graph for this function:

skill_entries()

dict[str, Path] audit_agent_setup.skill_entries

(

Path

root

)

Return skill directories directly below one discovery root.

Parameters

[in]

root

Skill discovery directory.

Returns

Mapping from directory name to path, including symlinked directories.

Definition at line 46 of file audit_agent_setup.py.

def skill_entries(root: Path) -> dict[str, Path]:
    """!
    @brief Return skill directories directly below one discovery root.
    @param[in] root Skill discovery directory.
    @return Mapping from directory name to path, including symlinked directories.
    """
 
    if not root.is_dir():
        return {}
    return {
        child.name: child
        for child in root.iterdir()
        if child.is_dir() or child.is_symlink()
    }
 
 

Here is the caller graph for this function:

entry_names()

set[str] audit_agent_setup.entry_names

(

Path

root

)

Return every direct child name under a skill discovery root.

Parameters

[in]

root

Skill discovery directory.

Returns

Child-name set, including unexpected files and links.

Definition at line 62 of file audit_agent_setup.py.

def entry_names(root: Path) -> set[str]:
    """!
    @brief Return every direct child name under a skill discovery root.
    @param[in] root Skill discovery directory.
    @return Child-name set, including unexpected files and links.
    """
 
    return {child.name for child in root.iterdir()} if root.is_dir() else set()
 
 

Here is the caller graph for this function:

remove_entry()

None audit_agent_setup.remove_entry

(

Path

path

)

Remove one skill-tree entry without following a directory symlink.

Parameters

[in]

path

Exact materialized or symlinked skill path.

Returns

None.

Definition at line 72 of file audit_agent_setup.py.

def remove_entry(path: Path) -> None:
    """!
    @brief Remove one skill-tree entry without following a directory symlink.
    @param[in] path Exact materialized or symlinked skill path.
    @return None.
    """
 
    if path.is_symlink() or path.is_file():
        path.unlink()
    elif path.is_dir():
        shutil.rmtree(path)
 
 

Here is the caller graph for this function:

synchronize()

None audit_agent_setup.synchronize

(

)

Materialize byte-identical Claude skill copies from the canonical tree.

Returns

None.

Exceptions

RuntimeError

when the canonical skill set is incomplete or unexpected.

Definition at line 85 of file audit_agent_setup.py.

def synchronize() -> None:
    """!
    @brief Materialize byte-identical Claude skill copies from the canonical tree.
    @return None.
    @throws RuntimeError when the canonical skill set is incomplete or unexpected.
    """
 
    canonical = skill_entries(CANONICAL_ROOT)
    canonical_names = entry_names(CANONICAL_ROOT)
    if canonical_names != EXPECTED_SKILLS:
        missing = sorted(EXPECTED_SKILLS - canonical_names)
        extra = sorted(canonical_names - EXPECTED_SKILLS)
        raise RuntimeError(f"canonical skill set differs: missing={missing}, extra={extra}")
 
    CLAUDE_ROOT.mkdir(parents=True, exist_ok=True)
    for path in list(CLAUDE_ROOT.iterdir()):
        remove_entry(path)
    for name in sorted(EXPECTED_SKILLS):
        shutil.copytree(canonical[name], CLAUDE_ROOT / name, symlinks=False)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

git()

subprocess.CompletedProcess[str] audit_agent_setup.git

(

*str

args

)

Run Git with machine-global excludes disabled.

Parameters

[in]

args

Arguments following git.

Returns

Completed process with captured text output.

Definition at line 106 of file audit_agent_setup.py.

def git(*args: str) -> subprocess.CompletedProcess[str]:
    """!
    @brief Run Git with machine-global excludes disabled.
    @param[in] args Arguments following `git`.
    @return Completed process with captured text output.
    """
 
    return subprocess.run(
        ["git", "-c", "core.excludesFile=/dev/null", "-C", str(REPO_ROOT), *args],
        capture_output=True,
        text=True,
        check=False,
    )
 
 

Here is the caller graph for this function:

audit()

list[str] audit_agent_setup.audit

(

)

Validate shared instructions, skill discovery copies, and local-settings hygiene.

Returns

Human-readable violations; an empty list means the audit passed.

Definition at line 121 of file audit_agent_setup.py.

def audit() -> list[str]:
    """!
    @brief Validate shared instructions, skill discovery copies, and local-settings hygiene.
    @return Human-readable violations; an empty list means the audit passed.
    """
 
    errors: list[str] = []
    agents = REPO_ROOT / "AGENTS.md"
    claude = REPO_ROOT / "CLAUDE.md"
 
    if not agents.is_file() or agents.is_symlink():
        errors.append("AGENTS.md must be a tracked regular file, not a symlink")
    if not claude.is_file() or claude.is_symlink():
        errors.append("CLAUDE.md must be a regular file, not a symlink")
    elif "@AGENTS.md" not in {line.strip() for line in claude.read_text(encoding="utf-8").splitlines()}:
        errors.append("CLAUDE.md must import the canonical @AGENTS.md instructions")
 
    canonical = skill_entries(CANONICAL_ROOT)
    copies = skill_entries(CLAUDE_ROOT)
    canonical_names = entry_names(CANONICAL_ROOT)
    copy_names = entry_names(CLAUDE_ROOT)
    if canonical_names != EXPECTED_SKILLS:
        errors.append(
            "canonical skill set mismatch: "
            f"missing={sorted(EXPECTED_SKILLS - canonical_names)}, "
            f"extra={sorted(canonical_names - EXPECTED_SKILLS)}"
        )
    if copy_names != EXPECTED_SKILLS:
        errors.append(
            "Claude skill set mismatch: "
            f"missing={sorted(EXPECTED_SKILLS - copy_names)}, "
            f"extra={sorted(copy_names - EXPECTED_SKILLS)}; run make sync-agent-skills"
        )
 
    for name in sorted(EXPECTED_SKILLS & set(canonical)):
        source_dir = canonical[name]
        source = source_dir / "SKILL.md"
        if source_dir.is_symlink() or not source.is_file() or source.is_symlink():
            errors.append(f"canonical skill {name} must contain a regular SKILL.md")
            continue
        metadata = frontmatter(source)
        if metadata.get("name") != name:
            errors.append(f"{source.relative_to(REPO_ROOT)} front-matter name must be {name!r}")
        if not metadata.get("description"):
            errors.append(f"{source.relative_to(REPO_ROOT)} requires a non-empty description")
 
        target_dir = copies.get(name)
        target = target_dir / "SKILL.md" if target_dir else None
        if target_dir is None:
            continue
        if target_dir.is_symlink() or target is None or not target.is_file() or target.is_symlink():
            errors.append(f"Claude skill {name} must be a materialized regular-file copy")
            continue
        source_files = sorted(
            path.relative_to(source_dir) for path in source_dir.rglob("*") if path.is_file()
        )
        target_files = sorted(
            path.relative_to(target_dir) for path in target_dir.rglob("*") if path.is_file()
        )
        if source_files != target_files:
            errors.append(f"Claude skill {name} file set differs; run make sync-agent-skills")
            continue
        for relative in source_files:
            if (source_dir / relative).read_bytes() != (target_dir / relative).read_bytes():
                errors.append(
                    f"Claude skill {name}/{relative} differs byte-for-byte; "
                    "run make sync-agent-skills"
                )
 
    tracked = git("ls-files", "--error-unmatch", "--", LOCAL_SETTINGS)
    if tracked.returncode == 0:
        errors.append(f"{LOCAL_SETTINGS} is machine-local and must not be tracked")
    ignored = git("check-ignore", "-v", "--", LOCAL_SETTINGS)
    if ignored.returncode != 0:
        errors.append(f"{LOCAL_SETTINGS} must be ignored by the repository .gitignore")
    else:
        fields = ignored.stdout.rstrip().split("\t", 1)[0].rsplit(":", 2)
        source = fields[0] if len(fields) == 3 else ""
        pattern = fields[2] if len(fields) == 3 else ""
        if Path(source).name != ".gitignore" or pattern != LOCAL_SETTINGS_PATTERN:
            errors.append(
                f"{LOCAL_SETTINGS} must use the exact repository ignore pattern "
                f"{LOCAL_SETTINGS_PATTERN!r}, not a user-global or incidental rule"
            )
 
    return errors
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

parse_args()

argparse.Namespace audit_agent_setup.parse_args

(

list[str]

argv

)

Parse audit command-line arguments.

Parameters

[in]

argv

Arguments excluding the executable name.

Returns

Parsed command-line namespace.

Definition at line 209 of file audit_agent_setup.py.

def parse_args(argv: list[str]) -> argparse.Namespace:
    """!
    @brief Parse audit command-line arguments.
    @param[in] argv Arguments excluding the executable name.
    @return Parsed command-line namespace.
    """
 
    parser = argparse.ArgumentParser(
        description="Audit or synchronize PICurv's portable shared agent setup."
    )
    parser.add_argument(
        "--sync",
        action="store_true",
        help="replace Claude skill entries with materialized copies of canonical .agents skills",
    )
    return parser.parse_args(argv)
 
 

Here is the caller graph for this function:

main()

int audit_agent_setup.main

(

list[str] | None

argv = None

)

Synchronize when requested, then fail closed on portability drift.

Parameters

[in]

argv

Optional arguments excluding the executable name.

Returns

Zero on success and one on any setup violation.

Definition at line 227 of file audit_agent_setup.py.

def main(argv: list[str] | None = None) -> int:
    """!
    @brief Synchronize when requested, then fail closed on portability drift.
    @param[in] argv Optional arguments excluding the executable name.
    @return Zero on success and one on any setup violation.
    """
 
    args = parse_args(sys.argv[1:] if argv is None else argv)
    try:
        if args.sync:
            synchronize()
    except (OSError, RuntimeError) as error:
        print(f"Agent setup synchronization failed: {error}", file=sys.stderr)
        return 1
 
    errors = audit()
    if errors:
        for error in errors:
            print(f"ERROR: {error}", file=sys.stderr)
        return 1
    action = "synchronized and audited" if args.sync else "audited"
    print(f"Agent setup {action}: shared instructions and {len(EXPECTED_SKILLS)} skills are portable.")
    return 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

REPO_ROOT

audit_agent_setup.REPO_ROOT = Path(__file__).resolve().parents[2]

Definition at line 13 of file audit_agent_setup.py.

CANONICAL_ROOT

str audit_agent_setup.CANONICAL_ROOT = REPO_ROOT / ".agents" / "skills"

Definition at line 14 of file audit_agent_setup.py.

CLAUDE_ROOT

str audit_agent_setup.CLAUDE_ROOT = REPO_ROOT / ".claude" / "skills"

Definition at line 15 of file audit_agent_setup.py.

EXPECTED_SKILLS

dict audit_agent_setup.EXPECTED_SKILLS

Initial value:

=  {
    "picurv-capability-change",
    "picurv-solver-debugging",
    "picurv-spatial-kernel-change",
    "picurv-technical-communication",
}

Definition at line 16 of file audit_agent_setup.py.

LOCAL_SETTINGS

str audit_agent_setup.LOCAL_SETTINGS = ".claude/settings.local.json"

Definition at line 22 of file audit_agent_setup.py.

LOCAL_SETTINGS_PATTERN

str audit_agent_setup.LOCAL_SETTINGS_PATTERN = "/.claude/settings.local.json"

Definition at line 23 of file audit_agent_setup.py.