feat(B-0058): alignment-clause drift detector#2103
Merged
Conversation
New TS tool at tools/alignment/audit_clause_drift.ts — compares docs/ALIGNMENT.md between two git refs to detect clause additions, removals, title changes, and body modifications. For each changed clause, cross-references the existing clause-coverage audit to report which factory surfaces (skills, agents) depend on it. This is slice 2 of B-0058 (responsibility #4: alignment-clause drift detector). Enables impact-survey before any renegotiation of alignment clauses — answers "who depends on this clause, and what breaks if it moves?" Tested: detects SD-2 + SD-9 body changes across commit 00b02e0. Build gate: 0 warnings, 0 errors. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
There was a problem hiding this comment.
Pull request overview
Adds a new Bun/TypeScript automation tool to detect drift in docs/ALIGNMENT.md clauses between two git refs and report which factory surfaces cite the affected clauses, extending the existing alignment observability tooling.
Changes:
- Added
tools/alignment/audit_clause_drift.tsto diff alignment clauses between--baseand--headrefs and emit human/JSON/Markdown reports. - Cross-referenced clause drift results with
audit_clause_coverage.tsoutput to list dependent skills/agents. - Registered the new tool in
tools/alignment/README.md.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| tools/alignment/README.md | Adds the new drift-audit script to the alignment tools index. |
| tools/alignment/audit_clause_drift.ts | New drift detector that parses clause snapshots at two refs and reports adds/removals/title/body changes plus dependent surfaces. |
Comment on lines
+217
to
+233
| } else if (baseClause.title !== headClause.title) { | ||
| diffs.push({ | ||
| id, | ||
| kind: "title-changed", | ||
| baseTitle: baseClause.title, | ||
| headTitle: headClause.title, | ||
| dependentSurfaces: depMap.get(id) ?? [], | ||
| }); | ||
| } else if (baseClause.body !== headClause.body) { | ||
| diffs.push({ | ||
| id, | ||
| kind: "body-changed", | ||
| baseTitle: baseClause.title, | ||
| headTitle: headClause.title, | ||
| dependentSurfaces: depMap.get(id) ?? [], | ||
| }); | ||
| } |
Comment on lines
+119
to
+125
| function getFileAtRef(ref: string, path: string): string | null { | ||
| const result = spawnSync( | ||
| "git", // eslint-disable-line sonarjs/no-os-command-from-path | ||
| ["show", `${ref}:${path}`], | ||
| { encoding: "utf8" }, | ||
| ); | ||
| if (result.error || result.status !== 0) return null; |
Comment on lines
+198
to
+205
| const baseClauses = baseContent !== null ? extractClauses(baseContent) : []; | ||
| const headClauses = headContent !== null ? extractClauses(headContent) : []; | ||
|
|
||
| const baseMap = new Map(baseClauses.map((c) => [c.id, c])); | ||
| const headMap = new Map(headClauses.map((c) => [c.id, c])); | ||
| const depMap = buildDependencyMap(); | ||
|
|
||
| const diffs: ClauseDiff[] = []; |
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
tools/alignment/audit_clause_drift.ts— comparesdocs/ALIGNMENT.mdbetween two git refs to detect clause additions, removals, title changes, and body modificationsaudit_clause_coverage.tsto report dependent factory surfaces (skills, agents)What it does
Answers the question from B-0058 §4: "who depends on this clause, and what breaks if it moves?" before the renegotiation is accepted.
Supports
--json,--md, and human-readable output. Exit code 1 when removals or body changes detected; 0 otherwise.Test plan
--base main --head HEAD): 0 diffs, exit 000b02e09): correctly detects SD-2 + SD-9 body changes with dependent surfaces--jsonoutput: valid JSON with schemaclause-drift-v1--mdoutput: valid markdown table--help: prints usagedotnet build -c Release— 0 warnings, 0 errors🤖 Generated with Claude Code