[migmartri]

Adds docs/decisions/, the Current Decisions pages of this repository. Each page lists the design decisions of one functional area that hold today, with stable area-prefixed IDs, their deciders, the spec they come from, and what a check of the code found. The pages keep only choices that a reader of the code would likely get wrong. Smaller decisions, decisions whose reason the code already states, and decisions that a spec replaced while it was drafted stay in their specs and are counted on each page's "Not shown" line.

Areas

Each area has a three-letter prefix, and its decision IDs count from 001. Area owners, please check your prefix.

• Artifact CAS (CAS, owner @migmartri): CAS-001 to CAS-008. Existence cache store, location, and tenant key, credentials kept in process, and the browser download cache (Authorization header, existence check before 304).
• Attestation Process (ATT, owner @migmartri): ATT-001, ATT-003, ATT-004. Organization order with .chainloop.yml, one reader shared with Trace, and the API token check. Non-Confirmed: ATT-002, because attestation verify does not read the file yet (feat: allow to force project and organization in .chainloop.yaml #3063 is open).
• Authentication (AUT, owner @migmartri): AUT-001 to AUT-007. Handoff code exchange, S256 binding, code store with no token at rest, opt-in detection, legacy ?t= handling in the CLI, uniform exchange errors, and a gRPC-only exchange endpoint.
• Service Operations (OPS, owner @migmartri): OPS-002 to OPS-005. Separate metrics and profiler ports, TLS on the shared endpoint, the HTTP port as the shared endpoint, and multiplexing in the server process. Non-Confirmed: OPS-001.
• Chainloop Trace (TRC, owner @jiparis): TRC-001 to TRC-039. Spec capture, skills, transcript pointers, pasted images, local mode, the e2e matrix, line attribution, and the Pi and Codex providers. Non-Confirmed: TRC-019 and TRC-028.

Open conflicts

• Service Operations: issue-3628-controlplane-http-dispatch D-003 (OPS-001) and issue-3628-single-endpoint D-020 disagree about the CAS transport, and neither has a "replaces" note. The code follows D-020. Proposed: a spec change that records D-020 as the replacement.
• Chainloop Trace: issue-3515 D-009 (TRC-003) and issue-3569 D-004 (TRC-019) disagree about whether the agent captures pasted images. The instructions follow TRC-003. Proposed: a spec change that records the current rule.
• Chainloop Trace: issue-3635 D-011 (TRC-028) plans a nightly e2e run, but no workflow runs the suite. Proposed: a spec change that drops the nightly run.

No conflict was on a page before this change, because the pages are new.

One point for the Trace owner: TRC-029 says that the e2e suite pins the agent versions. The suite does not install the agents. It only warns when the installed version is different, so the pin is not enforced.

Each area owner approves the area map entry and prefix, the key decision cut, and the Language section of their area.

AI disclosure: Claude Code assisted with this change. It ran the eng-adr reconcile, checked each decision against the code, and drafted the pages. A person approved the area map, the cut, the Language sections, and the conflict proposals.

[chainloop-platform]

PR validation — ✅ 3 passing

Status	Policy	Material	Messages
✅ Passed	pr-min-approvals	pr-info	-
✅ Passed	pr-description-required	pr-info	-
✅ Passed	pr-user-story-linked	pr-info	-

_{View attestation ↗}

AI Session Checks — 🟢 89% · ⚠️ 1 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 89%	1	⚠️ 1	100% AI / 0% Human	6	+814 / -0	10h47m53s

🟢 89% — 100% AI — ⚠️ 1 policies failing

Oct 31, 2026 23:07 UTC · 10h47m53s · $44.61 · 958 in / 561.5k out · claude-code 2.1.316 (claude-opus-5-5)

_{View session details ↗}

Change Summary

• Adds docs/decisions/README.md with five functional areas and their relationships.
• Adds five area pages covering Current Decisions, Non-Confirmed items, and open conflicts.
• Uses area-prefixed decision IDs (CAS, ATT, AUT, OPS, TRC) across the new pages.

AI Session Overall Score

🟢 89% — Clean docs-only reconcile run; four substantive judges were green and two lanes were inapplicable.

AI Session Analysis Breakdown

🟢 94% · scope-discipline

🟢 All landed files stay under docs/decisions/, the area the user asked to create. · High Impact

🟢 90% · alignment

🟢 The AI corrected its initial cut and re-ran the rules before writing pages. · High Impact

🟢 88% · user-trust-signal

No notes.

🟢 84% · context-and-planning

🟢 The full eng-adr workflow and format guidance were loaded before substantive work. · High Impact

abstained · solution-quality

🟡 solution-quality not assessed — reviewer should confirm coverage · Low Severity

abstained · verification

🟡 verification not assessed — reviewer should confirm coverage · Low Severity

---

File Attribution

████████████████████ 100% AI / 0% Human

Status	Attribution	File	Lines
created	ai	docs/decisions/chainloop-trace.md	+353 / -0
created	ai	docs/decisions/artifact-cas.md	+109 / -0
created	ai	docs/decisions/authentication.md	+102 / -0
created	ai	docs/decisions/README.md	+94 / -0
created	ai	docs/decisions/service-operations.md	+82 / -0
created	ai	docs/decisions/attestation-process.md	+74 / -0

---

Policies (4, 1 failing)

Status	Policy	Material	Messages
✅ Passed	ai-config-ai-agents-allowed	ai-coding-session-e31005	-
✅ Passed	ai-config-no-dangerous-commands	ai-coding-session-e31005	-
⚠️ Failed	ai-config-no-secrets	ai-coding-session-e31005	Secret (jwt) detected in session content [turn=413, source=tool_result, line=21]: deel_pto: "https://api.deel.com/apps/webhooks/calendars/[CHAINLOOP_TRACE_REDACTED:jwt]" Secret (private-key) detected in session content [turn=103, source=tool_result, line=2]: [CHAINLOOP_TRACE_REDACTED:private-key]
✅ Passed	ai-config-mcp-servers-allowed	ai-coding-session-e31005	-

Security Checks — ✅ 5 passing

✅ secret-scan

Status	Policy	Messages
✅ Passed	secrets-detection	-

✅ sast-scan

Status	Policy	Messages
✅ Passed	owasp-top10-2025	-
✅ Passed	sast	-
✅ Passed	cwe-top25	-
✅ Passed	cwe-top26-40-cusp	-

Scans not applied (3)

Scan	Reason
vulnerability-scan	no manifest/lockfile changed
github-actions-scan	no workflow files changed
iac-scan	no IaC files changed

_{View attestation ↗}

Security context

✅ Nothing this change touches has a recorded security-fix history.

_{View in Chainloop ↗ · How this works ↗}

---

Powered by Chainloop and Chainloop Trace

[cubic-dev-ai]

11 issues found across 6 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/decisions/service-operations.md">

<violation number="1" location="docs/decisions/service-operations.md:58">
P2: ADR-048 incorrectly says the shared services use no proxy: the CAS shared endpoint uses an in-process `httputil.ReverseProxy` for native gRPC. Clarify that there is no external proxy or sidecar, while documenting the CAS in-process proxy.</violation>
</file>

<file name="docs/decisions/attestation-process.md">

<violation number="1" location="docs/decisions/attestation-process.md:29">
P2: This definition incorrectly says the repository config is always at the repository root, so readers may expect a subdirectory `.chainloop.yml` to be ignored. Describe it as the nearest `.chainloop.yml`/`.chainloop.yaml` found from the current directory up to the repository root, matching `LoadChainloopYML`.</violation>
</file>

<file name="docs/decisions/chainloop-trace.md">

<violation number="1" location="docs/decisions/chainloop-trace.md:31">
P3: The glossary excludes the CLI-generated pasted-image captures documented in ADR-030. Define `Capture` broadly enough to include push-time CLI captures, and distinguish agent-written captures from transcript-derived captures.</violation>

<violation number="2" location="docs/decisions/chainloop-trace.md:174">
P2: This describes one entry per paste, but repeated identical images are deduplicated and point to the same material. Say “each distinct pasted image content” so the ADR does not document a behavior the implementation must avoid.

(Based on your team's feedback about pasted image deduplication.)</violation>

<violation number="3" location="docs/decisions/chainloop-trace.md:244">
P2: This overstates the implemented matrix: OpenCode 1.x has its own README column but no pinned configuration entry, so the suite never tests it. State the missing-column exception here or add the OpenCode 1.x pin and harness run so this ADR matches the code.

(Based on your team's feedback about per-column harness version pins.)</violation>
</file>

<file name="docs/decisions/authentication.md">

<violation number="1" location="docs/decisions/authentication.md:75">
P3: This decision overstates the uniform-error guarantee: malformed exchange requests fail validation before `ExchangeHandoff` and expose a validation error to the client. Scope the statement to exchanges that pass request validation, or make the validation path return the same public error.</violation>

<violation number="2" location="docs/decisions/authentication.md:84">
P2: This rationale conflates the absence of a JSON/REST mapping with the absence of an HTTP transport. The shared server exposes registered RPCs, including `ExchangeHandoff`, through gRPC-Web, and cross-origin browser calls can still involve CORS preflight; describe the decision as omitting a JSON/REST mapping instead.</violation>
</file>

<file name="docs/decisions/artifact-cas.md">

<violation number="1" location="docs/decisions/artifact-cas.md:66">
P2: Scope this decision to the HTTP download endpoint: gRPC ByteStream downloads are unchanged and do not receive ETag or 304 behavior. Without that qualification, readers can incorrectly assume all CAS download paths use the browser cache.</violation>

<violation number="2" location="docs/decisions/artifact-cas.md:74">
P2: Do not present the header-token migration as a confirmed end-to-end current decision when this repository still emits query-token URLs and contains no client that moves the token into the header. Move the viewer migration to Non-Confirmed, or narrow this ADR to the confirmed CAS behavior: accepting a header while retaining the legacy query fallback.</violation>
</file>

<file name="docs/decisions/README.md">

<violation number="1" location="docs/decisions/README.md:72">
P2: This relationship is false for local mode: Trace stores evidence on disk without contacting a control plane or Artifact CAS. Qualify the upload statement for remote pushes and successfully stored materials.</violation>

<violation number="2" location="docs/decisions/README.md:87">
P2: The index hides unresolved decisions and conflicts by reporting empty sections, although the linked area pages list ADR-002, ADR-031, ADR-044, ADR-052 and three open conflicts. Populate these sections or link to the area-level lists instead of reporting `None`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: ADR-048 incorrectly says the shared services use no proxy: the CAS shared endpoint uses an in-process httputil.ReverseProxy for native gRPC. Clarify that there is no external proxy or sidecar, while documenting the CAS in-process proxy.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/service-operations.md, line 58:

<comment>ADR-048 incorrectly says the shared services use no proxy: the CAS shared endpoint uses an in-process `httputil.ReverseProxy` for native gRPC. Clarify that there is no external proxy or sidecar, while documenting the CAS in-process proxy.</comment>

<file context>
@@ -0,0 +1,82 @@
+- Code: verified: `app/artifact-cas/internal/server/http.go`, `app/artifact-cas/internal/server/grpc.go` (legacy listener on by default).
+
+### ADR-048: The server process does the multiplexing, with no proxy or sidecar
+Each service serves all protocols on its shared endpoint in its own process. It runs on a VM, in Docker Compose, and in Kubernetes with no proxy or sidecar.
+- Why: no extra process, configuration, or lifecycle in any deployment.
+- Rejected: a chart-level proxy or Gateway API routes (extra infrastructure, and two ports stay). A mandatory sidecar or embedded proxy (a process and its lifecycle in every deployment).
</file context>

Suggested change

	Each service serves all protocols on its shared endpoint in its own process. It runs on a VM, in Docker Compose, and in Kubernetes with no proxy or sidecar.
	Each service serves all protocols on its shared endpoint in its own process. It runs on a VM, in Docker Compose, and in Kubernetes with no external proxy or sidecar; the CAS native gRPC path uses an in-process reverse proxy.

[cubic-dev-ai]

P2: This definition incorrectly says the repository config is always at the repository root, so readers may expect a subdirectory .chainloop.yml to be ignored. Describe it as the nearest .chainloop.yml/.chainloop.yaml found from the current directory up to the repository root, matching LoadChainloopYML.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/attestation-process.md, line 29:

<comment>This definition incorrectly says the repository config is always at the repository root, so readers may expect a subdirectory `.chainloop.yml` to be ignored. Describe it as the nearest `.chainloop.yml`/`.chainloop.yaml` found from the current directory up to the repository root, matching `LoadChainloopYML`.</comment>

<file context>
@@ -0,0 +1,74 @@
+
+## Language
+
+- **Repository config**: the `.chainloop.yml` file at the repository root that pins `organization` and `projectName` for the repository. _Avoid_: "workflow file", because the file holds no workflow.
+- **Saved default**: the organization that the CLI keeps in its own configuration for the user. _Avoid_: "default org" without a qualifier, because the repository config can also give an organization.
+
</file context>

Suggested change

	- **Repository config**: the `.chainloop.yml` file at the repository root that pins `organization` and `projectName` for the repository. _Avoid_: "workflow file", because the file holds no workflow.
	- **Repository config**: the nearest `.chainloop.yml` or `.chainloop.yaml` found from the current directory up to the repository root, which pins `organization` and `projectName` for the repository. _Avoid_: "workflow file", because the file holds no workflow.

[cubic-dev-ai]

P2: This describes one entry per paste, but repeated identical images are deduplicated and point to the same material. Say “each distinct pasted image content” so the ADR does not document a behavior the implementation must avoid.

(Based on your team's feedback about pasted image deduplication.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/chainloop-trace.md, line 174:

<comment>This describes one entry per paste, but repeated identical images are deduplicated and point to the same material. Say “each distinct pasted image content” so the ADR does not document a behavior the implementation must avoid.

(Based on your team's feedback about pasted image deduplication.) </comment>

<file context>
@@ -0,0 +1,353 @@
+- Code: verified: `app/cli/internal/trace/claude/speccopies.go`, `app/cli/pkg/action/trace_spec_materials.go`.
+
+### ADR-030: The CLI captures pasted images at push time
+At push time, the CLI makes an image spec entry for each pasted image in the transcript, then replaces its inline copy with a pointer.
+- Why: the bytes are in the transcript, so the capture depends on neither the agent nor a file on disk.
+- Rejected: replace only the images that the agent captured. Images then stay inline when the agent does not copy them, and the agent can copy only from a file path.
</file context>

Suggested change

	At push time, the CLI makes an image spec entry for each pasted image in the transcript, then replaces its inline copy with a pointer.
	At push time, the CLI makes one image spec entry for each distinct pasted image content in the transcript, reusing an existing matching entry, then replaces each inline copy with a pointer.

[cubic-dev-ai]

P2: This overstates the implemented matrix: OpenCode 1.x has its own README column but no pinned configuration entry, so the suite never tests it. State the missing-column exception here or add the OpenCode 1.x pin and harness run so this ADR matches the code.

(Based on your team's feedback about per-column harness version pins.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/chainloop-trace.md, line 244:

<comment>This overstates the implemented matrix: OpenCode 1.x has its own README column but no pinned configuration entry, so the suite never tests it. State the missing-column exception here or add the OpenCode 1.x pin and harness run so this ADR matches the code.

(Based on your team's feedback about per-column harness version pins.) </comment>

<file context>
@@ -0,0 +1,353 @@
+- Code: verified: `app/cli/internal/trace/e2e/workspace.go`, `app/cli/internal/trace/e2e/runner.go`.
+
+### ADR-053: Agent versions are pinned and bumped by hand
+The suite configuration pins one version for each agent. A maintainer bumps a pin on purpose.
+- Why: the job has access to secrets and must not run an agent release that nobody selected.
+- Rejected: the latest release on each run (runs code that nobody selected in a job with secrets). Automated bump pull requests (more tooling for the first version).
</file context>

Suggested change

	The suite configuration pins one version for each agent. A maintainer bumps a pin on purpose.
	The suite configuration pins one version for each configured harness; OpenCode 1.x is not currently configured. A maintainer bumps each pin on purpose.

[cubic-dev-ai]

P2: This rationale conflates the absence of a JSON/REST mapping with the absence of an HTTP transport. The shared server exposes registered RPCs, including ExchangeHandoff, through gRPC-Web, and cross-origin browser calls can still involve CORS preflight; describe the decision as omitting a JSON/REST mapping instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/authentication.md, line 84:

<comment>This rationale conflates the absence of a JSON/REST mapping with the absence of an HTTP transport. The shared server exposes registered RPCs, including `ExchangeHandoff`, through gRPC-Web, and cross-origin browser calls can still involve CORS preflight; describe the decision as omitting a JSON/REST mapping instead.</comment>

<file context>
@@ -0,0 +1,102 @@
+
+### ADR-043: The exchange endpoint is gRPC only
+The exchange is an unauthenticated RPC on the auth service, with no HTTP mapping.
+- Why: the CLI uses gRPC and the web UI uses gRPC-Web, so no client needs a plain HTTP route. With no HTTP route, the public surface of the unauthenticated endpoint is smaller, and the web UI makes no cross-origin preflight.
+- Rejected: keep an HTTP mapping for a future non-gRPC client (no such client exists).
+- Deciders: migmartri, matiasinsaurralde
</file context>

Suggested change

	- Why: the CLI uses gRPC and the web UI uses gRPC-Web, so no client needs a plain HTTP route. With no HTTP route, the public surface of the unauthenticated endpoint is smaller, and the web UI makes no cross-origin preflight.
	- Why: the CLI and web UI use gRPC transports, so no client needs a JSON/REST mapping. Omitting that mapping keeps the unauthenticated surface smaller.

[cubic-dev-ai]

P2: Scope this decision to the HTTP download endpoint: gRPC ByteStream downloads are unchanged and do not receive ETag or 304 behavior. Without that qualification, readers can incorrectly assume all CAS download paths use the browser cache.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/artifact-cas.md, line 66:

<comment>Scope this decision to the HTTP download endpoint: gRPC ByteStream downloads are unchanged and do not receive ETag or 304 behavior. Without that qualification, readers can incorrectly assume all CAS download paths use the browser cache.</comment>

<file context>
@@ -0,0 +1,109 @@
+- Code: verified: `app/artifact-cas/internal/service/cache.go` (in-process expirable LRU).
+
+### ADR-020: Downloads use the browser HTTP cache
+The CAS sets cache headers on downloads and answers 304 when the browser has the content. The control plane keeps no copy of the bytes.
+- Why: the browser downloads straight from the CAS, so a cache there skips the backend copy and the transfer.
+- Rejected: a server cache in the control plane (the control plane never sees the bytes, and its message size limit is too small).
</file context>

Suggested change

	The CAS sets cache headers on downloads and answers 304 when the browser has the content. The control plane keeps no copy of the bytes.
	The HTTP download endpoint sets cache headers and answers 304 when the browser has the content; gRPC ByteStream downloads are unchanged. The control plane keeps no copy of the bytes.

[cubic-dev-ai]

P2: The index hides unresolved decisions and conflicts by reporting empty sections, although the linked area pages list ADR-002, ADR-031, ADR-044, ADR-052 and three open conflicts. Populate these sections or link to the area-level lists instead of reporting None.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/README.md, line 87:

<comment>The index hides unresolved decisions and conflicts by reporting empty sections, although the linked area pages list ADR-002, ADR-031, ADR-044, ADR-052 and three open conflicts. Populate these sections or link to the area-level lists instead of reporting `None`.</comment>

<file context>
@@ -0,0 +1,89 @@
+
+None.
+
+## Open conflicts
+
+None.
</file context>

[cubic-dev-ai]

P2: This relationship is false for local mode: Trace stores evidence on disk without contacting a control plane or Artifact CAS. Qualify the upload statement for remote pushes and successfully stored materials.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/README.md, line 72:

<comment>This relationship is false for local mode: Trace stores evidence on disk without contacting a control plane or Artifact CAS. Qualify the upload statement for remote pushes and successfully stored materials.</comment>

<file context>
@@ -0,0 +1,89 @@
+## Relationships
+
+- **Attestation Process → Chainloop Trace:** both read `.chainloop.yml` through one reader (ADR-003, attestation-process.md). A change to the file order or keys changes both areas.
+- **Chainloop Trace → Artifact CAS:** Trace uploads each spec source, skill package, and pasted image as its own material. A transcript pointer replaces a copy only when its material is stored (ADR-028, chainloop-trace.md).
+- **Service Operations → Artifact CAS, Authentication:** the shared endpoint carries the CAS ByteStream and download routes and the login endpoints. A change to the dispatch or TLS affects all of them.
+
</file context>

Suggested change

	- **Chainloop Trace → Artifact CAS:** Trace uploads each spec source, skill package, and pasted image as its own material. A transcript pointer replaces a copy only when its material is stored (ADR-028, chainloop-trace.md).
	- **Chainloop Trace → Artifact CAS:** For remote pushes, Trace uploads each stored spec source, skill package, and successfully stored pasted image as its own material. A transcript pointer replaces a copy only when its material is stored (ADR-028, chainloop-trace.md).

[cubic-dev-ai]

P3: This decision overstates the uniform-error guarantee: malformed exchange requests fail validation before ExchangeHandoff and expose a validation error to the client. Scope the statement to exchanges that pass request validation, or make the validation path return the same public error.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/authentication.md, line 75:

<comment>This decision overstates the uniform-error guarantee: malformed exchange requests fail validation before `ExchangeHandoff` and expose a validation error to the client. Scope the statement to exchanges that pass request validation, or make the validation path return the same public error.</comment>

<file context>
@@ -0,0 +1,102 @@
+- Code: verified: `app/cli/cmd/auth_login.go`.
+
+### ADR-042: One error to the client for each exchange failure
+Each exchange failure gives the client the same error. The specific reason goes to the server log only.
+- Why: a uniform client error gives no hint to a person who guesses codes. The server log reason helps operators debug failed logins.
+- Rejected: a uniform error with no server log reason (hard to debug).
</file context>

Suggested change

	Each exchange failure gives the client the same error. The specific reason goes to the server log only.
	+Each handoff exchange that passes request validation gives the client the same error. The specific reason goes to the server log only.

[cubic-dev-ai]

P3: The glossary excludes the CLI-generated pasted-image captures documented in ADR-030. Define Capture broadly enough to include push-time CLI captures, and distinguish agent-written captures from transcript-derived captures.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At docs/decisions/chainloop-trace.md, line 31:

<comment>The glossary excludes the CLI-generated pasted-image captures documented in ADR-030. Define `Capture` broadly enough to include push-time CLI captures, and distinguish agent-written captures from transcript-derived captures.</comment>

<file context>
@@ -0,0 +1,353 @@
+
+- **Provider**: the Trace integration for one AI coding agent (Claude Code, Cursor, OpenCode, Pi, Codex). _Avoid_: "harness" in code and evidence. The e2e suite uses "harness" for the agent CLI that it runs.
+- **Spec source**: an input that the session was built from (a ticket, a document, a plan, an image, a skill). It is recorded as a spec entry and its own material. _Avoid_: "attachment", because a source is evidence with a digest, not a file on a message.
+- **Capture**: a file that the agent writes into the spec folder for one source. _Avoid_: "export", because the agent writes the capture, not the CLI.
+- **Pointer**: the `chainloop.replaced` object that takes the place of a copy of a spec source in the transcript. _Avoid_: "placeholder", which is the fixed line in a local-file capture.
+- **Local mode**: the storage mode (`traceStorage: LOCAL`) that stores sessions on disk with no control plane. _Avoid_: "offline", because the agent and the model are still online. Also avoid "export mode".
</file context>