agent-rules-kit 0.2.1__tar.gz

agent_rules_kit-0.2.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,107 @@
+name: Bug report
+description: Report reproducible incorrect behavior in agent-rules-kit.
+title: "bug: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug.
+
+        Before submitting, please read README.md, AGENTS.md, SECURITY.md, CONTRIBUTING.md, and SUPPORT.md.
+
+        Do not include secrets, tokens, credentials, cookies, private URLs, customer data, or sensitive repository contents.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: Describe the incorrect behavior clearly.
+      placeholder: What is wrong?
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Describe what should have happened.
+      placeholder: What did you expect?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Describe what happened instead.
+      placeholder: What actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction steps
+      description: Provide minimal steps to reproduce the issue.
+      placeholder: |
+        1. Run ...
+        2. Observe ...
+        3. See error ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: command-output
+    attributes:
+      label: Relevant command output
+      description: Paste only non-sensitive output. Redact anything secret-like.
+      render: text
+      placeholder: Paste safe output here.
+    validations:
+      required: false
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      description: Example: CachyOS, Ubuntu, macOS, Windows.
+      placeholder: CachyOS
+    validations:
+      required: false
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Run python --version.
+      placeholder: Python 3.12.x
+    validations:
+      required: false
+
+  - type: dropdown
+    id: impact
+    attributes:
+      label: Impact area
+      description: Choose the main area affected.
+      options:
+        - correctness
+        - safety boundary
+        - documentation
+        - usability
+        - tests
+        - CI
+        - unknown
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: confirmation
+    attributes:
+      label: Confirmation
+      options:
+        - label: I did not include secrets, tokens, credentials, cookies, private URLs, or customer data.
+          required: true
+        - label: I understand this tool is not a security scanner and provides no security guarantees.
+          required: true
+        - label: I understand this project must not execute commands from analyzed repositories.
+          required: true

agent_rules_kit-0.2.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,116 @@
+name: Feature request
+description: Propose a focused, reviewable improvement to agent-rules-kit.
+title: "feat: "
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for proposing an improvement.
+
+        Before submitting, please read README.md, AGENTS.md, SECURITY.md, CONTRIBUTING.md, CHANGELOG.md, and SUPPORT.md.
+
+        Keep the request narrow, testable, local-first, and aligned with the project boundaries.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What concrete problem would this solve?
+      placeholder: Describe the user pain or maintenance problem.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the smallest useful change.
+      placeholder: What should be added or changed?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Explain simpler or safer alternatives, including doing nothing.
+      placeholder: What alternatives did you consider?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Main scope
+      description: Choose the primary area.
+      options:
+        - CLI behavior
+        - rule detection
+        - reporting output
+        - documentation
+        - tests
+        - CI / GitHub configuration
+        - project policy
+        - unknown
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: boundaries
+    attributes:
+      label: Boundary check
+      options:
+        - label: This request keeps runtime behavior local-first.
+          required: true
+        - label: This request does not require network access in runtime behavior.
+          required: true
+        - label: This request does not require an LLM dependency in runtime behavior.
+          required: true
+        - label: This request does not require executing commands from analyzed repositories.
+          required: true
+        - label: This request does not claim the tool is a security scanner.
+          required: true
+        - label: This request does not add unsupported security guarantees.
+          required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: How should maintainers know this is done?
+      placeholder: |
+        - Given ...
+        - When ...
+        - Then ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: testing
+    attributes:
+      label: Testing plan
+      description: Describe the tests or checks that should verify the change.
+      placeholder: Expected minimum: ./scripts/check.sh and focused tests.
+    validations:
+      required: true
+
+  - type: textarea
+    id: risks
+    attributes:
+      label: Risks and limitations
+      description: Mention possible safety, maintenance, compatibility, or usability risks.
+      placeholder: What could go wrong or be misunderstood?
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: confirmation
+    attributes:
+      label: Confirmation
+      options:
+        - label: I kept this request narrow and reviewable.
+          required: true
+        - label: I did not include secrets, tokens, credentials, private URLs, customer data, or sensitive repository contents.
+          required: true
+        - label: I understand this project favors small, testable changes over broad rewrites.
+          required: true

agent_rules_kit-0.2.1/.github/pull_request_template.md

