Repository navigation
feat(shared-docs): tiered surface safety and advisory proposals for the manual update lane - #1384
Merged
Merged
Conversation
added 3 commits
November 19, 2026 20:41
…he manual update lane The scheduled update lane staged a bare lock bump: upstream additions silently entered the publish surface on the next channel, and upstream removals of live pages rode into the candidate unadjudicated. Both now fail the published-surface invariant that a human must author every change to it. - update-manual classifies the surface between the locked pins and the tracking head: a removed page still published at the current pin and not excluded blocks the run before anything is staged (exit 3, report-only, recipe in the summary), because retiring a live route needs a human redirect decision; each unadjudicated addition is paired with a textually appended exclude entry plus a deferred ledger entry, so the bump alone publishes nothing new and adoption is deleting one exclude line (optionally pasting the recorded metadata draft). - The new advisory decide stage (shared-docs-manual-decide.js, one gateway call on the REST refresh credential chain) drafts adopt/exclude/defer proposals with metadata drafts into proposals.jsonl; every line passes citation gates and the real manual-config validator, and a missing key or gateway failure degrades the run loudly instead of failing it. The deterministic merge step fills only the proposal field of deferred entries; classification is never inferred. - shared-docs/<group>/ledger.json (core/ledger.ts) is the append-only human decision surface: the lane stages deferred entries for first-seen additions and never rewrites an existing key. - The workflow classifies blocked/candidate/up-to-date, runs the advisory and merge steps only for candidates with pending additions, lands the lock plus the paired manual.yaml and ledger.json in one atomic commit, and surfaces the pairing and any advisory degradation in the PR body. Promote stays a human dispatch and is untouched. - Policy validator pins the new steps (gateway-chain equality, wiring preflight, atomic staging, blocked reporting) with 17 new mutation fixtures; vitest covers the ledger, pairing, blocking, candidate build and promotion carry; the decide/merge gates run offline in node --test. Matrix, path filters and the human-readable matrix spec are updated in the same change.
…e report has no surface counts
…ch decide report, landing gates Code-review follow-ups on the manual update lane: - The candidate step exited 3 before emitting candidate_out, so the classify step, the blocked-surface report and the report.json artifact retention were unreachable on the scheduled path: a blocked run died as a bare exit-3 with no file list. The step now always emits the output directory and passes the blocked exit code through; classify still sees report.json and the Report-the-blocked-surface step fails the run with the recipe. Pinned by a policy fragment and a mutation fixture. - The decide report shared one rejected array across batches, so with more pending pages than one gateway call each successful batch wiped the previous batches' recorded rejections; batches now carry their own arrays and the summary aggregates. lastError is batch-scoped so a degraded reason cannot cite a stale transient failure. - Pending pages with no readable upstream content head now degrade the decide stage up front (no gateway call on empty page blocks) and surface their count in the PR body instead of hiding behind a misleading degraded reason. - The merge step re-enforces adopt-proposals-must-carry-a-draft and counts skipped lines (with reasons) in its summary instead of dropping them. - An inline exclude value (exclude: [...]) now fails the pairing with an actionable message before the parse guard, and the committed ledger is read through repositoryRoot like every other group input.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Shared-docs manual update lane: tiered surface safety + advisory proposals
Closes the gap between the REST upstream refresh (diff → decisions → atomic adoption PR) and the manual-layout
shared-docs-manual-updatelane, which staged a bare lock bump: upstream additions silently entered the publish surface on the next channel, and upstream removals of live pages rode into the candidate unadjudicated (the getTelemetry deletion precedent).Design (approved): B + tiered blocking — the model stage has advisory authority only; every publish-surface change requires a human-authored edit, with human action compressed to "review the proposal, flip one field".
Surface safety in
update(promote untouched, still human-dispatched)excludeentry and a deferred entry in the newshared-docs/<group>/ledger.json, so the lock bump alone publishes nothing new. Adopting = deleting one exclude line (optionally pasting the metadata draft recorded in the ledger). Excluded removals degrade to annotations.next-lock.yaml+ pairedmanual.yaml+ledger.jsonland in the same commit or not at all.Advisory model stage
scripts/docs-workflow/shared-docs-manual-decide.js(one gateway call on the same credential chain asrest-upstream-refresh:AGENTIC_PROVIDER_API_KEY || DEEPSEEK_API_KEY,REST_UPSTREAM_AGENT_MODEL/REST_UPSTREAM_AGENT_BASE_URLfallbacks) drafts one proposal per pending addition (adopt/exclude/defer+ metadata draft). Gates: invented files, unknown actions, undrafted adopts, and any metadata draft the realparseManualConfigrefuses are rejected per line. Advisory by contract: a missing API key or gateway failure degrades the run loudly (PR body + run summary notice) instead of failing it; model/base-url vars are wiring and fail hard.shared-docs-manual-merge-proposals.jsdeterministically fills only theproposalfield of deferred entries — classification is never inferred, existing proposals are never overwritten.Tests and contracts
core/ledger.ts: parse/merge/attach-proposals with append-only semantics (9 unit tests); lane core covered intesting/manual/update.test.ts(blocked staging, pairing bytes + idempotency, candidate-build excludes paired pages, promotion carries paired excludes).node --test scripts/docs-workflow/shared-docs-manual-decide.test.js(7 tests, stubbed gateway).validate-workflow-policy.jspins the new steps (gateway-chain equality, wiring preflight, atomic staging, blocked reporting, PR-body notices) with 17 new mutation fixtures —pnpm test:workflow-policy120/120.path-filters.jsonand the human-readable matrix spec updated in the same change.Verification
pnpm test:shared-docsgrouped gate: all content green (run 1: 2129 passed / 0 failed / 8 skipped across light/transactions/local-runner/update-prepare); the local re-runs hit the documented load flake at theupdate-preparephase (explicit 15s/30s test timeouts punched through / 15-minute outer deadline) — CI is authoritative for that gate.pnpm test:replay:all16/16,pnpm test:workflow-matrix, deploy contract tests,pnpm vitest run .../workflows.test.ts112/112,pnpm typecheck,git diff --check, scopedactionlinton the changed workflow: all green.Follow-ups (not in this change)