Skip to content

feat(shared-docs): tiered surface safety and advisory proposals for the manual update lane - #1384

Merged
AnthonyTsu1984 merged 3 commits into
masterfrom
feat/shared-docs-manual-surface-lane
Nov 19, 2026
Merged

AnthonyTsu1984 merged 3 commits into
masterfrom
feat/shared-docs-manual-surface-lane

Conversation

@AnthonyTsu1984

Copy link
Copy Markdown
Collaborator

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-update lane, 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)

  • Blocked removals: a removed page still published at the current pin and not excluded fails the lane before anything is staged (exit 3; the run summary lists the files and the retire/keep/rename recipe). Retiring a live route needs a redirect decision that has no default.
  • Zero-auto-adoption pairing: every unadjudicated addition is paired with a textually appended exclude entry and a deferred entry in the new shared-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.
  • Atomicity: next-lock.yaml + paired manual.yaml + ledger.json land 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 as rest-upstream-refresh: AGENTIC_PROVIDER_API_KEY || DEEPSEEK_API_KEY, REST_UPSTREAM_AGENT_MODEL/REST_UPSTREAM_AGENT_BASE_URL fallbacks) drafts one proposal per pending addition (adopt/exclude/defer + metadata draft). Gates: invented files, unknown actions, undrafted adopts, and any metadata draft the real parseManualConfig refuses 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.js deterministically fills only the proposal field 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 in testing/manual/update.test.ts (blocked staging, pairing bytes + idempotency, candidate-build excludes paired pages, promotion carries paired excludes).
  • Decide/merge gates run offline: node --test scripts/docs-workflow/shared-docs-manual-decide.test.js (7 tests, stubbed gateway).
  • validate-workflow-policy.js pins the new steps (gateway-chain equality, wiring preflight, atomic staging, blocked reporting, PR-body notices) with 17 new mutation fixtures — pnpm test:workflow-policy 120/120.
  • Matrix, path-filters.json and the human-readable matrix spec updated in the same change.

Verification

  • pnpm test:shared-docs grouped 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 the update-prepare phase (explicit 15s/30s test timeouts punched through / 15-minute outer deadline) — CI is authoritative for that gate.
  • pnpm test:replay:all 16/16, pnpm test:workflow-matrix, deploy contract tests, pnpm vitest run .../workflows.test.ts 112/112, pnpm typecheck, git diff --check, scoped actionlint on the changed workflow: all green.

Follow-ups (not in this change)

  • First scheduled cron run after merge: confirm the zero-addition path stays byte-identical to today's lane output and observe the first real blocked/advisory PR.
  • Phase 2 (markers): the decide stage gains a marker-presence assertion at the candidate head once transforms reference upstream markers.

replay-seed 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.
…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.
@AnthonyTsu1984
AnthonyTsu1984 merged commit 230c19d into master Nov 19, 2026
21 checks passed
@AnthonyTsu1984
AnthonyTsu1984 deleted the feat/shared-docs-manual-surface-lane branch November 19, 2026 13:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant