Automattic / Automattic/docs-agent
Technical bootstrap makes no writes on an empty documentation surface
- Dominant language
- PHP
- Stars
- 1
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
The native technical bootstrap package completes its model turn without creating documentation when run against a genuinely empty `docs/**` surface. The deterministic completion validator correctly rejects the run because `docs/README.md` is absent.
## Hosted evidence
Initial bootstrap run:
- Run: https://github.com/Automattic/build-with-wordpress/actions/runs/29752036605
- Result artifact: https://github.com/Automattic/build-with-wordpress/actions/runs/29752036605/artifacts/8465035670
Controlled retry with an explicit bootstrap-only prompt requiring `docs/README.md`, `docs/architecture.md`, `docs/contributor-workflows.md`, a root README link, workspace writes, Git status, and Git diff:
- Run: https://github.com/Automattic/build-with-wordpress/actions/runs/29752395466
- Result artifact: https://github.com/Automattic/build-with-wordpress/actions/runs/29752395466/artifacts/8465203130
Both runs passed dependency installation, `pnpm install --frozen-lockfile`, `pnpm build`, `pnpm verify`, and generated-output drift isolation. Both then failed with:
```text
docs-agent.completion-contract.BOOTSTRAP_REQUIRED_PATH: Bootstrap required path is absent or insubstantial: docs/README.md
```
No publication branch or pull request was created. The temporary base/output branches were removed after evidence capture.
## Expected
On an intentionally empty documentation surface, the technical bootstrap package uses its enabled workspace write tools to create the caller-required navigable documentation before normal final prose.
## Acceptance criteria
1. A hosted technical bootstrap against an empty `docs/**` surface creates the caller-required paths.
2. The root entry point links to the documentation index and the configured glob minimum is satisfied.
3. The host-generated `DocsAgentCompletionReport` passes from the actual Git/filesystem evidence.
4. The runner publishes the required pull request against the declared temporary base.
5. Deterministic coverage proves the bootstrap package is instructed and able to perform required workspace writes without relying on final-response syntax.
## Compatibility
The deterministic completion and publication contracts should remain strict. This issue concerns bootstrap agent behavior on a fresh surface, not weakening validation.
Contributor guide
No contributing guide indexed for this repository
Research direction
Trace the native technical bootstrap package, deterministic completion contract, and publication runner implicated by the hosted runs. Use the two linked run artifacts and the BOOTSTRAP_REQUIRED_PATH failure as the starting evidence. Done means an empty docs/** surface receives the required paths and root link, the completion report passes from filesystem evidence, deterministic coverage passes, and a pull request is published.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github-actions, php
- Domain
- ci-cd, devtools, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100