@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/org-memory-api-payload-examples.md

@@ -0,0 +1,333 @@
+# Org memory API payload examples
+
+## Purpose
+
+This document provides implementation-ready request and response examples for the org-scoped company brain memory vertical slice. The examples are intentionally explicit about org, namespace, commit, digest, redaction, and validation fields so API, UI, controller, and test work can share the same contract.
+
+## `GET /api/orgs/[org]/agents/summary`
+
+Response:
+
+```json
+{
+  "organization": "a5c",
+  "namespace": "krate-org-a5c",
+  "agents": {
+    "dispatchRuns": { "running": 2, "failed": 1, "succeeded24h": 12 },
+    "approvals": { "pending": 3 },
+    "blockedStacks": 1
+  },
+  "memory": {
+    "repository": "org-company-brain",
+    "phase": "Ready",
+    "currentCommit": "abcdef1234567890",
+    "ontologyDigest": "sha256:ontology",
+    "indexDigest": "sha256:index",
+    "importsAwaitingReview": 2,
+    "updatesAwaitingReview": 1,
+    "lastIndexedAt": "2026-05-11T08:00:00Z"
+  }
+}
+```
+
+## `POST /api/orgs/[org]/agents/memory/resolve-ref`
+
+Request for current memory:
+
+```json
+{
+  "memoryRepository": "org-company-brain",
+  "mode": "current",
+  "requested": "main"
+}
+```
+
+Request for memory at a timestamp:
+
+```json
+{
+  "memoryRepository": "org-company-brain",
+  "mode": "ref-at-time",
+  "requestedAt": "2026-05-09T08:00:00Z",
+  "resolutionPolicy": "latest-commit-before-or-at",
+  "requireApprovedCommit": true
+}
+```
+
+Response:
+
+```json
+{
+  "organization": "a5c",
+  "memoryRepository": "org-company-brain",
+  "mode": "ref-at-time",
+  "requestedAt": "2026-05-09T08:00:00Z",
+  "resolvedCommit": "13579bdf2468",
+  "resolvedRef": "refs/heads/main",
+  "currentCommit": "abcdef1234567890",
+  "staleBySeconds": 172800,
+  "ontologyDigest": "sha256:ontology-at-commit",
+  "indexDigest": "sha256:index-at-commit",
+  "conditions": [
+    { "type": "Resolved", "status": "True", "reason": "CommitFound" }
+  ]
+}
+```
+
+## `POST /api/orgs/[org]/agents/memory/query`
+
+Request:
+
+```json
+{
+  "memoryRepository": "org-company-brain",
+  "requestedRef": "main",
+  "resolvedCommit": "abcdef1234567890",
+  "query": {
+    "text": "playwright flaky checks in krate",
+    "modes": ["graph", "grep"],
+    "graph": {
+      "kinds": ["Runbook", "Decision", "Incident", "AgentPractice", "BabysitterRun"],
+      "edgeDepth": 2
+    },
+    "grep": {
+      "paths": ["runbooks/**", "babysitter/runs/**", "babysitter/retrospectives/**"],
+      "maxMatches": 25,
+      "includeLineContext": true
+    }
+  },
+  "limits": {
+    "maxBytes": 64000,
+    "maxRecords": 40
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "organization": "a5c",
+  "snapshotPreview": {
+    "memoryRepository": "org-company-brain",
+    "resolvedCommit": "abcdef1234567890",
+    "queryManifestDigest": "sha256:query",
+    "selectedRecordsDigest": "sha256:records",
+    "selectedExcerptsDigest": "sha256:excerpts"
+  },
+  "records": [
+    {
+      "kind": "Runbook",
+      "id": "runbook:ci-playwright-flake",
+      "path": "runbooks/ci/playwright-flake.md",
+      "title": "Playwright flake triage",
+      "owners": ["team:platform"],
+      "digest": "sha256:record"
+    }
+  ],
+  "excerpts": [
+    {
+      "path": "babysitter/retrospectives/01KR1Z.md",
+      "lineStart": 18,
+      "lineEnd": 24,
+      "text": "Redacted bounded excerpt suitable for prompt preview.",
+      "digest": "sha256:excerpt"
+    }
+  ],
+  "redaction": { "status": "redacted", "secretPatternCount": 0 },
+  "limits": { "truncated": false, "bytes": 18340 }
+}
+```
+
+## `POST /api/orgs/[org]/agents/dispatch`
+
+Request:
+
+```json
+{
+  "repository": "krate",
+  "ref": "refs/heads/main",
+  "source": {
+    "kind": "manual-code-dispatch",
+    "path": "docs/agents"
+  },
+  "agentStack": "claude-code-ci-repair",
+  "task": {
+    "kind": "docs-update",
+    "prompt": "Improve the agent memory docs."
+  },
+  "memory": {
+    "repositoryRef": "org-company-brain",
+    "requestedRef": "main",
+    "queryMode": "graph-and-grep",
+    "queryText": "krate agent memory docs"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "organization": "a5c",
+  "dispatchRun": "adr-01hx",
+  "attempt": "ada-01hx-1",
+  "contextBundle": "acb-01hx",
+  "memorySnapshot": "ams-01hx",
+  "phase": "Queued",
+  "links": {
+    "runDetail": "/orgs/a5c/agents/runs/adr-01hx",
+    "repositoryRuns": "/orgs/a5c/repositories/krate/runs"
+  }
+}
+```
+
+## `GET /api/orgs/[org]/agents/runs/[run]`
+
+Response excerpt:
+
+```json
+{
+  "organization": "a5c",
+  "run": {
+    "name": "adr-01hx",
+    "phase": "Running",
+    "repository": "krate",
+    "agentStack": "claude-code-ci-repair"
+  },
+  "attempts": [
+    { "name": "ada-01hx-1", "phase": "Running", "agentMuxSessionId": "mux-session-123" }
+  ],
+  "contextBundle": {
+    "name": "acb-01hx",
+    "digest": "sha256:context",
+    "memorySnapshot": "ams-01hx"
+  },
+  "memorySnapshot": {
+    "name": "ams-01hx",
+    "memoryRepository": "org-company-brain",
+    "requestedRef": "main",
+    "resolvedCommit": "abcdef1234567890",
+    "queryManifestDigest": "sha256:query",
+    "selectedRecordsDigest": "sha256:records",
+    "selectedExcerptsDigest": "sha256:excerpts"
+  },
+  "artifacts": []
+}
+```
+
+## `POST /api/orgs/[org]/agents/memory/import-babysitter-run`
+
+Request:
+
+```json
+{
+  "source": {
+    "kind": "babysitter-run",
+    "repository": "krate",
+    "runId": "01KR1ZCPQVVPJAJDNBQHGPWZZY",
+    "sessionId": "019e-example",
+    "a5cRunPath": ".a5c/runs/01KR1ZCPQVVPJAJDNBQHGPWZZY"
+  },
+  "memoryRepository": "org-company-brain",
+  "retentionTier": "summary-only",
+  "include": {
+    "memoryMd": true,
+    "sessionSummary": true,
+    "journal": "none",
+    "taskResults": "summarized",
+    "artifactManifests": "digest-only",
+    "retrospectives": true
+  },
+  "targetPath": "babysitter/runs/01KR1ZCPQVVPJAJDNBQHGPWZZY",
+  "validationPolicy": {
+    "redactSecrets": true,
+    "detectPromptInjection": true,
+    "requireReview": true
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "organization": "a5c",
+  "import": "import-01kr1z",
+  "phase": "Collecting",
+  "sourceDigest": "sha256:source",
+  "retentionTier": "summary-only",
+  "links": {
+    "detail": "/orgs/a5c/agents/memory/imports/import-01kr1z"
+  }
+}
+```
+
+## `GET /api/orgs/[org]/agents/memory/imports/[import]`
+
+Response excerpt:
+
+```json
+{
+  "organization": "a5c",
+  "import": {
+    "name": "import-01kr1z",
+    "phase": "AwaitingReview",
+    "retentionTier": "summary-only",
+    "sourceDigest": "sha256:source",
+    "redactionDigest": "sha256:redaction",
+    "validationReportDigest": "sha256:validation",
+    "targetBranch": "krate/memory-import/01kr1z",
+    "pullRequestRef": "a5c-ai/company-brain/124"
+  },
+  "generatedFiles": [
+    { "path": "babysitter/runs/01KR1Z/run.yaml", "digest": "sha256:run" },
+    { "path": "babysitter/sessions/2026/05/11/019e-example.md", "digest": "sha256:session" }
+  ],
+  "conditions": [
+    { "type": "SecretsRedacted", "status": "True", "reason": "NoSecretsDetected" },
+    { "type": "OntologyValid", "status": "True", "reason": "ValidationPassed" },
+    { "type": "ReviewReady", "status": "True", "reason": "PullRequestCreated" }
+  ]
+}
+```
+
+## Error examples
+
+Cross-org denial:
+
+```json
+{
+  "error": {
+    "code": "CROSS_ORG_REF_DENIED",
+    "message": "Referenced memory repository is not in the requested organization.",
+    "referenceKind": "AgentMemoryRepository",
+    "organization": "a5c"
+  }
+}
+```
+
+Missing organization route:
+
+```json
+{
+  "error": {
+    "code": "ORG_REQUIRED",
+    "message": "Choose an organization before opening repository memory.",
+    "path": "/api/orgs/{org}/memory"
+  }
+}
+```
+
+Redaction blocked import:
+
+```json
+{
+  "error": {
+    "code": "MEMORY_IMPORT_REDACTION_BLOCKED",
+    "message": "Import removed too much sensitive content to create a useful memory summary.",
+    "import": "import-01kr1z",
+    "condition": "RedactionTooBroad"
+  }
+}
+```

