Merge pull request #14 from callowayproject/documentation

Remove outdated specs and enhance project documentation

Author: coordt

.pre-commit-config.yaml

@@ -54,11 +54,12 @@ repos:
     hooks:
       - id: interrogate
         exclude: test.*
-  - repo: https://github.com/python-jsonschema/check-jsonschema
-    rev: 0.37.1
+  - repo: https://github.com/rvben/rumdl-pre-commit
+    rev: v0.1.78  # Use latest version
     hooks:
-      - id: check-github-actions
-      - id: check-github-workflows
+      - id: rumdl      # Lint + auto-fix, fails if unfixable issues remain
+      - id: rumdl-fmt  # Pure format, always exits 0
+
 
 ci:
   autofix_prs: false

CHANGELOG.md

@@ -4,13 +4,28 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-**Foreman** is a minimal Python harness acting as an always-on AI co-maintainer for OSS repositories. It manages process lifecycle, credential injection, message routing, and GitHub event polling. All intelligence lives in containerized agents. The harness owns all GitHub API calls — agents only produce decision + action lists over HTTP, so credentials never enter agent containers.
+**Foreman** is a minimal Python harness acting as an always-on AI co-maintainer for OSS repositories.
+It manages process lifecycle, credential injection, message routing, and GitHub event polling.
+All intelligence lives in containerized agents.
+The harness owns all GitHub API calls — agents only produce decision + action lists over HTTP,
+so credentials never enter agent containers.
 
-The MVP target: a maintainer installs Foreman, configures one repo, and has issues triaged (labeled, responded to, or closed) without writing code — in under 30 minutes.
+The MVP target: a maintainer installs Foreman, configures one repo, and has issues triaged
+(labeled, responded to, or closed) without writing code — in under 30 minutes.
+
+## Spec-driven Development
+
+New features are developed by hashing out an idea.
+This idea is then turned into a spec.
+The spec is turned into a plan.
+The plan is iteratively implemented.
+
+All files for a feature are written in Markdown and live in the `docs/specs/<feature-name>/` directory.
 
 ## Commands
 
 ### Setup
+
 ```bash
 uv sync                        # install all dependency groups (dev, test, docs)
 pre-commit install             # install git hooks
@@ -31,6 +46,7 @@ pre-commit run --all-files                         # run all linters/formatters
 ```
 
 ### Entry point (once implemented)
+
 ```bash
 uv run foreman start --config config.yaml
 ```
@@ -39,7 +55,7 @@ uv run foreman start --config config.yaml
 
 The system follows a strict vertical ownership model:
 
-```
+```text
 GitHub API polling (poller.py)
     → Event router (router.py) — maps repo+event_type → agent URL
         → Harness HTTP server (server.py) — fetches memory, builds TaskMessage, POSTs to agent
