Add repo memory layer and agent governance

Co-Authored-By: Claude Fable 5 <[email protected]>

.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-<slug>.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.

.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

.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/<category>/` (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

.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/<category>/ 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":[]}

.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

.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 `<ticket-or-slug>.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.

.agents/proposals/README.md

@@ -0,0 +1,7 @@
+# Memory proposals
+
+Agents: drop candidate memories here, one file per proposal, named
+`YYYY-MM-DD-<slug>.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.

.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"}}
+  }
+}

.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

.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

.gitignore

@@ -36,3 +36,7 @@ test-results/
 memory-update.json
 memory-update.md
 .claude/
+
+# Agent-local memory state (never committed)
+.agents/private/
+.agents/state/

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: `<type>-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.

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/`.

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.