feat(git-delivery): governed remote publish gateway for push, upstream, and protected-target awareness (#476)#1527
Merged
Conversation
…tream, and protected-target awareness Add the governed publish layer (Issue #476, Epic #470) that turns local commit completion into safe remote delivery. `git push` becomes a controlled publish workflow with explicit preview, policy enforcement, recovery semantics, and evidence capture for allowed and blocked attempts. - keiko-tools: new `git-publish-gateway.ts` (pure) — `GitPushCommand`, the narrow `GitRemotePublishAdapter` port, a dedicated push-only allowlist, `buildPushArgv` (refuses force), the publish-rejection taxonomy, and the `runGitPublish` orchestrator producing a kernel-shaped lifecycle result. New `git-publish-node.ts` Node executor classifies rejections from git output. Push preflight gains a `non-fast-forward` finding. - keiko-server: new `pushExecution.ts` (`executeGovernedPublish`, default-safe publish policy pack, preview/response projections) + `pushRoutes.ts` (`/api/git-delivery/push/preview` read-only, `/push/execute` governed). - keiko-ui: a Publish section in `GovernedGitFlowCard`. - Protected/shared targets are blocked by policy (stricter than user branches); force push is blocked by default (publish risk ceiling + argv refusal). - ADR-0063; integration, route, unit, UI, and packaged-app browser evidence. Refs #476 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
0b5b092
into
feat/keiko-establish-governed-end-to-end-git-delivery
11 checks passed
This was referenced Jun 25, 2026
Closed
Merged
oscharko
added a commit
that referenced
this pull request
Jun 26, 2026
* feat(git-delivery): add governed Git action contracts, policy packs, and risk semantics (#471) (#1503) Introduce the typed contract foundation for Epic #470 governed Git delivery: three keiko-contracts leaf modules (git-delivery, git-delivery-policy, git-delivery-provider) defining the 10-kind action model, the 4-class risk taxonomy with data-driven severity, the approval-intent model, the lifecycle envelope (resolved inputs / policy decision / approval requirement / preview / result / evidence ref), repo and org policy packs with a deterministic fail-closed evaluator, and provider-neutral branch-protection / checks / pull-request / merge-readiness interfaces. Adds ADR-0058, an operator-facing governance doc, and a keiko-tools boundary test proving the read-only terminal baseline still denies every Git mutation so governed write authority lives only behind these typed contracts (AC5). Enables CI and CodeQL on the feat integration branch by mirroring the existing feat/prompt-enhancer-1307 trigger and protected-branch-gate entries. Refs #471 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * fix(git-delivery): harden #471 contract validators per adversarial review (#1506) Stricter parse-time enum guards (actionKind, provider-capability) and typed GitDeliveryRemoteTargetPolicy push-target patterns, with 10 regression tests. Follow-up to #1503. Refs #471. * feat(git-delivery): governed Git mutation execution kernel (Refs #472) (#1509) Implement the deterministic preflight and mutation orchestration kernel for governed local Git writes (Issue #472, Epic #470), consuming the #471 contracts. - Lifecycle orchestrator (runGitMutation): resolve, preflight, preview, policy, execute, result — the single execution authority over local mutation kinds. - Deterministic preflight evaluators over a content-free worktree snapshot, with typed findings (blocking/advisory severity; user-actionable/internal remediation); idempotent reruns by construction. - Narrow local Git adapter: a typed port with NO generic exec method, a closed governed command table, a dedicated allowlist, and pure argv builders with flag-injection guards. The Node adapter runs plans through the existing keiko-tools no-shell spawn boundary. - Structured failure taxonomy (policy-block / preflight-block / execution-failure / provider-failure / recovery-required) consumable without string parsing. - Idempotency journal (records successes only) and safe-retry semantics. - ADR-0059 + docs; barrel exports + surface pins; ./internal/git-mutation subpath. The read-only terminal git baseline is preserved and machine-checked complementary to the governed write surface. Remote/provider execution (push/PR/merge) is deferred to #476-#478 behind a separate gateway. Refs #472 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): add approval orchestration, preview manifests, and action-sheet UX contracts (#473) (#1513) Implement the approval and preview presentation layer for governed Git delivery (Issue #473, Epic #470) on top of the #471 contracts and the #472 execution kernel. - keiko-contracts: new strict-leaf git-delivery-action-sheet.ts projecting the kernel's content-free facts into a UI-safe GitDeliveryActionSheet — a three-state union (ready-to-execute / waiting-for-approval / blocked), an approval summary with mandatory/optional/impossible necessity, a content-free preview manifest (branch targets, mutation scope, remote impact, PR/merge/branch-protection/checks state, expected blockers), a policy/preflight/provider-not-ready blocked-cause classification, and recovery hints with a suggested governed recovery strategy. Includes the wire request type and pure assemblers/guards/parsers. - keiko-server: POST /api/git-delivery/action-sheet — a read-only/computational BFF endpoint that runs the pure kernel phases (evaluateGitPreflight + evaluateGitPolicy over TRUSTED server policy packs) and projects them into a sheet. Default-false deployment capability gate; CSRF + body-cap + strict-key + secret-shape + unsafe-format-char (Trojan-Source) rejection; deep-redacted response; expiry-aware approval demotion (clock parity with the #472 kernel). - keiko-ui: desktop GitDeliveryActionSheetCard rendering ready/blocked/recovery states with alertdialog semantics, focus management, a status live region, not-colour-alone labelling, and jest-axe coverage; fetchGitDeliveryActionSheet client. - ADR-0060 + docs/git-delivery/governed-git-approval-surface.md; regenerated ADR-0051 visual-regression proofs (evidence/1300) after the additive .gdas-* globals.css block. Authority stays server-side; the action sheet is a pure projection over backend facts, never a second policy system. No mutation executes in this slice (local execution is #472; remote push/PR/merge are #476-#478). Content-free throughout. Refs #473 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): governed Git mutation evidence ledger, audit export, and recovery metadata (Refs #474) (#1517) * feat(git-delivery): add governed Git mutation evidence ledger, audit export, and recovery metadata (Refs #474) Deliver the audit and compliance backbone for Epic #470 governed Git delivery so mutating repository actions become inspectable, exportable, and supportable after execution (Issue #474). - keiko-contracts: new strict-leaf `git-delivery-evidence.ts` defining the content-free `GitDeliveryEvidenceRecord`, exportable `GitDeliveryAuditPacket`, AC1 outcome-class vocabulary, the net-new retrospective three-way `GitDeliveryRecoveryDisposition` (retryable/user-fixable/policy-forbidden/none), and total exhaustive recovery-disposition derivations. Reuses the #473 recovery action-hint and #471 strategy vocabularies (no parallel subsystem). - keiko-tools: pure `buildGitDeliveryEvidenceRecord` projecting the #472 `GitMutationLifecycleResult` into a record for EVERY terminal outcome; hashes remote identifiers, the provider external id, and the repo identity (content-free by construction). - keiko-server: bounded, date-bucketed append-only evidence ledger (`mutationEvidenceLedger.ts`, redact-then-persist, fail-closed, never throws) and a capability-gated `GET /api/git-delivery/evidence` audit-export route with re-redaction on read. - ADR-0061 and docs/git-delivery/governed-git-evidence-ledger.md. Tests: 47 new (contracts 13, tools 21, server 13) proving AC1 completeness, AC2/AC5 no-secret-leak, AC3 recovery classification, AC4 export. Producer wiring of the kernel into a live execution route remains deferred to #476-#478. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(git-delivery): harden #474 evidence ledger per adversarial review (Refs #474) Adversarial 5-lens review (security/architecture/correctness/tests/redaction-skeptic; 3 SHIP, 1 SHIP_WITH_FIXES, no blockers). Confirmed fixes: - correctness (medium): effectiveBlockReason no longer attaches an eagerly-evaluated policy block reason to a preflight-blocked outcome (the policy gate never fired); preflight blocks now carry no policy blockReason. Regression test added. - audit integrity: strip bidirectional/zero-width/BOM format characters from echoed branch names so a crafted ref cannot visually spoof an audit row. Test added. - guard: isGitDeliveryAuditPacket now verifies recordCount === records.length. - export honesty: the audit packet now carries a bounded-window limitation note; multi-day cross-bucket + window-exclusion route tests added. - docs: soften the SHA-256/redactor wording (redactor is a secret-shape backstop, not a catch-all; the primary control is by-construction hashing); document that approver ids and branch names are deliberately retained governance provenance; correct ADR-0061 builder deps (deps.hash), correlation mechanism, server filenames, and the stale boundary-review note. Disposition: raw approver ids are intentional governance provenance (AC2 requires preserving approval provenance); not a leak. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): governed local branch, staging, and commit flows with commit-intent composition (Refs #475) (#1523) * feat(git-delivery): commit-message policy + commit-intent contracts and branch-switch kind (Refs #475) Adds two strict keiko-contracts leaves (git-commit-policy.ts, git-commit-intent.ts) and the governed branch-switch action kind. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(adr): ADR-0062 governed local git flows and commit-intent (Refs #475) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): branch-switch kernel, read-only worktree snapshot reader, commit-intent summary (Refs #475) Adds the governed branch-switch command across the #472 kernel (adapter argv, orchestrator dispatch, preflight switch-target-missing), a read-only worktree snapshot reader on the internal git-mutation subpath, and the pure commit-intent change summarizer. Threads the new finding code through the action-sheet projection recovery-hint table. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): governed local branch/staging/commit execution + preview routes (Refs #475) Adds the BFF execution surface for the #475 local flows: branch create/switch + staging routes and a read-only commit preview + governed commit execute route. Each runs the #472 kernel (preflight + policy + approval) over a server-built live snapshot, enforces the commit-message policy before the kernel, surfaces commit-intent quality warnings, and records evidence through the #474 ledger. Capability- and CSRF-gated, content-free, fail-closed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): governed local git flow desktop surface (Refs #475) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(git-delivery): governed local git flows reference (Refs #475) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(git-delivery): browser e2e evidence for governed commit no-bypass + fix window persistence (Refs #475) Adds a deterministic Playwright spec (real packaged app, governed routes intercepted) proving the browser commit path surfaces the governed message-policy block and cannot bypass /commit/execute (AC5 browser half). Fixes the governedGit window persistence from evidence-reference (which strips the slash-bearing project path → broken empty window on reload) to fs-reference, matching the path-carrying files/editor windows. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * style(git-delivery): satisfy strict lint in #475 test files (Refs #475) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * test(git-delivery): restore #475 coverage gate + validator-totality hardening (Refs #475) (#1525) * test(git-delivery): raise branch coverage + harden commit-message validator totality (Refs #475) Adversarial-review follow-ups: guard new RegExp in the issue-key check so the pure validateGitCommitMessage stays total (and fails closed) on a malformed operator-configured pattern. Add an execution-core integration test (real git through the default seams) + route branch-coverage for worktree-unavailable, approval-required, allowEmpty, the real branch/staging specs, and validation paths; drop the unused isStringArray guard. Restores keiko-server branches above its ratchet floor. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> (cherry picked from commit 1a99e4e) * fix(test): use the real in-memory store in the resolveProjectWorkspace test (Refs #475) The fake Project literal did not satisfy the UiStore type under the full tsc --noEmit (which checks test files); use createInMemoryUiStore so the test is type-safe. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): add governed remote publish gateway for push, upstream, and protected-target awareness (#1527) Add the governed publish layer (Issue #476, Epic #470) that turns local commit completion into safe remote delivery. `git push` becomes a controlled publish workflow with explicit preview, policy enforcement, recovery semantics, and evidence capture for allowed and blocked attempts. - keiko-tools: new `git-publish-gateway.ts` (pure) — `GitPushCommand`, the narrow `GitRemotePublishAdapter` port, a dedicated push-only allowlist, `buildPushArgv` (refuses force), the publish-rejection taxonomy, and the `runGitPublish` orchestrator producing a kernel-shaped lifecycle result. New `git-publish-node.ts` Node executor classifies rejections from git output. Push preflight gains a `non-fast-forward` finding. - keiko-server: new `pushExecution.ts` (`executeGovernedPublish`, default-safe publish policy pack, preview/response projections) + `pushRoutes.ts` (`/api/git-delivery/push/preview` read-only, `/push/execute` governed). - keiko-ui: a Publish section in `GovernedGitFlowCard`. - Protected/shared targets are blocked by policy (stricter than user branches); force push is blocked by default (publish risk ceiling + argv refusal). - ADR-0063; integration, route, unit, UI, and packaged-app browser evidence. Refs #476 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): governed GitHub pull request command center and metadata orchestration (Refs #477) (#1531) Deliver the governed pull request layer for Epic #470 (ADR-0064): turn a published branch into a review-ready GitHub PR through an explicit, governed workflow — a parallel execution authority to the #476 publish gateway, never an extension of it. - contracts: new strict leaf git-pull-request.ts — provider-neutral, content-free readiness model (objectExists vs reviewReady + severity-ranked blockers), deterministic metadata synthesis, draft-vs-ready recommendation, reviewer/label/ linkage suggestions, and a neutral rejection taxonomy with exhaustive disposition/error-code tables. No cross-package imports, no provider field names. - tools: git-pr-gateway.ts (pure PR gateway — GitPullRequestCommand carrying title/body, narrow two-method adapter port, dedicated `gh api` allowlist with NO merge/delete, pure argv builders, GitHub-error classifier, effective policy, runGitPullRequest returning a kernel-shaped lifecycle the #474 evidence builder consumes unchanged) + git-pr-node.ts (Node `gh api` executor; gh reads its own token, Keiko never does). - server: prExecution.ts + prRoutes.ts (read-only preview + governed execute) under a default-safe KEIKO_DEFAULT_PR_POLICY_PACK; content-free evidence (only byte lengths), capability-gated behind KEIKO_GIT_DELIVERY_ENABLED. - ui: GovernedPullRequestCard.tsx command center (editable metadata draft, readiness panel, recommendation, normalized failures). Inline CSS vars (globals.css untouched); WCAG 2.2 AA (aria-live, text-not-colour). - tests: contracts/tools/server/ui unit + a11y suites; browser e2e proving the PR path reaches the governed BFF routes with no bypass (evidence under docs/git-delivery/evidence/477). Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * feat(git-delivery): governed merge gateway, protected-branch enforcement, and guided recovery (Refs #478) (#1534) The merge layer of Epic #470 (ADR-0065): a THIRD parallel `gh api` execution authority that turns a review-ready pull request into a merged base branch as a governed release decision. Merge cannot execute until preflight, policy + final approval, and a provider readiness gate all pass; the provider's own enforcement is the backstop. - keiko-contracts: NEW leaf git-merge.ts — provider-neutral merge-readiness model (severity-ranked blockers reusing GitDeliveryMergeBlockReason + lifecycle states), strategy eligibility (policy ∩ provider capability), merge recommendation, and the rejection taxonomy with exhaustive error-code / recovery-disposition tables. Pure; existing contracts unchanged. - keiko-tools: git-merge-gateway.ts (GitMergeCommand, narrow two-method GitMergeAdapter, dedicated `gh api` merge allowlist, argv builders, ordered GitHub merge-error classifier, mergeable_state mapper, runGitMerge 3-gate orchestrator producing a kernel-shaped lifecycle) + git-merge-node.ts (Node `gh api` executor: readiness reads + merge PUT + guarded non-fatal branch DELETE; token read by gh, never by Keiko). - keiko-server: gitDelivery/mergeExecution.ts (approval-gated KEIKO_DEFAULT_MERGE_POLICY_PACK; preview/execute projections carrying per-blocker recovery info) + mergeRoutes.ts (read-only preview + governed execute, capability gate, validation, #474 evidence). Route group registered. - keiko-ui: GovernedMergeCard.tsx (window "governedMerge": eligible-strategy selector, readiness/recovery panel, final high-risk confirmation, outcome banner; inline CSS vars, globals.css untouched) + api client + window registry. - Docs: ADR-0065, docs/git-delivery/governed-merge.md. - Tests: contracts (38), tools gateway/node (55), server routes (13), UI card + a11y (17); browser e2e (playwright.issue-478) proving no merge-anyway bypass, with evidence under docs/git-delivery/evidence/478. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * docs(git-delivery): add Issue #479 closure evidence (#1536) Refs #479 * docs(git-delivery): finalize Epic #470 closeout after child-issue reconciliation (Refs #470) (#1538) The #479 closeout summary recorded that Epic #470 must remain open until the GitHub issue and project-board records for #472, #477, and #478 were reconciled with their already-merged code. #477 and #478 have since been closed; this finalizes the remaining reconciliation of #472 (governed Git mutation execution kernel, PR #1509 / 401b08a) and retires the closure-gating note now that all nine child issues (#471-#479) are closed and every Definition-of-Done and Expected-Verification item is evidenced. Refs #470 Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com> * fix(git-delivery): harden governed merge audit gaps (Refs #470) (#1542) * test(ui): refresh design-system evidence after git delivery integration * feat(editor): route Git status actions to governed delivery * feat(editor): complete runtime git command hub --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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.
Summary
Adds the governed publish layer (Issue #476, Epic #470) that turns local commit completion into safe remote delivery.
git pushis no longer a raw transport call — it becomes a controlled publish workflow with explicit preview, policy enforcement, recovery semantics, and evidence capture for allowed and blocked attempts. This is the point where local quality meets shared-team risk, so the controls become stricter, not looser.Remote push is executed by a separate publish gateway (per the #472 kernel's own deferral comment), never the local mutation adapter — which stays network-free. The gateway reuses the kernel's pure machinery (preflight, policy, the lifecycle-result shape, the evidence builder) so there is no second policy system and no second evidence schema. keiko-contracts is unchanged — the push input shape, execution error codes, and recovery vocabulary it already defines are sufficient.
Refs #476
Scope
["push"]allowlist + publish-rejection taxonomy); a Node push executor that classifies rejections from git output; anon-fast-forwardpreflight finding; server push preview/execute routes reusing the gateway + ledger + a default-safe publish policy pack; a Publish section in the existing governed flow card; integration/route/unit/UI/browser evidence; ADR-0063.Acceptance Criteria → Evidence
POST /api/git-delivery/push/previewreturns remote target, risk class, would-create-remote-branch / force-blocked flags, preflight findings, and the effective policy outcome for that target.pushRoutes.test.ts"push preview" + e2e.KEIKO_DEFAULT_PUBLISH_POLICY_PACKpermits only safe namespaces (claude/ feat/ fix/ chore/ docs/) within thepublishceiling;dev/main/release/*→policy-pack-blocked. Proven in gateway, route, and integration tests + e2e.GitPublishRejectionReasontaxonomy (8 reasons) → typed error code + reused recovery disposition/action hint, surfaced live;non-fast-forwardalso detected at preflight.git-publish-gateway.test.tsclassifier +git-publish-node.integration.test.tsreal non-ff classification.recovery-or-rewrite>publish) andbuildPushArgvrefusing any force argv. Proven in gateway, route, and integration tests (remote untouched).git-publish-node.integration.test.tsagainst real hermetic bare+working repos: real push reaches the remote; real non-ff classified at execution; force blocked + remote untouched; evidence recorded for allowed and blocked; push absent from the local mutation allowlist.Reuse And No-Duplication
Reuse evidence: the gateway produces a
GitMutationLifecycleResultconsumed unchanged by the #474 evidence builder (push case already present); reusesevaluateGitPreflight(push case),evaluateGitPolicy, and the #473/#474 recovery vocabulary; the BFF routes reuserequestGuards,isGitDeliveryTrusted, the evidence ledger, and theGovernedGitFlowCard. Zero keiko-contracts change.Product Impact
Verification
Required:
cipasses before merge.Local verification:
Security review: a separate publish gateway keeps the local mutation adapter network-free; the push allowlist permits only
pushand denies every force/rewrite flag; raw git output never crosses the boundary (only typed rejection reasons); refspec/flag-injection guarded at the route (isSafeGitRef) and the gateway (assertRef). Adversarial multi-lens review (security / correctness / contract-boundary / test-adequacy) with skeptic verification — disposition in the closure comment.🤖 Generated with Claude Code