@@ -48,25 +64,28 @@ GitHub API polling (poller.py)
         → Memory (memory.py) — logs every action, updates per-issue summaries
 ```
 
-**Key constraint:** The harness executes all GitHub API calls. Agents produce `DecisionMessage` (decision + action list) — they never call GitHub directly.
+**Key constraint:** The harness executes all GitHub API calls.
+Agents produce `DecisionMessage` (decision + action list) — they never call GitHub directly.
 
 ### Agent Protocol (JSON over HTTP)
 
 **Task (harness → agent):**
+
 ```json
 { "task_id": "uuid4", "type": "issue.triage", "repo": "owner/repo",
   "payload": {}, "context": { "memory_summary": "...", "llm_backend": {...} } }
 ```
 
 **Decision (agent → harness):**
+
 ```json
 { "task_id": "uuid4", "decision": "label_and_respond|close|escalate|skip",
   "rationale": "...", "actions": [{"type": "add_label", "label": "bug"}, ...] }
 ```
 
 ### Planned Module Structure
 
-```
+```text
 foreman/
 ├── config.py           # YAML config loader + Pydantic validation; ${VAR} env resolution
 ├── credentials.py      # Env var resolution; get_github_token()
@@ -89,14 +108,17 @@ agents/
 ### Memory (SQLite)
 
 Two tables in `~/.agent-harness/memory.db` (path overridable in config):
+
 - `action_log` — every decision logged before execution
 - `memory_summary` — per-repo+issue LLM-generated summary injected into task context on next dispatch
 
-SQLite is used directly via stdlib `sqlite3` — **never mock it in tests**; use a real temp-file DB via `pytest tmp_path`.
+SQLite is used directly via stdlib `sqlite3` — **never mock it in tests**;
+use a real temp-file DB via `pytest tmp_path`.
 
 ### Configuration (YAML)
 
-All secrets are `${VAR}` environment variable references — the config file itself never contains raw secrets. See `config.example.yaml` for the full schema.
+All secrets are `${VAR}` environment variable references — the config file itself never contains raw secrets.
+See `config.example.yaml` for the full schema.
 
 ## Code Style
 
@@ -106,27 +128,32 @@ All secrets are `${VAR}` environment variable references — the config file its
 - **Type hints:** required on all public functions and methods; `--keep-runtime-typing`
 - **Python minimum:** 3.12
 
-Pre-commit hooks enforce: ruff-format, ruff-check, mypy, pydoclint, interrogate, detect-secrets, pyupgrade, check-yaml, check-toml.
+Pre-commit hooks enforce: ruff-format, ruff-check, mypy, pydoclint, interrogate, detect-secrets, pyupgrade, check-yaml,
+check-toml.
 
 ## Testing Strategy
 
 - **Framework:** pytest + pytest-cov; target ≥85% line / ≥80% branch coverage
-- **LLM calls:** Recorded fixtures in `tests/fixtures/` — real responses captured once, replayed in CI. No live LLM calls.
+- **LLM calls:** Recorded fixtures in `tests/fixtures/` — real responses captured once, replayed in CI.
+    No live LLM calls.
 - **GitHub API calls:** Mock PyGithub/httpx at the boundary with pytest-mock.
 - **SQLite:** Use a real in-memory or temp-file DB — never mock it.
 - **Agent protocol:** Integration tests spin up the agent container locally and send real HTTP task messages.
 
 ## Behavioral Constraints
 
 **Always automatic:**
+
 - Poll configured repos on the set interval
 - Inject credentials from environment; never log or expose them
 - Write every decision and action to `action_log` before executing
 
 **Require explicit `allow_close: true` in agent config:**
+
 - Closing an issue (default: label + comment only)
 
 **Never:**
+
 - Call GitHub API as anything other than the configured bot identity
 - Store raw secrets in config, logs, or the memory DB
 - Execute shell commands or arbitrary code from agent decision payloads

CLAUDE.md

@@ -2,20 +2,16 @@
 
 ## Our Pledge
 
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
-identity and orientation.
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience
+for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance,
+race, caste, color, religion, or sexual identity and orientation.
 
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to a positive environment for our
-community include:
+Examples of behavior that contributes to a positive environment for our community include:
 
 * Demonstrating empathy and kindness toward other people
 * Being respectful of differing opinions, viewpoints, and experiences
@@ -38,92 +34,81 @@ Examples of unacceptable behavior include:
 
 ## Enforcement Responsibilities
 
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior
+and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate,
+threatening, offensive, or harmful.
 
-Community leaders have the right and responsibility to remove, edit, or reject
-comments, commits, code, wiki edits, issues, and other contributions that are
-not aligned to this Code of Conduct, and will communicate reasons for moderation
-decisions when appropriate.
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits,
+issues, and other contributions that are not aligned to this Code of Conduct,
+and will communicate reasons for moderation decisions when appropriate.
 
 ## Scope
 
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
+This Code of Conduct applies within all community spaces,
+and also applies when an individual is officially representing the community in public spaces.
 Examples of representing our community include using an official e-mail address,
-posting via an official social media account, or acting as an appointed
-representative at an online or offline event.
+posting via an official social media account, or acting as an appointed representative at an online or offline event.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-coreyoordt@gmail.com.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible
+for enforcement at <coreyoordt@gmail.com>.
 All complaints will be reviewed and investigated promptly and fairly.
 
-All community leaders are obligated to respect the privacy and security of the
-reporter of any incident.
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
 
 ## Enforcement Guidelines
 
-Community leaders will follow these Community Impact Guidelines in determining
-the consequences for any action they deem in violation of this Code of Conduct:
+Community leaders will follow these Community Impact Guidelines in determining the consequences
+for any action they deem in violation of this Code of Conduct:
 
 ### 1. Correction
 
-**Community Impact**: Use of inappropriate language or other behavior deemed
-unprofessional or unwelcome in the community.
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional
+or unwelcome in the community.
 
-**Consequence**: A private, written warning from community leaders, providing
-clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate.
+A public apology may be requested.
 
 ### 2. Warning
 
-**Community Impact**: A violation through a single incident or series of
-actions.
+**Community Impact**: A violation through a single incident or series of actions.
 
-**Consequence**: A warning with consequences for continued behavior. No
-interaction with the people involved, including unsolicited interaction with
-those enforcing the Code of Conduct, for a specified period of time. This
-includes avoiding interactions in community spaces as well as external channels
-like social media. Violating these terms may lead to a temporary or permanent
-ban.
+**Consequence**: A warning with consequences for continued behavior.
+No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct,
+for a specified period of time.
+This includes avoiding interactions in community spaces as well as external channels like social media.
+Violating these terms may lead to a temporary or permanent ban.
 
 ### 3. Temporary Ban
 
-**Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
 
-**Consequence**: A temporary ban from any sort of interaction or public
-communication with the community for a specified period of time. No public or
-private interaction with the people involved, including unsolicited interaction
-with those enforcing the Code of Conduct, is allowed during this period.
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community
+for a specified period of time.
+No public or private interaction with the people involved,
+including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period.
 Violating these terms may lead to a permanent ban.
 
 ### 4. Permanent Ban
 
-**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
-individual, or aggression toward or disparagement of classes of individuals.
+**Community Impact**: Demonstrating a pattern of violation of community standards,
+including sustained inappropriate behavior, harassment of an individual,
+or aggression toward or disparagement of classes of individuals.
 
-**Consequence**: A permanent ban from any sort of public interaction within the
-community.
+**Consequence**: A permanent ban from any sort of public interaction within the community.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.1, available at
-[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1,
+available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
 
-Community Impact Guidelines were inspired by
-[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
 
-For answers to common questions about this code of conduct, see the FAQ at
-[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
-[https://www.contributor-covenant.org/translations][translations].
+For answers to common questions about this code of conduct,
+see the FAQ at [https://www.contributor-covenant.org/faq][FAQ].
+Translations are available at [https://www.contributor-covenant.org/translations][translations].
 
 [homepage]: https://www.contributor-covenant.org
 [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html