Skip to content

Commit f8bd1b0

Browse files
author
chenbo
committed
Document generated file commit policy
1 parent 7cb89b2 commit f8bd1b0

5 files changed

Lines changed: 100 additions & 11 deletions

File tree

‎README.en.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,7 @@ See the [documentation home](docs/README.md) for full maturity notes.
133133
- [Agent-led vs Harness-led](docs/concepts/integration-modes.md)
134134
- [Loop Engineering Code Path](docs/concepts/loop-engineering.md)
135135
- [CLI Reference](docs/reference/cli-reference.md)
136+
- [Generated Files and Commit Policy](docs/reference/generated-files.md)
136137
- [Artifacts Reference](docs/reference/artifacts.md)
137138
- [Executor Adapters](docs/reference/executor-adapters.md)
138139
- [Benchmark Guide](docs/developer/benchmark-guide.md)

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ opencode-plusplus --pure # 纯 OpenCode，不启用 OpenCode++
132132
- [Agent-led vs Harness-led](docs/concepts/integration-modes.zh-CN.md)
133133
- [Loop Engineering 源码链路](docs/concepts/loop-engineering.zh-CN.md)
134134
- [CLI 命令参考](docs/reference/cli-reference.md)
135+
- [生成文件与提交策略](docs/reference/generated-files.md)
135136
- [输出结构说明](docs/reference/artifacts.md)
136137
- [Executor Adapter 状态](docs/reference/executor-adapters.md)
137138
- [Benchmark 指南](docs/developer/benchmark-guide.md)

‎docs/README.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,17 @@ This is the documentation map for OpenCode++. Start with the path that matches y
44

55
## Reader Paths
66