package/docs/agents/org-memory-controller-sequence-spec.md

@@ -0,0 +1,181 @@
+# Org memory controller sequence spec
+
+## Purpose
+
+This document defines the controller and API sequences for org-scoped company brain memory. It ties together `Organization`, namespace binding, memory repository bootstrap, memory context query, historical refs, Agent Mux dispatch, `.a5c` import, and memory update review.
+
+## Sequence principles
+
+- Resolve org before any resource lookup that can cross tenant boundaries.
+- Use the org namespace for all ServiceAccount, Secret, ConfigMap, runner, and workspace side effects.
+- Resolve Git refs to commits before context assembly or memory import review.
+- Store digests for every selected memory source, generated import file, validation report, and update patch.
+- Keep Agent Mux execution behind Krate admission; Agent Mux never decides org access.
+- Treat company brain memory as untrusted context until redacted and rendered with provenance.
+
+## Org bootstrap sequence
+
+```text
+admin creates Organization
+  -> org-controller validates slug and namespaceName
+  -> org-controller creates or verifies namespace
+  -> org-controller writes OrgNamespaceBinding
+  -> RBAC controller creates org admin RoleBindings
+  -> memory controller creates optional AgentMemoryRepository skeleton
+  -> UI shows org dashboard and empty repository/agents/memory states
+```
+
+Required status conditions:
+
+- `NamespaceReady`;
+- `OrgRbacReady`;
+- `DefaultPoliciesReady`;
+- `MemoryRepositoryReady` when memory bootstrap is enabled;
+- `Ready`.
+
+## Memory repository bootstrap sequence
+
+```text
+admin creates AgentMemoryRepository
+  -> memory controller verifies organizationRef and namespace
+  -> memory controller creates/adopts internal Git repo
+  -> memory controller commits default layout and ontology when empty
+  -> indexer builds graph/search/ontology reports
+  -> status records currentCommit, ontologyDigest, indexDigest
+  -> UI enables /orgs/[org]/agents/memory
+```
+
+Failure handling:
+
+- Git repo unavailable: `Ready=False`, `reason=MemoryRepositoryUnavailable`.
+- Layout invalid: `Ready=False`, `reason=MemoryLayoutInvalid`.
+- Ontology invalid: reads may be degraded, update merges blocked.
+
+## Dispatch with current memory sequence
+
+```text
+user opens /orgs/[org]/repositories/[repo]/code
+  -> UI requests dispatch preview
+  -> API resolves org, repo, stack, memory source policy
+  -> permission review checks repo, stack, runner, secrets, config, memory
+  -> memory controller resolves default branch to commit
+  -> context assembler queries graph/frontmatter/grep sources
+  -> redactor bounds and redacts results
+  -> AgentMemorySnapshot and AgentMemoryQuery are created
+  -> AgentContextBundle stores memory snapshot digests
+  -> AgentDispatchRun and AgentDispatchAttempt are created
+  -> Agent Mux launch receives admitted tool/session options
+  -> run detail streams events and shows memory provenance
+```
+
+Idempotency key:
+
+```text
+org + repository + source event + stack generation + memory resolved commit + context digest + attempt number
+```
+
+## Dispatch with historical memory sequence
+
+```text
+user selects memory from two days ago
+  -> UI converts relative input to absolute timestamp
+  -> API calls resolve-ref with mode ref-at-time
+  -> memory controller selects latest approved commit <= timestamp
+  -> UI shows resolved commit, age, and diff summary against current
+  -> context assembly uses historical commit for all memory queries
+  -> memory tools are scoped to historical AgentMemorySnapshot
+  -> run retry reuses same snapshot unless user refreshes memory
+```
+
+Blocking cases:
+
+- no commit exists before timestamp;
+- commit exists but failed ontology validation and policy requires valid ontology;
+- selected stack requires current-only memory;
+- actor lacks `memory.snapshots.diff` for preview diff.
+
+## Agent memory tool call sequence
+
+```text
+agent calls memory.docs.grep through Agent Mux
+  -> Agent Mux forwards tool request to Krate memory tool gateway
+  -> gateway resolves dispatch attempt and AgentMemorySnapshot
+  -> gateway checks tool grant and snapshot path/kind scope
+  -> memory query runs against pinned commit
+  -> result is redacted, bounded, digested, and audited
+  -> response returns excerpts with source paths and commit
+```
+
+The gateway must reject tool calls that ask for current branch state when the run is pinned to a historical snapshot unless the user explicitly refreshed context.
+
+## Babysitter run import sequence
+
+```text
+user chooses Import run memory from run detail
+  -> API creates AgentRunMemoryImport in org namespace
+  -> import controller verifies run/session/repo org ownership
+  -> import controller collects admitted MEMORY.md, session summary, journal, task, artifact metadata
+  -> source digests are computed
+  -> content is redacted and prompt-injection scanned
+  -> normalized Markdown/YAML files are generated
+  -> ontology/frontmatter/path/owner validation runs
+  -> memory update branch/PR is created
+  -> reviewer approves and merges
+  -> memory index rebuilds
+  -> source run links to merged memory commit
+```
+
+Idempotency key:
+
+```text
+organizationRef + source run ID + source digest + retention tier + targetPath
+```
+
+## Memory update review sequence
+
+```text
+agent proposes memory update artifact
+  -> artifact controller records digest and source run
+  -> memory controller creates AgentMemoryUpdate
+  -> validation checks ontology, frontmatter, owners, edges, paths, redaction
+  -> reviewer sees diff, source evidence, and validation report
+  -> approval controller records decision
+  -> memory controller merges or rejects update
+  -> memory repository currentCommit and indexes update
+  -> audit links update to source run/session/actor
+```
+
+Memory updates must not change the context snapshot of the run that proposed them. They only affect future dispatches or explicit refreshed retries.
+
+## Cross-org denial sequence
+
+```text
+request references org a5c and memory repo in org other
+  -> API resolves both refs
+  -> admission detects org mismatch
+  -> checks OrgSharingPolicy
+  -> no policy found
+  -> returns CROSS_ORG_REF_DENIED
+  -> audit records denied kind and actor without leaking private target details
+```
+
+## Watch and event sequence
+
+Org-scoped watch streams should publish:
+
+- `AgentMemoryRepository.status` changes;
+- `AgentMemorySnapshot` creation;
+- `AgentMemoryQuery` completion;
+- `AgentRunMemoryImport` phase/condition updates;
+- `AgentMemoryUpdate` review and merge events;
+- `AgentDispatchRun` memory provenance changes.
+
+Watch payloads must include org and namespace and must be filtered before streaming to the client.
+
+## Acceptance criteria
+
+- Each sequence has a clear org resolution step before side effects.
+- Every Git ref is resolved to a commit before context or import review.
+- Every memory or run import write path produces a reviewable update with validation status.
+- Cross-org references fail closed and produce non-leaky errors.
+- Watch streams can update UI without polling and without cross-org leakage.

