Skip to content

Commit 681e46a

Browse files
greenforestpathgreenforestpath
committed
Merge upstream 21 commits (resolve Cargo.lock conflict)
2 parents 7bf0993 + 8d5908d commit 681e46a

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+5871
-75
lines changed

‎.beads/issues.jsonl‎

Lines changed: 30 additions & 1 deletion
Large diffs are not rendered by default.

‎.github/workflows/notify-acfs.yml‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# ACFS Installer Change Notification Workflow
2+
# Generated by ACFS audit on 2026-01-26
3+
# Tool: br (beads_rust)
4+
name: Notify ACFS of Installer Changes
5+
6+
on:
7+
push:
8+
branches: [main, master]
9+
paths:
10+
- 'install.sh'
11+
workflow_dispatch:
12+
inputs:
13+
dry_run:
14+
description: 'Test without sending notification'
15+
required: false
16+
default: 'false'
17+
type: boolean
18+
force:
19+
description: 'Force notification even if checksum unchanged'
20+
required: false
21+
default: 'false'
22+
type: boolean
23+
24+
env:
25+
TOOL_NAME: 'br'
26+
INSTALLER_PATH: 'install.sh'
27+
ACFS_REPO: 'Dicklesworthstone/agentic_coding_flywheel_setup'
28+
29+
jobs:
30+
compute-and-notify:
31+
runs-on: ubuntu-latest
32+
permissions:
33+
contents: read
34+
35+
steps:
36+
- uses: actions/checkout@v4
37+
with:
38+
fetch-depth: 2
39+
40+
- name: Compute SHA256
41+
id: checksum
42+
run: |
43+
SHA256=$(sha256sum "${{ env.INSTALLER_PATH }}" | cut -d' ' -f1)
44+
echo "sha256=$SHA256" >> $GITHUB_OUTPUT
45+
echo "Computed SHA256: $SHA256"
46+
47+
- name: Get previous checksum
48+
id: previous
49+
run: |
50+
if git show HEAD~1:"${{ env.INSTALLER_PATH }}" > /tmp/prev 2>/dev/null; then
51+
PREV=$(sha256sum /tmp/prev | cut -d' ' -f1)
52+
echo "prev_sha256=$PREV" >> $GITHUB_OUTPUT
53+
echo "Previous SHA256: $PREV"
54+
else
55+
echo "prev_sha256=none" >> $GITHUB_OUTPUT
56+
echo "No previous version found"
57+
fi
58+
59+
- name: Compare checksums
60+
id: compare
61+
run: |
62+
if [[ "${{ steps.checksum.outputs.sha256 }}" != "${{ steps.previous.outputs.prev_sha256 }}" ]]; then
63+
echo "changed=true" >> $GITHUB_OUTPUT
64+
else
65+
echo "changed=false" >> $GITHUB_OUTPUT
66+
fi
67+
68+
- name: Notify ACFS (dry run)
69+
if: |
70+
(steps.compare.outputs.changed == 'true' || github.event.inputs.force == 'true') &&
71+
github.event.inputs.dry_run == 'true'
72+
run: |
73+
echo "::notice::DRY RUN - Would send notification to ACFS"
74+
echo "Tool: ${{ env.TOOL_NAME }}"
75+
echo "SHA256: ${{ steps.checksum.outputs.sha256 }}"
76+
77+
- name: Notify ACFS
78+
if: |
79+
(steps.compare.outputs.changed == 'true' || github.event.inputs.force == 'true') &&
80+
github.event.inputs.dry_run != 'true'
81+
uses: peter-evans/repository-dispatch@v3
82+
with:
83+
token: ${{ secrets.ACFS_NOTIFY_TOKEN }}
84+
repository: ${{ env.ACFS_REPO }}
85+
event-type: installer-updated
86+
client-payload: |
87+
{
88+
"tool": "${{ env.TOOL_NAME }}",
89+
"new_sha256": "${{ steps.checksum.outputs.sha256 }}",
90+
"old_sha256": "${{ steps.previous.outputs.prev_sha256 }}",
91+
"repo": "${{ github.repository }}",
92+
"commit": "${{ github.sha }}"
93+
}
94+
95+
- name: Summary
96+
if: always()
97+
run: |
98+
echo "## ACFS Notification Summary" >> $GITHUB_STEP_SUMMARY
99+
echo "| Field | Value |" >> $GITHUB_STEP_SUMMARY
100+
echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
101+
echo "| Tool | ${{ env.TOOL_NAME }} |" >> $GITHUB_STEP_SUMMARY
102+
echo "| SHA256 | \`${{ steps.checksum.outputs.sha256 }}\` |" >> $GITHUB_STEP_SUMMARY
103+
echo "| Changed | ${{ steps.compare.outputs.changed }} |" >> $GITHUB_STEP_SUMMARY

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,17 @@ claude-upgrade-progress.json
5151
# Local Cargo and Rustup caches (agent workspace artifacts)
5252
.cargo/
5353
.rustup/
54+
55+
# Ephemeral/temporary files (agent workflow artifacts)
56+
RESEARCH_FINDINGS.md
57+
TOON_INTEGRATION_BRIEF.md
58+
cov_*.out
59+
rustc-ice-*.txt
60+
*.snap.new
61+
sweep_*.png
62+
test_screenshot.png
63+
64+
# Nix build outputs (keep flake.lock - it should be committed)
65+
result
66+
result-*
67+
.direnv/

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,10 @@ JSON mode guarantees:
161161
- Clean stdout (diagnostics go to stderr)
162162
- Exit codes for success/failure
163163

