Skip to content

deploygov: linked-changes documentation sweep #1036

Description

@babltiga

Part of #1029 (linked deployment changes epic — read it first for the big picture). Needs #1034 and #1035.

Goal

Make the feature findable and correctly described everywhere prose about deployment governance
lives, and close the epic. Every earlier part documented its own contract next to its code; this
part adds the narrative chapter section, reconciles the cross-references, refreshes the public
site, and regenerates the help corpus. No code.

Design constraints agreed on the epic (restated so the docs cannot drift from them):

Steps

  1. docs/18-deployment-governance.md — a new numbered section after §7 (:331), before
    §8 "CI wrappers" (:362): "Linked database changes" — the trigger field and its validation
    table, the replay 409, the gate rule, execute_linked_queries and its failure semantics with
    the audit rows (DEPLOYMENT_SUBMITTED metadata, DEPLOYMENT_EXECUTED.linked_queries_executed,
    DEPLOYMENT_LINKED_QUERY_FAILED with trigger=linked_query), the core.api
    LinkedQueryExecutionService inversion and why (workflow → deploygov already exists), and
    the two UI surfaces. Renumber the later sections and fix every intra-document anchor. Update
    §2 (:118), §3 (:153), §5 (:246), §8 (:362), the "Audit & notifications" list (:522)
    and the module layout tree (:31) for the new files.
  2. docs/04-api-spec.md — reconcile the rows the earlier parts added (:7701, :7775): the
    trigger field, the query_request_id list filter, linked_queries on request responses,
    linked_queries_ready / linked_queries on the gate, the confirm body, and the five problem
    codes (DEPLOYMENT_LINKED_QUERY_NOT_FOUND, _INVALID, _FAILED,
    DEPLOYMENT_LINKED_QUERIES_REPLAY_MISMATCH) in the error table.
  3. docs/03-data-model.md — verify the deployment_request_queries section deploygov: persistence — deployment_request_queries link table #1030 wrote
    sits under ## Deployment governance (:2583) and cross-links query_requests.
  4. docs/05-backend.md — the analyzer input paragraph (:4326-4334) already describes the
    new field from ai: linked SQL and verdicts in the DeploymentAnalyzer input #1033; add the DEPLOYMENT_LINKED_QUERY_FAILED action and
    trigger=linked_query to the deploygov audit list under "State machine (deploygov: deployment governance — trigger API, AI analysis, state machine & routing #691)", and note the
    new core.api interface in the module-boundary discussion of the workflow module.
  5. docs/16-iac.md — under "CI Actions & pipeline templates" (:191): the new
    deployment-gate inputs, run-query's execute: "false", and a link to
    ci-templates/examples/github-migrations-workflow.yml.
  6. docs/12-roadmap.md — add the item under the milestone the epic is scheduled in (or
    "Backlog / Unscheduled", :247, if none), as the D1/D3/D5 deploygov epics are listed.
  7. README.md — one sentence in the deployment-governance feature paragraph (:131) and the
    IaC table row (:173) mentioning linked database changes.
  8. website/ — features/deployment-governance/index.html (a feature block with the panel
    screenshot, captured per e2e/screenshots/capture.ts), docs/guides/deployment-approval/index.html
    (the migrations recipe, mirroring the example workflow), docs/iac/index.html (the new
    inputs), docs/integrations/index.html if it lists gate inputs. Bump the JSON-LD
    dateModified on each edited page (features/deployment-governance/index.html:64,
    docs/guides/deployment-approval/index.html:67) and the matching sitemap.xml <lastmod>
    entries (:28, :238); keep the frontend/src/config/docs.ts ↔ website/app.js anchor
    contract intact (.claude/patterns/website-drift.md). Plain language on the marketing page —
    "the deployment waits until the migration is approved", not "the releasable function".
  9. help-corpus/ — regenerate with node .github/scripts/build-help-corpus.mjs and commit;
    the help-corpus CI job fails on drift. No new route, so no ROUTES entry; no new website
    area, so no SECTION_RULES entry.
  10. CLAUDE.md — extend the deploygov module line with the epic's one-paragraph summary,
    in the style of the existing #741 / #742 / #967 sentences.

Acceptance criteria

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions