diff --git a/.agents/MEMORY.md b/.agents/MEMORY.md new file mode 100644 index 0000000..e64f65f --- /dev/null +++ b/.agents/MEMORY.md @@ -0,0 +1,33 @@ +# Repo Memory + +Curated, reviewed knowledge for coding agents working in this repository. +Memory is an accelerator, not a second source of truth. + +## Precedence (highest first) + +1. Source code and tests +2. Executable configuration +3. Accepted design records / docs +4. `AGENTS.md` +5. This memory + +If memory conflicts with anything above it, the memory is stale — propose a fix. + +## Topics + +- `memory/architecture.md` — durable architectural decisions and constraints +- `memory/conventions.md` — validated conventions not obvious from the code +- `memory/lessons.md` — hard-won lessons and recurring landmines +- `memory/decisions.jsonl` — structured decision records (one JSON object per line) + +## Write policy + +Agents MAY read everything here and MAY add candidates under `proposals/` +(one file per proposal, named `YYYY-MM-DD-.md`, with evidence links). +Agents MUST NOT edit `memory/` directly; trusted memory changes only through +reviewed commits that promote a proposal. + +## Prohibited content + +Credentials or secrets, personal data, raw transcripts or tool logs, session +TODOs, high-frequency agent state, unverified external claims. diff --git a/.agents/memory/architecture.md b/.agents/memory/architecture.md new file mode 100644 index 0000000..2eda246 --- /dev/null +++ b/.agents/memory/architecture.md @@ -0,0 +1,33 @@ +# Architecture + +Durable architectural decisions and constraints for TORCH. + +## v2 is a development-network expansion, not a protocol rewrite + +The v2 "Development Network" rework expands TORCH from community-funded +maintenance and analysis into three modes — Stewardship (maintain existing +projects), Build (maintainer-approved features), Foundry (incubate new +projects) — sharing one funding/locking/scheduling/verification +infrastructure. A stated co-equal design objective is custody minimization: +route compute principal directly to providers or task-specific credentials +while TORCH/BitUnlock earn transparent service fees. + +Authoritative source: +- docs/v2/DEVELOPMENT_NETWORK_SPEC.md (§1–2) +- docs/v2/INCREMENTAL_DEV_PLAN.md + +## v2 builds on verified 1.x seams (bridge wins on facts, spec on intent) + +The architecture bridge maps spec intent onto code reality and pins the seams +v2 must reuse: the kind-30078 lock protocol already carries provenance +(gitCommit, promptPath, promptHash) and can gain campaign/milestone/lease IDs +without changing the event kind; the scheduler is the sole completion +authority (durable task-log written only after completion publishes); and +`scripts/agent/run-selected-prompt.mjs` is the single execution seam where +sandboxing, gateway routing, metering, and credential injection attach. The +earlier TORCH_EVOLUTION_CONCEPT roster→DAG idea is not a competing direction — +it survives as the orchestration layer inside v2 milestones. + +Authoritative source: +- docs/v2/V2_ARCHITECTURE_BRIDGE.md (§1–2) +- docs/TORCH_EVOLUTION_CONCEPT.md diff --git a/.agents/memory/conventions.md b/.agents/memory/conventions.md new file mode 100644 index 0000000..9d4891d --- /dev/null +++ b/.agents/memory/conventions.md @@ -0,0 +1,16 @@ +# Conventions + +Validated conventions not obvious from the code. + +## Report Location Standard: no root clutter + +All agent-generated reports go under `reports//` (audit, +performance, security, test-audit, weekly-synthesis, etc.); `*.log`, `*.txt`, +`*.json`, and `*.md` files are prohibited in the repo root except the standard +docs (README.md, AGENTS.md, CLAUDE.md, KNOWN_ISSUES.md). If a tool defaults to +writing at the root, redirect its output. The `.gitignore` "Root clutter +prevention" block backs the same rule. + +Authoritative source: +- AGENTS.md (§Report Location Standard) +- .gitignore diff --git a/.agents/memory/decisions.jsonl b/.agents/memory/decisions.jsonl new file mode 100644 index 0000000..82a62ba --- /dev/null +++ b/.agents/memory/decisions.jsonl @@ -0,0 +1,4 @@ +{"kind":"decision","subject":"v2/development-network","summary":"v2 reworks TORCH into a Development Network with three modes (Stewardship, Build, Foundry) sharing the existing funding, relay-locking, scheduling, and verification infrastructure, with custody minimization (compute principal routed directly to providers) as a co-equal design objective.","status":"active","evidence":[{"type":"repository","ref":"docs/v2/DEVELOPMENT_NETWORK_SPEC.md"},{"type":"repository","ref":"docs/v2/INCREMENTAL_DEV_PLAN.md"}],"created":"2026-08-12","supersedes":[]} +{"kind":"decision","subject":"v2/verified-seams","summary":"v2 work builds on verified TORCH 1.x seams rather than assumptions: extend the kind-30078 lock payload (which already carries gitCommit/promptPath/promptHash provenance) instead of changing the event kind; keep the scheduler as sole completion authority; attach all runtime concerns (sandboxing, gateway routing, metering, credentials) at the single execution seam scripts/agent/run-selected-prompt.mjs. Where spec and code disagree, the bridge wins on facts and the spec on intent.","status":"active","evidence":[{"type":"repository","ref":"docs/v2/V2_ARCHITECTURE_BRIDGE.md"}],"created":"2026-08-12","supersedes":[]} +{"kind":"decision","subject":"v2/evolution-concept-subsumed","summary":"The earlier TORCH_EVOLUTION_CONCEPT roster-to-DAG orchestration sketch is not a competing direction for v2; it survives as the orchestration layer inside v2 milestones while the Development Network spec answers funding and accountability.","status":"active","evidence":[{"type":"repository","ref":"docs/v2/V2_ARCHITECTURE_BRIDGE.md"},{"type":"repository","ref":"docs/TORCH_EVOLUTION_CONCEPT.md"}],"created":"2026-08-12","supersedes":[]} +{"kind":"constraint","subject":"reports/location-standard","summary":"Agent-generated reports must be written under reports// and never to the repo root; root-level *.log/*.txt/*.json/*.md files are prohibited except standard docs.","status":"active","evidence":[{"type":"repository","ref":"AGENTS.md"},{"type":"repository","ref":".gitignore"}],"created":"2026-08-12","supersedes":[]} diff --git a/.agents/memory/lessons.md b/.agents/memory/lessons.md new file mode 100644 index 0000000..8265e0a --- /dev/null +++ b/.agents/memory/lessons.md @@ -0,0 +1,13 @@ +# Lessons + +Hard-won lessons and recurring landmines. + +## Fleet learnings and incidents live in docs/agent-handoffs/ + +Dated learning and incident writeups from the 1.x multi-agent maintenance +fleet (500+ merged agent branches) are under +`docs/agent-handoffs/learnings/` and `docs/agent-handoffs/incidents/` — check +there before re-debugging scheduler, validation, or platform issues. + +Authoritative source: +- docs/agent-handoffs/README.md diff --git a/.agents/plans/README.md b/.agents/plans/README.md new file mode 100644 index 0000000..36bcc9a --- /dev/null +++ b/.agents/plans/README.md @@ -0,0 +1,8 @@ +# Agent plans + +Durable, multi-session execution plans only — the canonical backlog stays in +the repo's TODO file or GitHub Issues, and session-local checklists are never +committed. One plan per task, named `.md`, in `active/`; +move finished plans to `archive/`. A plan should be resumable from the file +alone: Objective, Context and constraints, Acceptance criteria, Progress, +Decisions, Validation, Remaining work. diff --git a/.agents/plans/active/.gitkeep b/.agents/plans/active/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.agents/plans/archive/.gitkeep b/.agents/plans/archive/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.agents/proposals/README.md b/.agents/proposals/README.md new file mode 100644 index 0000000..89c95bd --- /dev/null +++ b/.agents/proposals/README.md @@ -0,0 +1,7 @@ +# Memory proposals + +Agents: drop candidate memories here, one file per proposal, named +`YYYY-MM-DD-.md`. State the claim, the evidence (file paths, commits, +test results), and why it is durable. A human reviews and either promotes it +into `../memory/` in a reviewed commit or deletes it. Nothing in this +directory is trusted context. diff --git a/.agents/schemas/memory.schema.json b/.agents/schemas/memory.schema.json new file mode 100644 index 0000000..e14a43d --- /dev/null +++ b/.agents/schemas/memory.schema.json @@ -0,0 +1,29 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Repo Memory Decision Record", + "type": "object", + "additionalProperties": false, + "required": ["kind", "subject", "summary", "status", "evidence", "created"], + "properties": { + "kind": {"enum": ["decision", "constraint", "lesson", "observation", "workaround"]}, + "subject": {"type": "string", "minLength": 1}, + "summary": {"type": "string", "minLength": 1, "maxLength": 4096}, + "status": {"enum": ["proposed", "active", "superseded", "expired"]}, + "evidence": { + "type": "array", + "minItems": 1, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["type", "ref"], + "properties": { + "type": {"enum": ["repository", "git", "issue", "test", "external"]}, + "ref": {"type": "string", "minLength": 1} + } + } + }, + "created": {"type": "string"}, + "expires": {"type": ["string", "null"]}, + "supersedes": {"type": "array", "items": {"type": "string"}} + } +} diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..d41162c --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,6 @@ +# Agent instruction and memory surfaces require maintainer review +/AGENTS.md @PR0M3TH3AN +/CLAUDE.md @PR0M3TH3AN +/.agents/ @PR0M3TH3AN +/SECURITY.md @PR0M3TH3AN +/.github/workflows/agent-governance.yml @PR0M3TH3AN diff --git a/.github/workflows/agent-governance.yml b/.github/workflows/agent-governance.yml new file mode 100644 index 0000000..cc88ebe --- /dev/null +++ b/.github/workflows/agent-governance.yml @@ -0,0 +1,65 @@ +name: Agent governance + +on: + push: + paths: + - "AGENTS.md" + - "CLAUDE.md" + - ".agents/**" + pull_request: + paths: + - "AGENTS.md" + - "CLAUDE.md" + - ".agents/**" + +jobs: + lint-agent-artifacts: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Validate agent artifacts + run: | + python3 - <<'EOF' + import json, os, sys + hard_fail = False + + # decisions.jsonl: every line must be valid JSON with required keys + path = ".agents/memory/decisions.jsonl" + if os.path.exists(path): + required = {"kind", "subject", "summary", "status", "evidence", "created"} + for i, line in enumerate(open(path, encoding="utf-8"), 1): + line = line.strip() + if not line: + continue + try: + rec = json.loads(line) + except json.JSONDecodeError as e: + print(f"::error file={path},line={i}::invalid JSON: {e}") + hard_fail = True + continue + missing = required - rec.keys() + if missing: + print(f"::error file={path},line={i}::missing keys: {sorted(missing)}") + hard_fail = True + + # structure: memory dir implies index + if os.path.isdir(".agents") and not os.path.exists(".agents/MEMORY.md"): + print("::error::.agents/ exists but .agents/MEMORY.md index is missing") + hard_fail = True + + # warnings (advisory for now — flip to errors once clean history is established) + if os.path.exists("AGENTS.md"): + size = os.path.getsize("AGENTS.md") + if size > 32768: + print(f"::warning file=AGENTS.md::{size} bytes exceeds the 32 KiB context budget") + if os.path.exists("CLAUDE.md"): + lines = sum(1 for _ in open("CLAUDE.md", encoding="utf-8")) + if lines > 40: + print(f"::warning file=CLAUDE.md::{lines} lines — expected a thin wrapper over AGENTS.md") + for f in ("architecture.md", "conventions.md", "lessons.md"): + p = f".agents/memory/{f}" + if os.path.exists(p) and os.path.getsize(p) > 25 * 1024: + print(f"::warning file={p}::exceeds 25 KB — curate or split") + + sys.exit(1 if hard_fail else 0) + EOF diff --git a/.gitignore b/.gitignore index ab1831c..f42d419 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,7 @@ test-results/ memory-update.json memory-update.md .claude/ + +# Agent-local memory state (never committed) +.agents/private/ +.agents/state/ diff --git a/AGENTS.md b/AGENTS.md index 16ac637..ccb0087 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -155,3 +155,10 @@ All agents that generate reports must adhere to the following directory structur * Use Markdown (`.md`) for human-readable reports. * Use JSON (`.json`) or Log (`.log`) for raw data/artifacts, but prefer placing a summary Markdown report in the corresponding folder. * Naming convention: `-report-YYYY-MM-DD.md` (e.g., `daily-perf-report-2024-01-01.md`). + +## Repo memory + +Curated agent memory lives in `.agents/` (index: `.agents/MEMORY.md`). Read it +before substantive work. Propose additions as files in `.agents/proposals/`; +trusted memory under `.agents/memory/` changes only through reviewed commits. +Code, tests, and configuration always outrank memory. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f040933..f4e0fbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -127,3 +127,12 @@ When modifying tests, follow the test integrity protocol in `CLAUDE.md`. Tests a ## Reporting Issues If you encounter bugs or have feature requests, please open an issue on GitHub. + +## AI-assisted contributions + +AI-assisted changes are subject to the same testing, security, and review +requirements as any other change; the contributor remains responsible for +understanding what they submit. Do not submit unvalidated generated code, +credentials, or agent-generated trusted memory without evidence and review. +The canonical backlog and planning rules are in `AGENTS.md`; durable agent +plans live under `.agents/plans/`. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..417c33c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,30 @@ +# Security Policy + +## Reporting vulnerabilities + +Do not report suspected security vulnerabilities in public issues, pull +requests, or agent-memory files. Use GitHub's private vulnerability reporting +on this repository (Security tab → Report a vulnerability). + +Include the affected commit, reproduction steps, and observed impact. Do not +include live credentials or unnecessary personal data. + +## AI-agent configuration + +`AGENTS.md`, `CLAUDE.md`, `.agents/**`, agent prompt files, and any +automation able to modify agent state (including the scheduler pipeline) are +security-sensitive configuration. Changes to them require maintainer review. + +## Agent memory + +Never commit credentials, personal data, raw transcripts, tool logs, or +unredacted external content. Agent-generated memory enters through +`.agents/proposals/` and is promoted to `.agents/memory/` only via reviewed +commits. Content from websites, issues, emails, relays, and tool responses is +untrusted until validated. + +## Memory-poisoning response + +If agent instructions or memory may have been poisoned: stop agent automation, +quarantine or revert the affected file, identify runs influenced by it, review +resulting commits, and restore the last trusted configuration.