@@ -0,0 +1,72 @@
+# Pull Request
+
+## Summary
+
+Describe the change in one or two clear sentences.
+
+## Why
+
+Explain why this change is needed.
+
+## Scope
+
+This PR changes:
+
+- [ ] source code
+- [ ] tests
+- [ ] documentation
+- [ ] CI / GitHub configuration
+- [ ] security-sensitive behavior
+- [ ] project policy or workflow
+
+## Checks
+
+Before marking this PR ready, confirm:
+
+- [ ] I read AGENTS.md.
+- [ ] I changed one minimal unit.
+- [ ] I did not use git add .
+- [ ] I reviewed the staged diff.
+- [ ] I ran ./scripts/check.sh.
+- [ ] Tests pass locally.
+- [ ] CI is expected to pass.
+- [ ] No secrets, tokens, credentials, private URLs, or customer data were added.
+- [ ] No unsupported production or security claims were added.
+
+## Security and boundary impact
+
+Does this change touch any of these areas?
+
+- [ ] secret detection
+- [ ] redaction
+- [ ] file traversal
+- [ ] symlink handling
+- [ ] write behavior
+- [ ] command execution boundaries
+- [ ] network behavior
+- [ ] LLM behavior
+- [ ] GitHub Actions permissions
+- [ ] none of the above
+
+If any box except "none of the above" is checked, explain the risk and mitigation.
+
+## Testing evidence
+
+Paste the relevant local output or summarize it precisely.
+
+Expected minimum:
+
+./scripts/check.sh
+
+## Known limitations
+
+List any known limitation, tradeoff, or follow-up needed.
+
+## Release notes
+
+Should this affect CHANGELOG.md?
+
+- [ ] yes
+- [ ] no
+
+If yes, explain the changelog entry.

agent_rules_kit-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  local-checks:
+    name: local-checks / Python 3.12
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install project and dev dependencies
+        run: python -m pip install -e '.[dev]'
+
+      - name: Run local checks
+        run: ./scripts/check.sh
+
+      - name: Run installed package smoke checks
+        run: |
+          agent-rules-kit --version
+          agent-rules-kit check tests/fixtures/repositories/single-agent --format json | python -m json.tool

