.markgate.yml

# markgate configuration — https://github.com/go-to-k/markgate
#
# Four narrow-scope gates back the pre-commit / pre-PR / pre-merge
# checks for this repo. Each gate only invalidates when files in its
# own `include` set change, so a tests-only commit doesn't re-run doc
# checks and a docs-only commit doesn't re-run typecheck/build/tests.
#
# Gates:
#   check          — typecheck/lint/build/unit tests
#                    (set by /check and /verify-pr).
#   docs           — README/CLAUDE.md/docs consistency with src
#                    (set by /check-docs and /verify-pr).
#   verify-pr      — full PR-readiness checklist (live-test of changed
#                    behavior, shared-utility caller verification, PR
#                    title + body freshness, and a retrospective that
#                    proposes new rules/hooks/skills for any pattern
#                    that surfaced in the session). Set ONLY by
#                    /verify-pr. Declared as `requires: [check, docs]`
#                    so freshness is the AND of those children plus
#                    the skill's own work; `/verify-pr` cannot mark it
#                    fresh while either child is stale. The PreToolUse
#                    hook in .claude/hooks/verify-pr-gate.sh blocks
#                    `gh pr create` and `gh pr merge` (incl. --auto)
#                    when this gate is stale.
#   integ-destroy  — real-AWS deploy + destroy with zero orphan
#                    resources. Set ONLY by /run-integ when the destroy
#                    step finishes with 0 errors and the post-destroy
#                    AWS state is empty. Carries a 14d TTL on top of
#                    the file-scope check, so a marker stays valid only
#                    as long as the AWS-side behavior it verified is
#                    plausibly current. The PreToolUse hook in
#                    .claude/hooks/integ-destroy-gate.sh blocks
#                    `gh pr merge` (and `gh pr merge --auto`) when this
#                    gate is stale, so deletion-touching code never
#                    reaches main without a verified destroy.
#   pr-review      — `/review-pr` reviewer-dispatch verification on
#                    size-flagged PRs. Set ONLY by the `/review-pr`
#                    skill when its size + bias heuristic recommends
#                    1-reviewer or 3-axis review AND the dispatched
#                    reviewers complete with no blockers. Bound to
#                    the PR's HEAD sha via the `.markgate-pr-review-sha`
#                    sentinel file (the skill writes the current PR's
#                    HEAD sha there before `markgate set`, and the
#                    gate's `include:` scope is just that file — so
#                    a new push to the PR invalidates the marker
#                    automatically without any extra plumbing). The
#                    PreToolUse hook in .claude/hooks/pr-review-gate.sh
#                    blocks `gh pr merge` (NOT `gh pr create` — small
#                    PRs should be openable freely) when the marker
#                    is stale AND the target PR's tier from the
#                    `/review-pr` heuristic is `1-reviewer` or
#                    `3-axis`. `inline`-tier PRs always pass through.
#                    Closes the "sub-agent self-review ≠ independent
#                    review" gap surfaced by PR #267 / issue #270 (see
#                    memory rule feedback_subagent_review_not_self_review.md).
#
#   integ-local    — Docker-based `cdkd local *` family verification
#                    with zero orphan containers / networks. Set ONLY
#                    by /run-integ when a `local-*` integ test (e.g.
#                    `local-invoke`, `local-start-api`, `local-run-task`)
#                    finishes cleanly AND the post-run `docker ps` /
#                    `docker network ls` sweep is empty. Carries a 14d
#                    TTL on top of the file-scope check — Docker base
#                    images (`public.ecr.aws/lambda/*`, RIE binary),
#                    chokidar/network behavior, and `dockerd` semantics
#                    drift over time, so a marker that's been clean for
#                    two weeks no longer proves today's local code path
#                    actually works against today's environment. The
#                    PreToolUse hook in .claude/hooks/integ-local-gate.sh
#                    blocks `gh pr merge` (and `git merge`) when this
#                    gate is stale, so local-execution-touching code
#                    never reaches main without a verified Docker run.
#
# The PreToolUse hook in .claude/hooks/check-gate.sh verifies `check`
# and `docs` on every `git commit`.

