Skip to content

feat(architecture): wire approve-architecture consumption (transition to PR 3/6) - #297

Merged
hzcheng merged 2 commits into
mainfrom
agent-pivot/arch-approval-transition
Aug 19, 2026
Merged

feat(architecture): wire approve-architecture consumption (transition to PR 3/6)#297
hzcheng merged 2 commits into
mainfrom
agent-pivot/arch-approval-transition

Conversation

@hzcheng

@hzcheng hzcheng commented Aug 19, 2026

Copy link
Copy Markdown
Owner

Summary

Transition PR for the Harness Simplification program (between PR 2/6 and PR 3/6). The decision record (docs/architecture/harness-simplification-decision.md) replaced Architecture Change record machine authorization with owner architecture approval (approve-architecture <full-head-sha>), but the merged gates never consumed it. This wires the consumption path so PR 3/6 (which deletes the record machinery and therefore cannot be authorized by a record) can be evaluated and merged.

Root causes fixed:

  • merge-approval gate: evaluated only approve <sha> and base records — a relaxing change that may not add records (ADR: no new records during the window) could never be authorized. The gate now detects the owner's approve-architecture <full-head-sha> comment and threads the verdict into the declaration evaluation.
  • quality lane: the architecture change gate demanded approve-architecture <sha> but nothing consumed the comment. The classifier now accepts an architectureApproved verdict; the verify workflow detects the owner comment and exports ARCHITECTURE_APPROVED (PR-lane feedback only — the merge gate re-verifies from the default branch).
  • trusted kernel: could not materialize the PR head (the pull_request_target checkout fetches only the base ref, so both git checkout <sha> and git diff base...head failed) and never received the approval flag. The workflow now fetches the PR head first; the kernel looks up the owner's approval comment via the GitHub API (fail-closed).
  • architecture-approval job: diffed the base branch against itself (git diff origin/main HEAD where HEAD is the base checkout) and always passed vacuously. It now diffs the base against the fetched PR head SHA.

Skill harvest

Updated .skills/fixing-regressions-with-ci: when a CI check fails, first identify which side of the PR supplies the check's code — pull_request checks run PR-head files, pull_request_target checks (merge-approval gate, trusted kernel) run default-branch files, so a PR-head edit cannot change a default-branch check until it merges. This is the lesson from PR #296's repeated CI failures.

Known red check (bootstrap)

trusted-kernel will fail on this PR: the check runs the default branch's kernel, which cannot yet fetch the PR head (this PR is the fix). After this PR merges, the kernel on main becomes functional and evaluates PR #296 with the approval consumption above.

Change impact declaration

{
  "headSha": "6cc7fca077b4929411d6dbaede79e8e560346ece",
  "capabilities": [
    "MAIN-ARCHITECTURE-HARNESS"
  ],
  "modules": [],
  "invariants": [],
  "policyDelta": "tightening",
  "baselineWaiverDelta": "zero",
  "newFiles": [],
  "behaviors": [
    "ARCH-CHANGE-GATE-001",
    "ARCH-CLOSED-WORLD-001",
    "ARCH-INVARIANT-CATALOG-001",
    "ARCH-MODULE-BOUNDARY-001",
    "ARCH-MODULE-CYCLE-001",
    "ARCH-POLICY-SCHEMA-001",
    "ARCH-PROGRAM-LEDGER-001",
    "ARCH-SINGLE-WRITER-001",
    "ARCH-WEBVIEW-MANIFEST-001"
  ],
  "semanticImpact": {
    "stateAuthority": false,
    "writerSet": false,
    "protocol": false,
    "persistence": false,
    "identity": false,
    "recovery": false
  },
  "coordinators": [],
  "verification": "npm run test-compile; node --test tests/unit/tooling/** tests/unit/architecture/** (565 pass); npm run test:architecture-policy; npm run test:behavior-contracts; npm run lint; node scripts/architecture/checkArchitectureChange.js (classification: tightening)"
}

@hzcheng
hzcheng force-pushed the agent-pivot/arch-approval-transition branch from 2ce8e1a to 5766249 Compare August 19, 2026 10:17
chenghongze added 2 commits August 19, 2026 18:24
… to PR 3/6)