package/docs/agents/org-memory-e2e-fixture-plan.md

@@ -0,0 +1,161 @@
+# Org memory E2E fixture plan
+
+## Purpose
+
+This document defines deterministic fixtures for testing the org-scoped memory vertical slice. The fixtures should let future implementation prove org isolation, memory snapshotting, run import, and UI visibility without requiring a live external GitHub organization.
+
+## Fixture topology
+
+```text
+Cluster
+  -> Organization a5c / namespace krate-org-a5c
+    -> Repository krate
+    -> AgentStack claude-code-ci-repair
+    -> AgentMemoryRepository org-company-brain
+    -> AgentMemorySource krate-ci-memory
+    -> RunnerPool trusted-linux
+  -> Organization other / namespace krate-org-other
+    -> Repository krate
+    -> AgentMemoryRepository other-company-brain
+```
+
+The duplicate repository slug is intentional. It tests org-aware routing and legacy ambiguity handling.
+
+## Memory repository fixture
+
+`org-company-brain` initial tree:
+
+```text
+.company-brain/
+  README.md
+  babysitter/MEMORY.md
+  ontology/node-kinds.yaml
+  ontology/edge-kinds.yaml
+  runbooks/ci/playwright-flake.md
+  repositories/krate.md
+  babysitter/retrospectives/seed.md
+  indexes/ontology-report.json
+```
+
+`runbooks/ci/playwright-flake.md` frontmatter:
+
+```yaml
+id: runbook:ci-playwright-flake
+kind: Runbook
+title: Playwright flake triage
+status: approved
+owners: [team:platform]
+repoRefs: [repository:krate]
+tags: [ci, playwright]
+updatedAt: 2026-05-11T08:00:00Z
+```
+
+## `.a5c` run fixture
+
+Fixture path:
+
+```text
+.a5c/runs/01KR-FIXTURE/
+  run.json
+  journal/000001.json
+  journal/000002.json
+  tasks/task-1/task.json
+  tasks/task-1/result.json
+```
+
+Minimum `run.json` fields:
+
+```json
+{
+  "id": "01KR-FIXTURE",
+  "organizationRef": "a5c",
+  "repository": "krate",
+  "process": "docs-memory-fixture",
+  "status": "completed",
+  "startedAt": "2026-05-11T08:00:00Z",
+  "completedAt": "2026-05-11T08:15:00Z"
+}
+```
+
+Journal fixture should include one harmless event and one secret-like value to prove redaction:
+
+```json
+{
+  "sequence": 2,
+  "eventType": "task.output",
+  "timestamp": "2026-05-11T08:05:00Z",
+  "message": "Token-like content sk-test-fixture-redact-me must be redacted."
+}
+```
+
+## Seed resources
+
+Required resources:
+
+- `Organization/a5c`;
+- `OrgNamespaceBinding/a5c`;
+- `Organization/other`;
+- `OrgNamespaceBinding/other`;
+- `Repository/krate` in both orgs;
+- `AgentStack/claude-code-ci-repair` in `a5c`;
+- `AgentMemoryRepository/org-company-brain` in `a5c`;
+- `AgentMemorySource/krate-ci-memory` in `a5c`;
+- `AgentServiceAccount/agent-claude-code-ci-repair` in `a5c`;
+- `RunnerPool/trusted-linux` in `a5c`.
+
+## Test cases
+
+### Org route ambiguity
+
+1. Request legacy `/repositories/krate/code`.
+2. Fixture has `krate` in `a5c` and `other`.
+3. Expect an explicit org picker or `ORG_REQUIRED`, not silent selection.
+
+### Memory query preview
+
+1. Request `/api/orgs/a5c/agents/memory/query` for `playwright flaky checks`.
+2. Expect `runbook:ci-playwright-flake` and no `other` org records.
+3. Expect resolved commit and digests.
+
+### Manual dispatch with memory
+
+1. Dispatch from `/orgs/a5c/repositories/krate/code`.
+2. Expect `AgentMemorySnapshot`, `AgentContextBundle`, and `AgentDispatchRun`.
+3. Expect run detail to show memory commit and selected records.
+
+### Summary-only run import
+
+1. Import `.a5c/runs/01KR-FIXTURE` with `summary-only` tier.
+2. Expect secret-like journal content not present in generated memory.
+3. Expect `SecretsRedacted=True`, `OntologyValid=True`, `ReviewReady=True`.
+4. Expect generated run/session summary files and artifact manifest digest only.
+
+### Cross-org memory denial
+
+1. Dispatch in `a5c` requests `other-company-brain`.
+2. Expect `CROSS_ORG_REF_DENIED`.
+3. Expect no content from `other` in preview, context, transcript, tool output, or audit details.
+
+### Historical memory pin
+
+1. Resolve `refAt` before a fixture update commit.
+2. Dispatch with resolved historical commit.
+3. Update current memory.
+4. Retry run.
+5. Expect retry to use original commit and show stale warning.
+
+## Assertions
+
+- Every created resource includes `organizationRef`.
+- Every UI route includes `/orgs/a5c` or `/orgs/other`.
+- Every memory source includes resolved commit and digest fields.
+- Every redacted import omits raw secret-like values.
+- Every cross-org denial emits an audit event with org and denied kind but no private target content.
+
+## Out of scope for fixture
+
+- External GitHub API calls.
+- Real Agent Mux runtime execution.
+- Raw artifact byte retention.
+- Cross-org sharing policy allow path.
+- Vector search.