7-
| I want to... | Read |
8-
| ------------------------------------- | -------------------------------------------------------------------------------------------------- |
9-
| Try the tool in 5 minutes | [Getting Started](getting-started.md) |
10-
| Understand the product positioning | [Positioning](concepts/positioning.md) |
11-
| Understand the runtime architecture | [Architecture](concepts/architecture.md) |
12-
| Choose Agent-led or Harness-led usage | [Integration Modes](concepts/integration-modes.md) |
13-
| Use OpenCode chat with sidecar guards | [OpenCode Transparent Sidecar](integrations/opencode-sidecar.md) |
14-
| Integrate an executor CLI | [Executor CLI Integration](integrations/executor-cli.md) |
15-
| Use MCP tools | [MCP Tools](reference/mcp-tools.md) and [MCP Troubleshooting](integrations/mcp-troubleshooting.md) |
16-
| Understand generated files | [Artifacts Reference](reference/artifacts.md) |
17-
| Extend or debug the runtime | [Developer Docs](#developer-docs) |
7+
| I want to... | Read |
8+
| ------------------------------------- | -------------------------------------------------------------------------------------------------------- |
9+
| Try the tool in 5 minutes | [Getting Started](getting-started.md) |
10+
| Understand the product positioning | [Positioning](concepts/positioning.md) |
11+
| Understand the runtime architecture | [Architecture](concepts/architecture.md) |
12+
| Choose Agent-led or Harness-led usage | [Integration Modes](concepts/integration-modes.md) |
13+
| Use OpenCode chat with sidecar guards | [OpenCode Transparent Sidecar](integrations/opencode-sidecar.md) |
14+
| Integrate an executor CLI | [Executor CLI Integration](integrations/executor-cli.md) |
15+
| Use MCP tools | [MCP Tools](reference/mcp-tools.md) and [MCP Troubleshooting](integrations/mcp-troubleshooting.md) |
16+
| Understand generated files | [Generated Files Policy](reference/generated-files.md) and [Artifacts Reference](reference/artifacts.md) |
17+
| Extend or debug the runtime | [Developer Docs](#developer-docs) |
1818

1919
## Concepts
2020

@@ -34,6 +34,7 @@ Chinese concept pages:
3434

3535
- [CLI Reference](reference/cli-reference.md)
3636
- [MCP Tools](reference/mcp-tools.md)
37+
- [Generated Files and Commit Policy](reference/generated-files.md)
3738
- [Artifacts](reference/artifacts.md)
3839
- [Configuration](reference/config.md)
3940
- [Executor Adapters](reference/executor-adapters.md)

‎docs/reference/artifacts.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
OpenCode++ writes human-readable Markdown and machine-readable JSON.
44

5+
For whether each generated file should be committed, see [Generated Files and Commit Policy](generated-files.md).
6+
57
```txt
68
AGENTS.md
79
.agent-context/

‎docs/reference/generated-files.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Generated Files and Commit Policy
2+
3+
OpenCode++ writes both stable repository context and local runtime evidence. These files do not all belong in git.
4+
5+
Default rule:
6+
7+
- Commit stable guidance that helps every contributor or coding agent.
8+
- Do not commit local traces, sidecar reports, tool evidence, caches, or machine-specific config.
9+
- Treat execution evidence as potentially sensitive even when output previews are sanitized.
10+
11+
## Policy Table
12+
13+
| File or directory | Generated? | Commit? | May contain sensitive info? | Regenerate with |
14+
| -------------------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
15+
| `AGENTS.md` | Yes | Usually yes | Low, unless manual sources include secrets | `opencode-plusplus build .` |
16+
| `AGENTS.manual.md` | No, migration/helper only | Optional | Depends on what you write | Edit manually |
17+
| `.agent-context/AGENTS.generated.md` | Yes | Usually yes if your repo commits generated context | Low | `opencode-plusplus build .` |
18+
| `.agent-context/repo-summary.md`, `onboarding.md`, `context-layers.md` | Yes | Usually yes | Low | `opencode-plusplus build .` |
19+
| `.agent-context/key-files.md`, `module-map.md`, `architecture.md`, `dependency-graph.md`, `readiness.md` | Yes | Usually yes | Low to medium; includes repo structure | `opencode-plusplus build .` |
20+
| `.agent-context/contracts/*.json` | Yes | Usually yes | Low | `opencode-plusplus build .` |
21+
| `.agent-context/index/*.json`, `.agent-context/graphs/*`, `.agent-context/evidence/*` | Yes | Project choice | Medium; includes paths, symbols, summaries | `opencode-plusplus build .` |
22+
| `.agent-context/rag/*` | Yes | Project choice | Medium; optimized for retrieval and may include snippets | `opencode-plusplus build .` |
23+
| `.agent-context/tasks/*` | Yes | Optional | Medium; task text may reveal intent | `opencode-plusplus pack "<task>" .` |
24+
| `.agent-context/runs/<task-id>/*` | Yes | Usually no for local runs; optional for reviewed benchmark/demo artifacts | Medium; task prompts and boundaries may include repo details | `opencode-plusplus run "<task>" .` |
25+
| `.agent-context/runs/<task-id>/iterations/*` | Yes | Usually no | High; executor output, diffs, decisions, trace summaries | `opencode-plusplus orchestrate "<task>" . ...` |
26+
| `.agent-context/traces/*.json` | Yes | No by default | High; commands, files, hashes, sanitized output previews | `opencode-plusplus trace ...` or sidecar hooks |
27+
| `.agent-context/traces/opencode-sidecar-events.jsonl` | Yes | No | High; local sidecar events | Start OpenCode with `opencode-plusplus` |
28+
| `.agent-context/traces/tool-evidence/*.json` | Yes | No | High; command evidence payloads with sanitized previews and hashes | Sidecar `tool.execute.after` |
29+
| `.agent-context/sidecar/latest.json`, `latest.md` | Yes | No | Medium to high; local blocker/warning state | `opencode-plusplus sidecar verify .` |
30+
| `.agent-context/sidecar/policy.md`, `task-verify.md`, `hallucination.md`, `regression.md` | Yes | No by default | Medium to high; local verification reports | `opencode-plusplus sidecar verify .` |
31+
| `.agent-context/hallucination/*` | Yes | Usually no | Medium; transcript-derived claims | `opencode-plusplus hallucination . --trace <trace-id>` |
32+
| `.agent-context/regression/*.json` | Yes / curated | Commit curated memory, not transient reports | Medium; known issues and fragile modules | `opencode-plusplus build .`, `opencode-plusplus memory add-fix .` |
33+
| `.agent-context/memory/candidates/*.json` | Yes | No until reviewed | Medium | `opencode-plusplus memory learn-from-pr .` |
34+
| `.agent-context/cache/*` | Yes | No | Low to medium | `opencode-plusplus build .` |
35+
| `.agent-context/delta/*` | Yes | No by default | Medium; local change guidance | `opencode-plusplus delta .` or `opencode-plusplus evolve .` |
36+
| `.opencode/plugins/opencode-plusplus.ts` | Yes | Usually yes for OpenCode sidecar mode | Low; imports local OpenCode++ runtime | `opencode-plusplus` or `opencode-plusplus opencode init .` |
37+
| `.opencode/commands/opencode-plusplus.md`, `.opencode/commands/opencode-plusplus-verify.md` | Yes | Usually yes | Low | `opencode-plusplus opencode init .` |
38+
| `.opencode/agents/opencode-plusplus.md` | Yes | Usually yes | Low | `opencode-plusplus opencode init .` |
39+
| `opencode-plusplus.config.yml` | Starter generated, then user-owned | Yes | Low to medium | `opencode-plusplus init .` |
40+
| `opencode-plusplus.local.yml` | User-owned local config | No | High; can contain local paths or credentials | Copy from `opencode-plusplus.local.example.yml` |
41+
42+
## Recommended `.gitignore`
43+
44+
For most repositories, commit the stable context and OpenCode integration files, but ignore runtime evidence:
45+
46+
```gitignore
47+
.agent-context/cache/
48+
.agent-context/traces/
49+
.agent-context/sidecar/
50+
.agent-context/runs/*/iterations/
51+
.agent-context/delta/
52+
.agent-context/memory/candidates/
53+
opencode-plusplus.local.yml
54+
```
55+
56+
If your team does not want generated repository context in git, ignore all of `.agent-context/` and regenerate it locally:
57+
58+
```gitignore
59+
.agent-context/
60+
AGENTS.md
61+
```
62+
63+
In that mode, keep `AGENTS.manual.md` or another human-authored guide if you still want stable agent instructions in the repository.
64+
65+
## Why This Repository Commits `.agent-context`
66+
67+
This project intentionally keeps a generated `.agent-context/` in the repository because it is both the product output and a test fixture for dogfooding. That does not mean every downstream project should commit every `.agent-context` file.
68+
69+
Use this split:
70+
71+
- **Commit:** stable guidance, contracts, generated summaries, OpenCode plugin/commands when shared with the team.
72+
- **Do not commit:** traces, sidecar latest reports, tool evidence, caches, local config, and transient task iterations.
73+
74+
## Sensitive Evidence Notes
75+
76+
OpenCode++ sidecar evidence is safer than raw logs, but it is still local runtime evidence:
77+
78+
- long stdout/stderr is passed to `record-tool` through a JSON evidence file, not command-line arguments;
79+
- raw output is hashed;
80+
- stored previews are redacted and truncated;
81+
- missing exit code is recorded as `unknown`, not `passed`;
82+
- working-tree hashes and touched file lists can still reveal local activity.
83+
84+
Keep `.agent-context/traces/` and `.agent-context/sidecar/` out of git unless you have a deliberate audit workflow.

0 commit comments

Comments
 (0)