gates:
  check:
    hash: files
    include:
      - "src/**"
      - "tests/**"
      - "package.json"
      - "pnpm-lock.yaml"
      - "tsconfig*.json"
      - "vitest.config.ts"
      - "build.mjs"
      - ".eslintrc*"
      - ".prettierrc*"

  docs:
    hash: files
    include:
      - "src/**"
      - "docs/**"
      - "README.md"
      - "CLAUDE.md"
      - ".claude/rules/**"

  verify-pr:
    # `requires` (markgate 0.3+) declares verify-pr's freshness as the
    # AND of `check` and `docs` instead of duplicating their include
    # globs. The pre-0.3 layout listed src/** + tests/** + docs/** etc.
    # explicitly here, drifting from check/docs over time. Now: edit
    # any check-scope file -> check stale -> verify-pr stale (and same
    # for docs). Set-time enforcement is also strict — `/verify-pr`
    # cannot mark this gate fresh while either child is stale, which
    # mirrors the skill's actual workflow (it runs /check + /check-docs
    # first). No own `include:` — freshness is purely the AND of
    # children, avoiding the git-tree default.
    requires: [check, docs]

  integ-destroy:
    hash: files
    # Wall-clock TTL on top of the file-scope check (markgate 0.3+).
    # Real-AWS behavior drifts even when the repo doesn't (AWS SDK
    # updates, API behavior changes, eventual-consistency tweaks); a
    # marker that's been clean for two weeks no longer proves the
    # destroy path actually works against today's AWS. `/run-integ`
    # resets the countdown on every successful set. 14d picked over
    # 7d (too aggressive — would force /run-integ on most PRs touching
    # destroy logic) and 30d (too lax — AWS SDK minors land roughly
    # weekly).
    ttl: 14d
    # Scope: every code path that participates in real-AWS resource
    # destruction. Editing any of these REQUIRES a fresh `/run-integ`
    # destroy verification before the PR can be merged. The list is
    # intentionally broad — false positives (forced extra integ runs)
    # are far cheaper than false negatives (broken destroy reaching a
    # release tag).
    include:
      - "src/provisioning/providers/**"
      # The CC provider's delete()/remnant-cleanup is deletion logic too —
      # it was missing from this scope until issue #1252 touched it.
      - "src/provisioning/cloud-control-provider.ts"
      - "src/cli/commands/destroy.ts"
      - "src/deployment/deploy-engine.ts"
      - "src/analyzer/dag-builder.ts"
      - "src/analyzer/implicit-delete-deps.ts"
      - "src/analyzer/lambda-vpc-deps.ts"

  pr-review:
    hash: files
    # Scope: a single sentinel file at repo root holding the PR HEAD sha
    # that /review-pr last verified. The skill writes the sha into the
    # file right before `markgate set pr-review`, so the marker's digest
    # is implicitly bound to the PR sha — a new push to the PR will
    # rewrite the file (via the next /review-pr run) and a stale marker
    # with the wrong sha is naturally caught by markgate's digest check.
    # The file is gitignored (see .gitignore) — it's per-checkout
    # bookkeeping, not a tracked artifact. No TTL: PR-sha binding is
    # enough; the skill should re-run when the PR changes anyway.
    include:
      - ".markgate-pr-review-sha"

  integ-broad:
    # Records the last broad real-AWS integ run. The canonical
    # broad-integ set (keep in sync with .claude/hooks/integ-broad-gate.sh
    # error message + .claude/skills/run-integ/SKILL.md step 11 +
    # .claude/skills/verify-pr/SKILL.md step 6 + CLAUDE.md):
    #   bench-cdk-sample
    #   lambda
    #   microservices
    #   drift-revert
    #   drift-revert-vpc
    #   multi-stack-deps
    #   multi-resource
    #   remove-protection
    #   export
    # Narrow feature integs like `import-value-strong-ref` flip the
    # `integ-destroy` marker but do not exercise multi-resource VPC /
    # Lambda / Custom-Resource paths, so a cross-cutting code change
    # to `src/deployment/deploy-engine.ts` etc. can ship a regression
    # the narrow integ never sees. This gate's hook blocks `gh pr
    # merge` when the diff touches cross-cutting paths AND the marker
    # is stale, forcing a broad integ in addition to whatever feature
    # integ the change came with.
    #
    # Why a separate marker (vs. extending `integ-destroy`): markgate
    # is content-digest based; `integ-destroy` doesn't distinguish
    # which integ flipped it. The sentinel below is written ONLY by
    # /run-integ when a broad-set test name passes — so a narrow
    # feature integ legitimately flips `integ-destroy` (it WAS a
    # clean real-AWS destroy) while leaving `integ-broad` stale,
    # which is exactly the gradient we want.
    #
    # Scope: a sentinel file at repo root carrying the last broad
    # integ's test name + timestamp. Updated ONLY by /run-integ when
    # the test name is in the broad set AND the run was clean.
    # Gitignored — per-checkout bookkeeping, not a tracked artifact.
    # Same 14d TTL as the other AWS-coupled gates so the marker ages
    # out automatically and the next cross-cutting PR triggers a
    # fresh broad run regardless of code changes.
    ttl: 14d
    hash: files
    include:
      - ".markgate-broad-integ-test"

  integ-local:
    hash: files
    # Wall-clock TTL on top of the file-scope check (markgate 0.3+).
    # Docker base-image behavior (`public.ecr.aws/lambda/*`, RIE
    # binary), `dockerd` semantics, and chokidar / network plumbing
    # drift even when the repo doesn't. 14d matches the integ-destroy
    # gate: aggressive enough to catch environment drift, lax enough
    # to avoid forcing a Docker run on every local-touching PR.
    ttl: 14d
    # Scope: every code path that participates in `cdkd local *`
    # execution (Lambda RIE containers, ECS task emulation, HTTP
    # server, container pool, etc.). Editing any of these REQUIRES a
    # fresh `/run-integ local-*` verification before the PR can be
    # merged. The list is intentionally broad — false positives
    # (forced extra integ runs) are far cheaper than false negatives
    # (a broken local path reaching a release tag).
    include:
      - "src/local/**"
      - "src/cli/commands/local-*.ts"
      - "tests/integration/local-*/**"

  integ-schema-migration:
    # Records the last cdkd state-schema migration integ run. cdkd's
    # S3 state schema (the on-disk shape of
    # `s3://bucket/cdkd/<stack>/<region>/state.json`) is the actual
    # user contract — millions of state files live in real AWS
    # accounts under the v1..v5 shapes already shipped. Bumping
    # `StackState.version` (v5 -> v6 etc.) MUST be transparently
    # auto-migrated by the new binary AND verified by a real-AWS
    # integ test that proves the round-trip: deploy under vN -> swap
    # binary -> read works -> next write upgrades to vN+1 silently ->
    # destroy clean. Unit tests can't catch wire-format divergences
    # (`undefined` field stripping, key ordering, schema version
    # coercion); only real round-trip does. Users must never need to
    # run an explicit migrate command for a schema bump — the binary
    # auto-migrates on first write under the new version.
    #
    # Why a separate marker (vs. extending `integ-destroy` /
    # `integ-broad`): a destroy / broad integ flips its marker on
    # ANY clean real-AWS destroy and exercises the v5 binary against
    # v5 state — neither verifies cross-version compatibility. The
    # only thing that does is an integ named
    # `schema-v<N>-to-v<N+1>-migration` which `/run-integ`
    # specifically recognizes and gates the `integ-schema-migration`
    # marker set on.
    #
    # Scope: just `src/types/state.ts` — the file carrying the
    # `StackState.version` literal type, the
    # `STATE_SCHEMA_VERSIONS_READABLE` constant, and every
    # state-shape interface. Editing any other path doesn't touch
    # the schema. The hook
    # (`.claude/hooks/integ-schema-migration-gate.sh`) does a
    # precise second-pass `gh pr diff` grep for actual
    # version-constant additions/deletions so non-bump edits to this
    # file (JSDoc, helper functions, comment fixes) pass through
    # without false-positive activation. Same 14d TTL as the other
    # AWS-coupled gates.
    ttl: 14d
    hash: files
    include:
      - "src/types/state.ts"