Automattic / Automattic/docs-agent

Technical bootstrap makes no writes on an empty documentation surface

Open
#177 0 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.