A docs pipeline: prose and comments to a pull request, with no tests and no OpenSpec change #99
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Why
cmoriarty/soundcheck#29 ("Document the admin console") is docs only, and ran on
quick-fix(run_01M3JCM259FPD9PG96ZRYBN7HK). The docs themselves came out well — a README section, a 151-linedocs/admin-console.md, a cross-reference indocs/deploy.md— but the pipeline is built for code:fix.implementtook 23 min. Its prompt says "a test for it must fail without the fix", so it also wrotesrc/docs.test.ts: 9 assertions that the README contains certain strings. It also touchedpackage-lock.json.agent.test.unitthen ran for 9 min (and went wrong — see #98). On soundcheck the fullnpm testis ~6 min and ~8 GB.fix.summarize/git.commit.summaryare a second agent step to write what the first already knows.Proposal: a
docsbuilt-in9 nodes (quick-fix has 13), one agent step (quick-fix has up to four).
docs.write(agent, timeout 1800 s, not 5400)file:line) must be read from the source, not taken from the brief..osf/summary.mditself, in PR form: what changed, what to check, and that no code or spec changed. That dropsfix.summarizeandgit.commit.summary.paths-exist:.osf/summary.md,worktree-changed, and a newdocs-only.docs-onlypredicate — every changed path outside.osf/is either*.md,*.mdx,*.rst,*.txt,docs/**,LICENSE,CHANGELOG; or#,//,/* */,*,<!-- -->).Otherwise the step fails with "code changed — use quick-fix". This would have caught
src/docs.test.tsand the lockfile.docs.check(scripted, no model) — relative Markdown links resolve, and citedfile:linereferences point at files and lines that exist. No test suite: oncedocs-onlyholds, there is nothing for tests to exercise.Left out on purpose: no review agent (the merge gate is the review), no e2e or browser steps (
ui_changedis false by construction).Entry points: offered in the New Run picker, started by the
osf:docslabel, plusgit-flow-docs(the same shape on_FEATUREbranches) — as quick-fix does.Where it goes
src/osf/pipeline/nodes.py: a_DOCSselection,docs.writeanddocs.checkin_EXTRA_NODES,docsandgit-flow-docsin_BUILTIN_SHAPES.src/osf/engine/prompts.py:build_docs_write.src/osf/engine/predicates.py:docs-only.file:linechecker fordocs.check.Open question
Python docstrings are not comments by the line rule. Proposed: treat them as code, so docstring-only changes go to quick-fix. Covering them needs an AST comparison (the module's AST with docstrings stripped is unchanged).
Shipped in
2acc7ac(changedocs-pipeline, archived inc623806).docsandgit-flow-docs:git.clone → script.brief → script.agents-md → docs.write → docs.check → git.commit.feature → git.pr.open → human.merge-pr → git.pr.merge. One agent step; no test lanes, no browser check, no OpenSpec change, no archive.docs.writeforbids tests, requires every path/URL/env var/route/file:lineto be read from the repository, and writes.osf/summary.mdas the PR description itself (no summary step). Timeout 1800 s.docs-onlycompletion check: every changed path outside.osf/is prose (.md .mdx .rst .txt .adoc,docs/**, README/LICENSE/CHANGELOG/…) or a source file whose changed lines are all blank or whole-line comments. A test, lockfile, docstring, trailing comment or deleted source file fails it, naming the file and pointing at quick-fix.docs.check(scripted,python -m osf.pipeline.docs check): relative Markdown links and backtickedpath:N[-M]on lines the run added must resolve; old broken links are ignored, URLs aren't fetched. Report in.osf/docs-check.json.osf:docsstarts one. The label must be created by hand on each repository, likeosf:quick-fix.docs-pipeline;named-pipelinesandnew-runupdated. Guide updated. Full lane green (backend 1883, UI unit 445, browser 108).To retry cmoriarty/soundcheck#29 on it: redeploy osfd, create
osf:docson soundcheck, and label the issue. #98's fix ships in the same deploy, so the run won't inherit the old.osf/change.json.