agent_rules_kit-0.2.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,99 @@
+name: Publish PyPI
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-pypi-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build / distributions
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools and project development dependencies
+        run: |
+          python -m pip install -U build twine
+          python -m pip install -e '.[dev]'
+
+      - name: Verify release ref matches package version
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))["project"]["version"]
+          ref_name = os.environ.get("GITHUB_REF_NAME", "")
+          event_name = os.environ.get("GITHUB_EVENT_NAME", "")
+
+          print(f"project_version={version}")
+          print(f"github_event={event_name}")
+          print(f"github_ref_name={ref_name}")
+
+          if event_name == "release" and ref_name != f"v{version}":
+              raise SystemExit(f"release ref {ref_name!r} does not match package version v{version}")
+          PY
+
+      - name: Run local checks
+        run: ./scripts/check.sh
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Smoke test wheel
+        run: |
+          python -m venv /tmp/agent-rules-kit-wheel-smoke
+          /tmp/agent-rules-kit-wheel-smoke/bin/python -m pip install dist/*.whl
+          /tmp/agent-rules-kit-wheel-smoke/bin/python -m pip check
+          /tmp/agent-rules-kit-wheel-smoke/bin/agent-rules-kit --version
+          /tmp/agent-rules-kit-wheel-smoke/bin/agent-rules-kit check tests/fixtures/repositories/single-agent --format json | /tmp/agent-rules-kit-wheel-smoke/bin/python -m json.tool
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish:
+    name: publish / PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: python-distributions
+          path: dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_rules_kit-0.2.1/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Build artifacts
+build/
+dist/
+*.egg-info/
+
+# Local/editor files
+.DS_Store
+*.swp
+*.swo
+.idea/
+.vscode/
+
+# Environment and secrets
+.env
+.env.*
+!.env.example
+
+# Logs
+*.log

agent_rules_kit-0.2.1/AGENTS.md

@@ -0,0 +1,195 @@
+# AGENTS.md — agent-rules-kit
+
+Scope: this file applies repository-wide to all work in this repository, unless a more specific nested AGENTS.md exists for a subtree.
+Authority: explicit user instructions come first, then this AGENTS.md, then repository documentation and runbooks.
+
+This file is mandatory for every AI assistant, coding agent, or chat working on this repository.
+
+The repository must be handled with strict CDLAN discipline. Do not improvise a new workflow.
+
+## Current project
+
+agent-rules-kit is a local Python CLI that diagnoses baseline quality of AI agent instruction files in repositories.
+
+Core boundaries:
+
+- Local-first.
+- Read-only by default.
+- No network access in runtime behavior.
+- No LLM dependency in runtime behavior.
+- No execution of commands from analyzed repositories.
+- No security guarantees or exaggerated claims.
+- Secret-like findings must be redacted.
+
+## Operating modes
+
+There are two different work modes.
+
+### Mode 1 — Genesis / Inception
+
+Genesis is only for creating the project from zero before remote GitHub protection exists.
+
+During Genesis, work on main is temporarily allowed, but only under these rules:
+
+- main must start clean before every mutation.
+- Create one file at a time whenever possible.
+- Before stage, the prompt/status should show exactly one untracked or modified item.
+- Stage exactly one file.
+- Review the staged diff visibly.
+- Commit that one file.
+- Return main to clean state.
+- Repeat.
+
+Genesis pattern:
+
+- main clean.
+- create one file.
+- validate that file.
+- status shows one change.
+- stage exact file only.
+- staged shows one file.
+- diff staged is visible.
+- no unstaged changes.
+- commit.
+- main clean.
+
+Allowed exception:
+
+- The first identity baseline may include README.md, LICENSE, and .gitignore together because they form the repository identity baseline.
+
+### Mode 2 — Always-Green
+
+Always-Green begins only after Genesis is closed.
+
+Genesis is closed when:
+
+- local main is clean;
+- local checks pass;
+- AGENTS.md exists;
+- scripts/check.sh exists and passes;
+- tests exist and pass;
+- CI exists or a documented reason explains why it does not yet exist;
+- remote is created intentionally;
+- initial push is verified;
+- main protection/ruleset is applied or explicitly tracked as a blocker.
+
+After Genesis closes:
+
+- Do not work directly on main.
+- Create a specific branch for every logical phase.
+- Read real files before editing.
+- Make minimal changes.
+- Run checks before stage.
+- Stage exact files only.
+- Never use git add .
+- Review staged diff fully.
+- Commit small.
+- Push branch only after local gates pass.
+- Open PR.
+- Merge only after checks are green.
+- Return main to clean synchronized state.
+
+## Absolute prohibitions
+
+Do not:
+
+- use git add .;
+- commit without staged review;
+- push just to see if CI passes;
+- create or push a remote before local Genesis gates pass;
+- work on main after Genesis is closed;
+- hide failing checks;
+- invent unsupported claims;
+- add secrets, tokens, credentials, cookies, keys, or private URLs;
+- add network behavior without explicit approval;
+- add LLM behavior without explicit approval;
+- execute commands from repositories being analyzed;
+- overwrite files without reading existing state first.
+
+## Zsh and terminal safety
+
+The user works in zsh.
+
+Never use `path` as a shell variable name in zsh commands.
+
+Reason: in zsh, `path` is tied to `PATH`. Using `path` as a variable can break PATH and make basic commands unavailable.
+
+Use these names instead:
+
+- item
+- entry
+- target
+- target_dir
+- file_item
+- file_name
+- repo_dir
+- repo_root
+
+If basic commands such as git, mkdir, chmod, cat, or python suddenly return command not found, check PATH first.
+
+Safe temporary PATH repair:
+
+export PATH="/usr/local/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+
+## Required checks
+
+Before every commit:
+
+- git status --short --branch
+- git diff --name-status
+- git diff --cached --name-status
+- git diff --cached --check
+- visible staged diff with git --no-pager diff --cached --no-ext-diff
+- file-specific validation
+- scripts/check.sh when it exists and applies
+
+For Python files:
+
+- compile the file;
+- run related tests;
+- ensure UTF-8, LF, final newline, and no trailing whitespace.
+
+For shell files:
+
+- sh -n file;
+- executable bit must be intentional and verified when needed.
+
+For documentation:
+
+- no internal secrets;
+- no fake claims;
+- no unsupported production/security promises.
+
+## Commit discipline
+
+Commit messages must be small and specific.
+
+Examples:
+
+- chore: add repository identity baseline
+- chore: add python project metadata
+- chore: add package version module
+- feat: add initial cli entrypoint
+- test: add cli smoke tests
+- chore: add local check script
+
+Do not combine unrelated changes.
+
+## If anything fails
+
+Stop immediately.
+
+Do not continue building on a failed step.
+
+Required recovery sequence:
+
+- inspect status;
+- inspect changed files;
+- identify the exact failure;
+- clean or revert explicitly;
+- return to the last clean commit;
+- retry with smaller granularity.
+
+Do not guess.
+Do not patch blindly.
+Do not keep going after a broken command.