The harness simplification decision (docs/architecture/
harness-simplification-decision.md) replaces Architecture Change record
machine authorization with owner architecture approval, but the merged
gates never consumed it:

- the merge-approval gate evaluated only 'approve <sha>' and base
  records, so a relaxing change that may not add records (ADR: no new
  records during the window) could never be authorized;
- the quality lane's architecture change gate demanded
  'approve-architecture <sha>' but nothing consumed the comment;
- the trusted kernel could not materialize the PR head (the
  pull_request_target checkout fetches only the base ref) and never
  received the approval flag;
- the architecture-approval job diffed the base against itself and
  always passed vacuously.

Changes:

- mergeApprovals: add the ARCHITECTURE_APPROVAL_PATTERN binding form and
  findArchitectureApprovalComment; standard approval never substitutes.
- checkArchitectureChange: classifyArchitectureChange accepts
  { architectureApproved }; an approved relaxing/re-partition change is
  authorized without a base record. The CLI consumes
  ARCHITECTURE_APPROVED=true (developer feedback only; the merge gate
  re-verifies from the default branch).
- changeImpactContext and run-merge-approval-gate: thread the owner
  approval verdict into the declaration evaluation.
- run-trusted-kernel: look up the owner's approve-architecture comment
  bound to the exact head SHA via the GitHub API (fail-closed).
- trusted-kernel workflow: fetch the PR head before evaluating; pass
  PR_NUMBER/GITHUB_TOKEN; declare read permissions.
- run-architecture-approval-gate: diff base against the fetched PR head
  SHA instead of HEAD (the checkout is the base branch).
- verify workflow: the quality lane detects the owner approval comment
  and exports ARCHITECTURE_APPROVED (job-scoped issues:read).
- Skill harvest: fixing-regressions-with-ci now requires identifying
  which side of the PR supplies a failing check's code before editing.
Skill-Harvest: updated .skills/fixing-regressions-with-ci
@hzcheng
hzcheng force-pushed the agent-pivot/arch-approval-transition branch from 5766249 to 6cc7fca Compare August 19, 2026 10:25
@hzcheng

hzcheng commented Aug 19, 2026

Copy link
Copy Markdown
Owner Author

approve 6cc7fca

@hzcheng
hzcheng merged commit ba0944e into main Aug 19, 2026
9 of 10 checks passed
hzcheng pushed a commit that referenced this pull request Aug 19, 2026
…ics (PR 3/6)

Net -846 lines. The trusted kernel has taken over.

- Delete scripts/run-guard-mutation-parity.js
- Remove guardSemantics from the record schema and delta flags
- checkArchitectureChange.js: no record matching; a relaxing or
  re-partition classification is authorized only by the owner's
  approve-architecture <full-head-sha> comment (consumption wired in
  the transition PR #297)
- describeArchitectureChange.js: diff reporter only
- run-trusted-kernel.js: materialize the head via git ls-tree +
  git show (no symmetric diff against unfetched objects); consume the
  owner's approve-architecture comment from the GitHub API (fail-closed)
- trustedKernel.js: drop the deleted parity script from protected paths
- Remove parity from tests, protected paths, and release packaging
hzcheng pushed a commit that referenced this pull request Aug 19, 2026
…ics (PR 3/6)

Net -846 lines. The trusted kernel has taken over.

- Delete scripts/run-guard-mutation-parity.js
- Remove guardSemantics from the record schema and delta flags
- checkArchitectureChange.js: no record matching; a relaxing or
  re-partition classification is authorized only by the owner's
  approve-architecture <full-head-sha> comment (consumption wired in
  the transition PR #297)
- describeArchitectureChange.js: diff reporter only
- run-trusted-kernel.js: materialize the head via git ls-tree +
  git show (no symmetric diff against unfetched objects); consume the
  owner's approve-architecture comment from the GitHub API (fail-closed)
- trustedKernel.js: drop the deleted parity script from protected paths
- Remove parity from tests, protected paths, and release packaging
@hzcheng
hzcheng deleted the agent-pivot/arch-approval-transition branch August 19, 2026 15:44
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