164+
Schema discovery:
165+
- `br schema all --format json` emits JSON Schema documents for the main robot outputs
166+
- `br schema issue-details --format toon` for token-efficient schema viewing
167+
164168
### Rich Output Features
165169

166170
In Rich mode, br provides enhanced terminal output:

‎AGENT_FRIENDLINESS_REPORT.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Agent-Friendliness Report: br (beads_rust)
2+
3+
Bead: bd-3s2 (re-underwriting)
4+
Audit date: 2026-01-25
5+
Auditor: WildAnchor (Codex / GPT-5)
6+
7+
## Executive Summary
8+
9+
br is already strongly agent-friendly (non-invasive CLI + machine outputs), and now has a clear
10+
schema surface plus token-efficient TOON output for many read commands.
11+
12+
Recent work (this repo):
13+
14+
- Added agent-first doc entrypoints: `docs/agent/`
15+
- Captured a baseline snapshot pack: `agent_baseline/`
16+
- Added machine-readable artifacts: `ROBOT_MODE_EXAMPLES.jsonl`, `CLI_SCHEMA.json`
17+
- Added agent smoke tests: `scripts/agent_smoke_test.sh`
18+
- Removed `rm -rf` usage from local scripts/tests to comply with the no-deletion policy in `AGENTS.md`
19+
20+
## Current Agent Surfaces
21+
22+
### Machine output formats
23+
24+
- JSON: `--json` (global) or `--format json` (command-level when supported)
25+
- TOON: `--format toon` (decode via `tru --decode`)
26+
- Default format (if you omit `--format`/`--json`): `BR_OUTPUT_FORMAT` > `TOON_DEFAULT_FORMAT`
27+
28+
### Schema surface
29+
30+
br can emit JSON Schemas for primary machine outputs:
31+
32+
```bash
33+
br schema all --format json
34+
br schema issue-details --format json
35+
br schema error --format json
36+
```
37+
38+
TOON is also supported:
39+
40+
```bash
41+
br schema all --format toon
42+
```
43+
44+
### Error envelope
45+
46+
Many failures emit a structured JSON error object on stderr. A canonical example is captured in:
47+
48+
- `agent_baseline/errors/show_not_found.json`
49+
50+
And the machine schema is available via:
51+
52+
```bash
53+
br schema error --format json
54+
```
55+
56+
## Interface Modality Decision
57+
58+
Decision: CLI-only (no MCP surface in this repo).
59+
60+
Rationale:
61+
62+
- br is frequently used as a local, composable CLI primitive (shell pipes, git hooks, scripts).
63+
- MCP would add distribution + auth + permission surface area that is not required for the core value.
64+
- The existing CLI already covers the key agent needs: triage (`ready`), mutation (`update/close`), and sync (`sync --flush-only`).
65+
66+
## Gaps / Next Improvements
67+
68+
- No dynamic `--help-json` surface yet; `CLI_SCHEMA.json` is an interim static artifact.
69+
- Many commands return bare arrays/objects rather than a consistent `{data, metadata, errors}` envelope.
70+
- Schema outputs include `generated_at` (useful, but not deterministic byte-for-byte).
71+
72+
## Scorecard (1-5)
73+
74+
| Dimension | Score | Notes |
75+
|----------:|:-----:|-------|
76+
| Documentation | 5 | Root `AGENTS.md` + agent-first entrypoints under `docs/agent/` |
77+
| CLI ergonomics | 5 | Task-focused commands; consistent flags across major read flows |
78+
| Robot/machine mode | 5 | JSON everywhere; TOON for many read commands |
79+
| Schemas | 4 | `br schema` exists; TOON key folding is documented |
80+
| Errors | 4 | Structured envelope w/ hints; stderr routing needs care when piping |
81+
| Consistency | 4 | Some commands also have `--robot`; others rely on `--json`/`--format` |
82+
| Overall | 4.5 | High maturity; remaining work is mostly polish/consistency |

