docs: close top-4 documentation gaps across AGENTS, ARCHITECTURE, PRD, tooling #4

Merged

ses merged 4 commits from feat/docs-gaps-top4 into main

2026-08-25 16:28:10 +00:00

ses commented

2026-08-25 16:14:58 +00:00

Owner

Summary

Four small, atomic commits that close the four highest-priority documentation
gaps identified after the feat/pr-get-and-create PR landed.

chore(tooling): make bun test robust under sandbox limits —
package.json test script now sets BUN_MAX_WORKERS=1, dodging Bun's
Failed to start HTTP Client thread: Resource temporarily unavailable
panic on CPU/thread-constrained sandboxes. AGENTS.md Gotchas records the
rationale and points CI-locals at bun test direct for permissive
environments.
docs(architecture): document real cwd inference with worktree support —
Replaces the stale "this module is a stub" paragraph in
docs/ARCHITECTURE.md with an accurate description of the
git -C <cwd> remote get-url origin implementation, worktree handling
(.git as a file with gitdir: vs. as a directory), SSH→https://<host>
URL normalization, and the three-layer test strategy (pure URL parser,
mocked detection, end-to-end real-git fixture).
docs(agents): add branch naming convention — Branches follow
feat/<scope>, matching Conventional Commits scope. Same convention for
branches and commits reduces cognitive load.
docs(prd): record resolved write-guard decision — Adds a "Resolved
decisions" section to docs/PRD.md capturing why the confirm: true / confirm_title per-call guard and the process-level write flag
were removed in the previous PR.

Scope

Doku-only. No code or interface changes. CLI / MCP / OpenCode behavior is
identical to main.

Verify

bun run lint — green
bun run typecheck — green
bun run test — 122/122 green (now without manual BUN_MAX_WORKERS)
bun run build — green (untouched by this PR)

Out of scope

Lower-priority doc gaps noted in the inventory but not addressed here:
docs/GLOSSARY.md staleness check, ADR for the cwd-inference normalization,
comment in src/shared/cwd.ts explaining the worktree mechanism. These remain
candidates for a future feat/docs-gaps-rest PR.

## Summary Four small, atomic commits that close the four highest-priority documentation gaps identified after the `feat/pr-get-and-create` PR landed. - **`chore(tooling): make bun test robust under sandbox limits`** — `package.json` test script now sets `BUN_MAX_WORKERS=1`, dodging Bun's `Failed to start HTTP Client thread: Resource temporarily unavailable` panic on CPU/thread-constrained sandboxes. AGENTS.md Gotchas records the rationale and points CI-locals at `bun test` direct for permissive environments. - **`docs(architecture): document real cwd inference with worktree support`** — Replaces the stale "this module is a stub" paragraph in `docs/ARCHITECTURE.md` with an accurate description of the `git -C <cwd> remote get-url origin` implementation, worktree handling (`.git` as a file with `gitdir:` vs. as a directory), SSH→`https://<host>` URL normalization, and the three-layer test strategy (pure URL parser, mocked detection, end-to-end real-git fixture). - **`docs(agents): add branch naming convention`** — Branches follow `feat/<scope>`, matching Conventional Commits scope. Same convention for branches and commits reduces cognitive load. - **`docs(prd): record resolved write-guard decision`** — Adds a "Resolved decisions" section to `docs/PRD.md` capturing why the `confirm: true` / `confirm_title` per-call guard and the process-level write flag were removed in the previous PR. ## Scope Doku-only. No code or interface changes. CLI / MCP / OpenCode behavior is identical to `main`. ## Verify - `bun run lint` — green - `bun run typecheck` — green - `bun run test` — 122/122 green (now without manual `BUN_MAX_WORKERS`) - `bun run build` — green (untouched by this PR) ## Out of scope Lower-priority doc gaps noted in the inventory but not addressed here: `docs/GLOSSARY.md` staleness check, ADR for the cwd-inference normalization, comment in `src/shared/cwd.ts` explaining the worktree mechanism. These remain candidates for a future `feat/docs-gaps-rest` PR.

ses added 4 commits

2026-08-25 16:14:58 +00:00

chore(tooling): make bun test robust under sandbox limits 620b5ad29a

docs(architecture): document real cwd inference with worktree support a384bcb1dd

docs(agents): add branch naming convention af1aa30af8

docs(prd): record resolved write-guard decision

ci / test (pull_request) Successful in 52s

Details

5424826df6

ses merged commit 5424826df6 into main

2026-08-25 16:28:10 +00:00

ses deleted branch feat/docs-gaps-top4