Files
pipelines/examples/docs-fold.md
T
alan a3f571d672 docs: make docs-fold the single writer of shared documentation
Every item wrote the shared, append-only docs (android/README.md, docs/cli.md and
the packaged skill references), so every merge conflicted on prose. Keep the duty
to notice stale docs; move the writing to one deliberate place.

- Per-item note, not a shared edit. An item that makes a shared document stale
  writes docs/notes/<slug>.md - unique per item, so two items never touch the same
  file - and commits that note with its change. It never edits a README, topic doc
  or packaged skill reference itself.
- One writer. The manual-only docs-fold pipeline, bundled as the fifth starter
  examples/docs-fold.md, folds every note under docs/notes/ into the shared
  document it names and deletes the consumed notes in its own commit; an empty
  notes directory is a success no-op. Operator trigger:
  pipelines new "Docs fold" --template docs-fold --no-open; pipelines submit
  <draft.md>; pipelines run "Docs fold".
- Implemented where the convention lives: orchestration.md (brief item 5, the
  hard-constraint bullet, a "Single documentation writer" section and the
  "Pipeline choice" committer bullet), the canonical committer checklist in
  format.md (new step 6), the committer prompts in examples/task.md and
  examples/three-stage.md, the new examples/docs-fold.md with its catalog and
  README entries, and the repository guideline AGENTS.md. Test-expectation counts
  (examples/catalog_test.go, internal/server/templates_test.go,
  scripts/smoke-first-install.py) follow the fifth starter.

Reflected where it belongs: the packaged templates (examples/task.md,
examples/three-stage.md, the new examples/docs-fold.md), the packaged skill
references (orchestration.md, format.md) and the repo guideline AGENTS.md all carry
the new convention. No new reference file was added, so install.go's managed
inventory is unchanged. The shared descriptive docs were deliberately not
rewritten: this change makes README.md:191, docs/cli.md:170 and
internal/author/skill/references/operations.md:13 name four starters where there are
now five. Those stay as they are - correcting them now is exactly the per-item
shared edit this change removes - and the stale-doc note
docs/notes/docs-fold-single-writer.md records each one for the docs-fold writer to
fold. Nothing else needed updating. No new dependency; no Android, Gradle, server,
installer, Docker or published-definition change; no definition published over the
running pipelines.

Evidence: go test -count=1 ./... passed; go build ./... and go vet on the touched
packages clean; ./internal/author/... covers embedding, reference links, the managed
inventory and install/upgrade/protection; ./examples/... validates the fifth starter
and its manual-only, committer-terminated graph; ./internal/server/... covers the
served catalog. Not run: the docs-fold writer against the shared docs (nothing to
fold yet); no install or deploy.

(cherry picked from commit f29656cf084d7eee2e033f2a37a9d231d7acaaf0)
2026-10-17 23:59:59 +01:00

91 lines
2.9 KiB
Markdown

# stage fold
```output
{ summary, changed_files, folded_notes }
```
```prompt
Fold the accumulated per-item documentation notes into the repository's shared
documentation. Read every file under `docs/notes/`; for each note, apply the change it
records to the shared document the note names - the repository's READMEs and topic docs
and the packaged skill references - then delete the consumed note. Do not edit any other
file, change behaviour, or rewrite documentation that is still true. Keep values from
their single existing sources. An empty or missing `docs/notes/` directory is a success
no-op: make no change, commit nothing, and say so. Limit inspection to the notes
directory and the documents they name; never scan filesystem or mount roots, and use
commands supported by the actual execution environment. Save any artifacts you produce
into the artifacts directory named in the runtime context. Report the notes read, the
documents changed and the notes deleted in an `# evidence` section, with the exact
commands and observed results. Return the line-oriented result: the first non-empty line
is the declared outcome, a `# output` section holds one JSON object with the output
fields named above, and any further `# <heading>` section is retained verbatim as
evidence. Return blocked if the notes directory cannot be read.
```
```tools
read
glob
grep
edit
shell
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> committer
blocked -> #failure
error -> #failure
```
# stage committer
```output
{ committed, commit, changed_files, pre_commit_checks }
```
```prompt
Commit this run's change locally. Never push, tag, deploy or rewrite history. Select
the run's changed paths from input.server_changed_files (the runner's captured
evidence) and the fold stage's declared changed_files, and stage their union, including
the notes the fold stage deleted (stage the removal, not only surviving paths). Inspect
the staged diff before committing; never commit unrelated work, secrets or generated
artifacts. When nothing is staged - for example an empty notes directory - do not create
an empty commit; return success with a clear note. Otherwise commit with a concise
message naming this run's change and report the commit hash. If a required check fails,
do not commit; return blocked with the failing output. Return the line-oriented result:
the first non-empty line is the declared outcome, a `# output` section holds one JSON
object with the output fields named above, and any further `# <heading>` section is
retained verbatim as evidence. Never claim an unexecuted check passed or fabricate a
commit.
```
```memory
{"changed_files":"fold.changed_files","server_changed_files":"input.server_changed_files"}
```
```tools
read
glob
grep
shell
```
```configs
provider=opencode-go
model=deepseek-v4.1-flash
retries=2
timeout=1h
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```