auto-api-docs-writer: Opus 4.7 single-agent + branch-safety hardening, configurable base/dest#155
Conversation
Rewrite the daily writer to match the upgraded api-docs skill, which edits the mdoc XML directly instead of the extract→write→merge JSON round-trip. Host steps: - Drop the "Extract placeholders and manifest" and "Upload extracted JSON" steps from regenerate-stubs, the "Download pre-extracted JSON" / "Save original JSON" pre-agent steps, and the "Save final JSON" post-step. None are needed without the JSON layer. - Add a non-fatal "Bootstrap SkiaSharp binding for snippet checks" pre-agent step (externals-download + dotnet build binding/SkiaSharp) so the example reviewer can compile-check snippets against a real SkiaSharp.dll. - Keep the SkiaSharpAPI symlink (for the host docs-format-docs post-step) and the formatting post-step. Agent prompt (runtime-imported body): - Replace the JSON phases with the skill's direct-XML add pipeline: resolve-scope new -> writer edits XML -> lint + 3 reviewers + synthesizer -> fix CRITICAL -> structural validate -> commit + PR. - Route each sub-agent through the task tool's per-role model (writer/factual/ examples = opus, quality/synthesizer = sonnet), with an engine.model fallback if the sandbox does not honor per-sub-agent models. - Export DOCS_GIT_ROOT/DOCS_DIR on docs-tool.ps1 calls so scope/validate use the docs repo (primary checkout) for git baselines while source lookups still use the SkiaSharp clone. Recompiled the .lock.yml via `gh aw compile`. Note: depends on the matching api-docs skill update in mono/SkiaSharp (the cloned skiasharp_branch must carry the new skill + docs-tool.ps1 DOCS_GIT_ROOT support). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit b9ed9e6: ✅ Validation status: passed
For more details, please refer to the build report. |
The api-docs eval per-role bake-off picked gpt-5.5 for reviewer-factual (only candidate that caught the seeded byte-order contradiction; best mean recall + precision). Align the workflow's per-role routing note with the skill's updated review.md table and reviewer-factual Model: header. Body-only change (runtime-imported), so the compiled .lock.yml is unaffected. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 617b8a3: ✅ Validation status: passed
For more details, please refer to the build report. |
…put) Sibling of auto-api-docs-writer that runs the api-docs skill's REVIEW pipeline on a scope (default group:text) instead of filling placeholders. Doubles as the first CI exercise of per-sub-agent model routing: the orchestrator launches each reviewer/writer sub-agent via the task tool with an explicit model (factual -> gpt-5.5 per the eval bake-off) and prints a Routing report so the run is auditable. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit d28641a: ✅ Validation status: passed
For more details, please refer to the build report. |
…g report) Make the daily writer the common path: after the add pass (fill placeholders) it now also runs a REVIEW pass over a baked scope of existing docs (review-scope.txt, default group:text) — lint + 3 reviewers + synthesizer + fix CRITICAL/obsolete via per-role task models — then one validate + PR covers both passes. Because the writer is already registered on the docs default branch, this is dispatchable on a feature branch (skiasharp_branch input) WITHOUT landing a new workflow on main; the review scope is baked (not a dispatch input) so input validation against the default branch still passes. Adds a mandatory Routing report so the run doubles as the first CI exercise of per-sub-agent model routing. Removes the now-redundant standalone auto-api-docs-reviewer workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit e535c65: ✅ Validation status: passed
For more details, please refer to the build report. |
…tself The first CI pilot run completed green but produced NO PR. Root cause: the orchestrator delegated the terminal fix step to a background "fixer" sub-agent, then ended its turn before that agent (and the PR) completed -- exactly the session-killing pattern the older workflow had guardrails against. Separately, per-sub-agent model routing turned out to be cosmetic in the gh-aw sandbox: the api-proxy token-usage log showed every call was claude-sonnet-4.6 regardless of the requested per-role model. Fixes: - Pin the run model: explicit engine.model claude-sonnet-4.6 (drops the GH_AW_MODEL_AGENT_COPILOT override; orchestrator + every sub-agent run on it). - Drop cosmetic per-role routing and the routing-report requirement; document per-role routing as a local-only skill feature. - Terminal fixes are now the orchestrator's own FOREGROUND work (A4/R4); the only sub-agents launched are the pass-A writer and the reviewers. No terminal background agent. Synthesis is the orchestrator's job (no synthesizer agent). - Restore the tight escape hatch: once reviewers report, timebox fixing to ~10 min, then validate + open the PR. - Add an explicit "No terminal background agent" Critical rule and simplify the completion gate (create_pull_request/noop is the orchestrator's own job). Recompiled auto-api-docs-writer.lock.yml. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 3be9831: ✅ Validation status: passed
For more details, please refer to the build report. |
Validation run 28203165066 produced a real PR (the orchestration fix worked), but the agent rationalized out of step C: it saw it was already on the dispatch ref (a feature branch ahead of main), decided to "commit here and create the PR from this branch," and skipped `git checkout -b automation/write-api-docs`. Because safe-outputs preserves the committed branch and force-resets it (recreate_ref:true), this force-overwrote the workflow's own source branch. Fix: make step C unconditional — `git checkout -B automation/write-api-docs` before committing, even when already on a feature branch ahead of main, staging only SkiaSharpAPI/. Add a matching Critical rule explaining that committing on the dispatch ref destroys it under recreate_ref. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
… runs Root cause of the run-156 branch clobber: gh-aw's checkout step makes the DISPATCH REF the agent's working branch (git checkout -B <dispatch-ref>). When dispatched from a feature branch, the agent starts on that branch; it then committed its doc work there instead of switching to automation/write-api-docs, and safe-outputs (preserve_branch_name + recreate_ref) adopted that branch name as the PR head and force-recreated it — erasing the workflow source commits. Relying on the agent to switch branches is fragile (it rationalized staying put because the branch was "already ahead by 1 commit"). Add a host pre-agent step that renames the working branch to automation/write-api-docs before the agent starts, so every commit and the PR head land on a throwaway branch regardless of which ref triggered the run. The prompt rule remains as defense-in-depth. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Parameterize the docs PR base (docs_base_branch) and PR head (docs_head_branch)
as workflow_dispatch inputs so the writer can be tested against an older docs
state where many 'To be added.' placeholders still exist.
- base-branch -> ${{ inputs.docs_base_branch || 'main' }}; gh-aw propagates it
to the safeoutputs config.json, the safe_outputs checkout ref, and the handler
env (all interpolation-safe).
- regenerate-stubs aligns the docs submodule to docs_base_branch (was hardcoded main).
- host PR-branch step checks out docs_head_branch (was hardcoded automation/write-api-docs).
- prompt no longer hardcodes the PR branch name: commit on the host-prepared current
branch, never the dispatch ref.
Backward compatible: schedule/push runs default base=main, head=automation/write-api-docs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
mattleibow
changed the title
|
Learn Build status updates of commit 3be9831: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Learn Build status updates of commit e30f07b: ✅ Validation status: passed
For more details, please refer to the build report. |
A shallow submodule clone has no origin/<branch> remote-tracking ref for an arbitrary docs_base_branch, so 'git checkout -B stub-base origin/<branch>' fails (it only worked for main, which is tracked). Use FETCH_HEAD, set by the preceding fetch, which resolves for any branch. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit cdae111: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
- review_scope workflow_dispatch input (default group:text) drives the review pass scope, so other doc groups can be reviewed one at a time. - Commit step now unstages generated files (index.xml, ns-*.xml, _filter.xml, FrameworksIndex/) that stub regeneration rewrites, keeping them out of the PR. Exposed by the add-at-scale run against an old base where the regenerated generated files diverged from the base. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The skill dropped the selector grammar (type:/ns:/match:); docs-tool.ps1 now only lists all/new/changed/file:PATH and the model maps a plain-English theme to files itself. Update Pass R to branch on inventory-mode-vs-theme, drop the obsolete -Confirm:$false fuzzy flag, and refresh the input/comment wording. Recompiled the lock. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 5fe96e2: ✅ Validation status: passed
For more details, please refer to the build report. |
State the procedure positively: a plain-English theme is resolved by listing all and selecting the fitting files; edits touch only <Docs>. Recompiled lock. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
The skill deleted references/scope-resolution.md; remove the file-list bullet and the Pass R parenthetical that pointed at it, plus one more 'no JSON step' negative. Recompiled the lock. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit e164f7f: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 0ae2d3f: ✅ Validation status: passed
For more details, please refer to the build report. |
The deterministic docs gates (resolve-scope / lint / validate) moved out of the skill's PowerShell script (docs-tool.ps1) into Cake targets in the SkiaSharp clone: docs-resolve-scope, docs-lint, docs-validate. Update Pass A/R/V and the scope-environment note to invoke `dotnet cake --target=docs-* --scope=...`. The DOCS_GIT_ROOT/DOCS_DIR env overrides are unchanged — the Cake targets read the same vars, so the inverted-checkout sandbox keeps working (docs as primary checkout, SkiaSharp clone for binding/ source lookups). The compiled .lock.yml is unchanged: the body is imported at runtime and no frontmatter changed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit e10f6fa: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
The api-docs cake tooling folded its three QA tasks (docs-resolve-scope / docs-lint / docs-validate) into the existing docs-format-docs target, which now formats every doc and runs the deterministic checks in one pass (warnings for missing/quality issues, build-failing errors for broken XML/CDATA). The DOCS_GIT_ROOT/DOCS_DIR env overrides are gone too. Update the agent prompt to match: - Drop the "Scope environment" env-injection section; the docs are the primary checkout at the workspace root and skiasharp/docs/SkiaSharpAPI is symlinked to them, so the post-step docs-format-docs gate sees the edits with no override. - Discover files with plain git/find instead of docs-resolve-scope (placeholders via `git status` + `grep 'To be added.'`; review scope via `git status`/`find`/theme selection). - Replace the docs-lint step with an optional docs-format-docs run for the deterministic findings. - Replace the docs-validate step (V): the post-step docs-format-docs is now the gate and fails the run on malformed-xml/broken-cdata, so the agent no longer runs a validate target. - Refresh the Critical rules accordingly (post-step gate, no structural validator, signatures owned by mdoc). Body-only change; the compiled .lock.yml imports the prompt at runtime and its only cake call (the docs-format-docs post-step) is unchanged, so no recompile is needed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit 1c78080: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
docs-format-docs no longer emits a malformed-xml finding — a file that will not parse now throws from XDocument.Load, and broken-cdata remains the only build-failing lint class. Update the validation-gate prose to match. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 58511f5: ✅ Validation status: passed
For more details, please refer to the build report. |
…puts The workflow restated the skill's whole procedure, ran a broken/hidden SkiaSharp build that produced no DLL, and never self-gated. Make the skill the single source of truth and carry only gh-aw-specific wiring here: - Pin the agent-job checkout to docs_base_branch (was the dispatch ref) so the working tree, regenerated stubs, and PR base all agree; dispatching on a feature branch no longer reviews the wrong base. - Remove the review_scope input and Record review scope step: the work set is self-selecting (format findings + new placeholders + files changed vs base). - Remove the continue-on-error Bootstrap build (externals-download + dotnet build): docs are XML and need no build; it silently produced no DLL. - Rewrite the body as a thin trigger that defers to the api-docs skill and encodes the loop: run docs-format-docs to collect the to-do list, do the work (fill placeholders + the three reviewers from references/reviewing.md), then run docs-format-docs again to validate before the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 76b8543: ✅ Validation status: passed
For more details, please refer to the build report. |
Two model reviews (GPT-5.5, Opus 4.7) of run 28411250198 found the agent burned ~5-10 tool calls + 3 extra format passes diagnosing a duplicated docs tree, and hit a stray interactive git pager. Both pre-emptable in the host wiring: - Clone SkiaSharp with --no-recurse-submodules. The docs format/lint pass only reads in-tree files, so submodules are dead weight; worse, --recurse-submodules checked the docs submodule out as a real dir at skiasharp/docs/SkiaSharpAPI, which the ln -sfn could not replace, nesting a second copy. The format glob (skiasharp/docs/**/*.xml) then walked both and double-counted (~404 -> ~812). - rm -rf the docs dir before symlinking, and assert the linked view has exactly the same XML count as the workspace (fail fast on duplication). - Disable the git pager / detached-HEAD advice and echo the SkiaSharp HEAD SHA. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 2f8b342: ✅ Validation status: passed
For more details, please refer to the build report. |
The deterministic obsolete-in-example linter check was removed (obsolete usage is now a reviewer judgement guided by obsolete-api-map.md). Update the run procedure so it no longer lists obsolete-in-example as a collectable finding, and point the Fix step at reviewer B instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 13701a4: ✅ Validation status: passed
For more details, please refer to the build report. |
…ing (#4242) Rework the api-docs skill: router layout, direct-XML edits, Cake tooling (#4242) Context: companion CI workflow is mono/SkiaSharp-API-docs#155 Restructures the `api-docs` skill into a single dual-purpose tool that both adds docs for new APIs and reviews/corrects existing docs, and moves its tooling off a standalone PowerShell script onto a Cake target so the same checks run locally and in CI. ~~ Skill layout ~~ SKILL.md becomes a thin router (~410 lines removed) that points at focused references/ files (adding.md, reviewing.md, validation.md, patterns.md, skia-patterns.md, checklist.md, obsolete-api-map.md). The previous multi-agent orchestration (writer + three reviewers + synthesizer, each with its own Model: header) is folded into one single-pass procedure: the gh-aw CI sandbox does not honor per-sub-agent model routing, so the fan-out was dead weight. The prompt and methodology content is preserved, not dropped — it now lives in references/. ~~ Direct-XML editing ~~ Drops the old extract -> write -> merge JSON round-trip (scaffolding for a weaker model). A capable model edits the mdoc XML in place; safety comes from the post-edit formatter/validator rather than from regenerating files. ~~ One Cake pass instead of PowerShell ~~ Removes scripts/docs-tool.ps1 (-452 lines) and folds format + content checks into a single `docs-format-docs` target in scripts/infra/docs/docs.cake (+213). It loads each type XML once (XDocument), formats it, and runs deterministic checks in the same pass: warnings for missing/placeholder/quality issues, build-failing errors only for broken XML/CDATA. build.cake wires the target in. ~~ Obsolete handling ~~ Makes references/obsolete-api-map.md the unambiguous, overload-aware authority and removes the name-only obsolete-in-example linter. Name matching could not tell an obsolete overload from a modern one (DrawText/MeasureText exist on both the deprecated SKPaint forms and the modern SKFont/SKCanvas(..,SKFont,..) forms), so it produced false positives and a skill that contradicted its own reference. Obsolete judgement is now the reviewer's, guided by the map (the deprecated overload is the one without an SKFont parameter). Validated by two CI runs of the companion workflow (PRs #168 and #169): consistent across both — 8 placeholders filled source-first, 23 lint findings fixed, 0 final findings, no obsolete usage introduced, no valid modern SKFont/SKCanvas overloads deleted, and MS Learn OpenPublishing Errors:0. Co-authored-by: Matthew Leibowitz <mattleibow@live.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Go Live: publish latest API docs (#171) Publish the accumulated SkiaSharp / HarfBuzzSharp API documentation from main to the live (published) branch. This is the first Go Live since #66 and rolls up a large batch of docs automation, a full regeneration, and content/cross-reference cleanup. Highlights in this batch: - Docs automation: automated API docs writer (#92, hardened in #155), daily update workflow, go-live workflow (#65), and a Learn Build status-based auto-merge gate (#82, #83) backed by check-learn-build.py and a .github/known-warnings.csv baseline. - Regeneration: frameworks docs switched to latest-only monikers (#141), baseline reset to the Windows-generated output (#142), and stub regeneration moved to Linux via Mono (#147). This drops older, no-longer-shipping member/type pages (e.g. pre-v1.68 view APIs, the removed Android ISKRenderer interface, and the SKPaint text properties that moved to SKFont). - Content: filled API documentation placeholders (#150, #151, #172) and fixed broken cross-references (#152). - Cross-reference cleanup (#173): removed/repointed 36 obsolete xref-not-found references left behind by the latest-only-moniker regeneration — dangling links in 2019-era remarks to members that were since removed or relocated. Without this the Go Live build reported 160 warnings and the auto-merge gate (correctly) blocked the publish. Build health at publish: 0 errors, 124 warnings, 0 suggestions. All 124 remaining warnings are expected xref-not-found references to external framework types (OpenTK, Gdk/Cairo/Graphene, ElmSharp/Tizen.NUI, Windows.UI.Xaml, Microsoft.UI.Xaml, SharpVk, Vortice) that Learn cannot resolve and which are tracked in the known-warnings.csv baseline — 0 new warnings versus baseline, so the gate passes. Co-authored-by: Matthew Leibowitz <mattleibow@live.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 participant
Hardens and simplifies the
auto-api-docs-writeragentic (gh-aw) workflow. The workflow now carries only gh-aw wiring; how to write docs lives in theapi-docsskill (companion PR mono/SkiaSharp#4242).Single agent on Opus 4.7
The gh-aw sandbox does not honor per-sub-agent model routing (every call resolved to the run model regardless of the requested per-agent model, confirmed via the api-proxy
token-usage.jsonl). The multi-agent fan-out added complexity — and caused a no-PR failure when a terminal "fixer" sub-agent was backgrounded and the turn ended — without any benefit.engine.model→claude-opus-4.7(wasclaude-sonnet-4.6).tasksub-agents, no per-role models, no synthesizer.references/adding.md,references/reviewing.md).Branch safety + clone hygiene
recreate_refnever clobbers) the dispatch ref; the prompt commits on the host-prepared branch (no hardcoded head name).--no-recurse-submodules+rm -rf+ a file-count assertion and echoes the resolved HEAD; eliminates the docs-tree symlink duplication (workspace == linked) so the lint scans each file once; quiets git in the agent run.Configurable refs
skiasharp_branch(where the skill lives),docs_base_branch(defaultmain), anddocs_head_branch(defaultautomation/write-api-docs)workflow_dispatchinputs.docs_base_branch(viaFETCH_HEAD, so arbitrary/shallow branches work) and the PR targets it — keeping base, working tree, and stubs in agreement instead of reviewing the wrong base when dispatched on a feature branch.Generated-file hygiene
index.xml,ns-*.xml,_filter.xml,FrameworksIndex/) that stub regeneration rewrites, keeping them out of the PR.Validated on CI: two consecutive runs produced clean PRs (#168, #169) — dedup held, host gate 0 errors, the agent ran format-first / source-first / three reviewers / no build, and MS Learn OpenPublishing reported Errors:0.