‎CHANGELOG_AGENT_FRIENDLY.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Agent-Friendly Changelog
2+
3+
This file tracks agent-facing changes (docs, robot output surfaces, schemas, safety behavior).
4+
5+
## 2026-01-25
6+
7+
- Added agent-first doc entrypoints under `docs/agent/`.
8+
- Added `agent_baseline/` snapshots (README/help/schema + small example outputs).
9+
- Added `ROBOT_MODE_EXAMPLES.jsonl` and `CLI_SCHEMA.json` as static, machine-readable artifacts.
10+
- Removed `rm -rf` usage from local scripts/tests to comply with the no-deletion policy in `AGENTS.md`.

‎CLI_SCHEMA.json‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
{
2+
"tool": "br",
3+
"repo": "beads_rust",
4+
"purpose": "Agent-first issue tracker (SQLite + JSONL).",
5+
"entrypoints": {
6+
"binary": "br",
7+
"agent_docs": [
8+
"AGENTS.md",
9+
"docs/agent/QUICKSTART.md",
10+
"docs/agent/ROBOT_MODE.md",
11+
"docs/agent/SCHEMA.md",
12+
"docs/agent/ERRORS.md",
13+
"docs/agent/EXAMPLES.md"
14+
],
15+
"deep_docs": [
16+
"docs/CLI_REFERENCE.md",
17+
"docs/AGENT_INTEGRATION.md"
18+
]
19+
},
20+
"global_flags": [
21+
{
22+
"flag": "--json",
23+
"type": "bool",
24+
"notes": "Force machine-readable JSON output (overrides --format)."
25+
},
26+
{
27+
"flag": "--no-color",
28+
"type": "bool",
29+
"notes": "Disable ANSI styling in text output."
30+
},
31+
{
32+
"flag": "--quiet",
33+
"type": "bool",
34+
"notes": "Minimize output (errors only)."
35+
}
36+
],
37+
"format_env": {
38+
"BR_OUTPUT_FORMAT": {
39+
"values": [
40+
"text",
41+
"json",
42+
"toon",
43+
"csv"
44+
],
45+
"notes": "Highest precedence default output format when --format/--json not provided."
46+
},
47+
"TOON_DEFAULT_FORMAT": {
48+
"values": [
49+
"text",
50+
"json",
51+
"toon",
52+
"csv"
53+
],
54+
"notes": "Fallback default output format when BR_OUTPUT_FORMAT is not set."
55+
}
56+
},
57+
"schema_surface": {
58+
"supported": true,
59+
"command": "br schema all --format json",
60+
"targets": [
61+
"all",
62+
"issue",
63+
"issue-with-counts",
64+
"issue-details",
65+
"ready-issue",
66+
"stale-issue",
67+
"blocked-issue",
68+
"tree-node",
69+
"statistics",
70+
"error"
71+
]
72+
},
73+
"output_notes": [
74+
"Prefer `--format json` (or `--json`) for parsing.",
75+
"Prefer `--format toon` for token-efficient outputs; decode with `tru --decode` when needed.",
76+
"Errors may be emitted as structured JSON on stderr."
77+
]
78+
}

0 commit comments

Comments
 (0)