stage-prompt-drift-guard
Audit historical stage-prompt artifact drift from Codex logs, generate a package index, and enforce only newly introduced drift in CI and local pre-push hooks.
Best use case
stage-prompt-drift-guard is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Audit historical stage-prompt artifact drift from Codex logs, generate a package index, and enforce only newly introduced drift in CI and local pre-push hooks.
Teams using stage-prompt-drift-guard should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/stage-prompt-drift-guard/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How stage-prompt-drift-guard Compares
| Feature / Agent | stage-prompt-drift-guard | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Audit historical stage-prompt artifact drift from Codex logs, generate a package index, and enforce only newly introduced drift in CI and local pre-push hooks.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Stage Prompt Drift Guard
Use when Codex/work-queue history references `.Codex/work-queue/assets/<work-item>/stage-*-prompt.md` files that no longer exist, and you need to make that drift visible without failing on all historical debt.
## When to use
- Codex session log audit shows many missing `stage-*-prompt.md` reads
- You want an auditable index of prompt packages and surviving evidence files
- You need a CI/local guard that blocks only newly introduced drift, not legacy repo drift
## Core approach
### 1. Extend the audit before enforcing
Build or update an audit script that:
- parses Codex post-hook log records
- detects prompt-like reads and stage prompt reads
- groups them by work item (`WRK-123`, `workspace-hub-456`)
- emits a `stage_prompt_packages` structure with:
- `work_item`
- `stages`
- `prompt_files` with `path`, `exists`, `reads`
- `evidence_files`
Important: scan both
- historical prompt reads from logs, and
- current asset directories under `.Codex/work-queue/assets/*`
so packages with surviving evidence but no prompt files are still represented.
### 2. Generate a human-auditable report
Write markdown/JSON report artifacts under `docs/reports/`.
The markdown should include a “Stage prompt package index” section that lists for each package:
- stages seen
- prompt file count
- missing prompt artifact count
- evidence file count
This turns missing prompt drift into a visible artifact instead of a hidden log-only problem.
### 3. Detect real drift issues
A drift issue is:
- one or more missing stage prompt files, and
- no replacement evidence for that package
Useful replacement evidence:
- `.Codex/work-queue/assets/<work-item>/evidence/*`
- explicit report/index paths if you intentionally replaced prompt artifacts with generated summaries
### 4. Enforce only newly introduced drift
Do NOT fail on the full historical backlog.
Add `--base-ref` / `--head-ref` support and compute:
```bash
git diff --name-status <base>...<head>
```
Then only fail when:
- a missing prompt path is in the deleted set for the current diff, and
- the same diff does not add replacement evidence or an approved report/index replacement
This is the key practical finding: strict enforcement on total historical drift is unusable; diff-scoped enforcement works.
### 5. Wire the guard into CI
Best home: an existing enforcement workflow for PRs.
Pattern:
- checkout with full history
- setup Python + uv
- run the drift checker with `--base-ref origin/main --head-ref HEAD --fail-on-issues`
- always append the markdown report to `$GITHUB_STEP_SUMMARY`
Expected result:
- historical repo drift remains visible in reports
- PRs only fail when they introduce new drift
### 6. Wire the same guard into local pre-push
Create a wrapper shell script, e.g. `scripts/enforcement/require-stage-prompt-drift.sh`, that:
- defaults to `origin/main...HEAD`
- skips cleanly if base ref is unavailable locally
- supports strict/advisory modes via env vars
- calls the Python drift checker with `--fail-on-issues`
- passes `--write-evidence-stubs` by default unless explicitly disabled
- writes JSONL audit events to `logs/hooks/stage-prompt-drift-events.jsonl`
Recommended env vars:
- `STAGE_PROMPT_DRIFT_BASE_REF`
- `STAGE_PROMPT_DRIFT_HEAD_REF`
- `STAGE_PROMPT_DRIFT_STRICT`
- `STAGE_PROMPT_DRIFT_SCRIPT`
- `STAGE_PROMPT_DRIFT_WRITE_STUBS`
- `STAGE_PROMPT_DRIFT_LOG`
- `DISABLE_ENFORCEMENT`
Behavior that proved useful:
- log `pass`, `warning`, `fail`, and `skip` verdicts
- print remediation guidance on warning/fail
- if strict mode is off, warn but allow push
Then wire it into `.git/hooks/pre-push` via the repo’s hook installer rather than editing hooks manually every time.
### 7. Add a local doctor/status command
Add `scripts/enforcement/stage-prompt-drift-status.sh` that reports:
- whether `scripts/enforcement/require-stage-prompt-drift.sh` exists
- whether `.git/hooks/pre-push` exists
- whether the hook references `require-stage-prompt-drift.sh`
- overall state: `ACTIVE` or `INACTIVE`
Recommended behavior:
- exit 0 only when all three conditions are satisfied
- print remediation: `bash scripts/enforcement/install-hooks.sh`
### 8. Surface drift activity in the compliance dashboard
Update `scripts/enforcement/compliance-dashboard.sh` to summarize `logs/hooks/stage-prompt-drift-events.jsonl`.
Include:
- whether the log file exists
- total event count
- counts by verdict (`pass`, `warning`, `fail`, `skip`, `unknown`)
- latest event summary
Important finding:
- do not let the dashboard fail merely because there were zero commits in the window; handle the no-commit case separately and still print drift-event status.
### 9. Auto-generate non-destructive evidence stubs for blocked work items
Extend the Python checker with `--write-evidence-stubs` support.
Useful pattern:
- detect whether the work item is blocked by checking `.Codex/work-queue/{blocked,pending,working,done}` records
- if blocked and no replacement evidence exists, create:
- `.Codex/work-queue/assets/<work-item>/evidence/stage-prompt-drift-summary.stub.md`
- never overwrite an existing stub
- if a stub already exists, reuse/report it instead of replacing it
Stub content should include:
- work item id
- missing prompt paths
- blocked context / blocker lines from the work item record
- next actions telling the user to replace the stub with a human-authored summary
## Test strategy
Write tests before or with the implementation.
### Audit/report tests
Verify:
- `stage_prompt_packages` is emitted
- package entries include evidence files
- markdown includes the stage prompt package index
### Drift checker tests
Verify:
- missing prompt + no evidence => flagged
- missing prompt + evidence => not flagged
- diff filtering only flags deleted prompt files in current change set
- added evidence in same diff suppresses the failure
- CLI returns nonzero with `--fail-on-issues`
### Hook installer tests
Verify:
- installer appends the drift guard to `.git/hooks/pre-push`
- dry-run does not modify the hook
## Verification commands
```bash
uv run pytest tests/analysis/test_claude_session_ecosystem_audit.py \
tests/analysis/test_stage_prompt_drift_check.py \
tests/enforcement/test_require_stage_prompt_drift.py \
tests/enforcement/test_install_hooks_stage_prompt_drift.py -q
uv run python scripts/analysis/stage_prompt_drift_check.py \
--base-ref origin/main \
--head-ref HEAD \
--fail-on-issues
bash scripts/enforcement/install-hooks.sh --dry-run
bash scripts/enforcement/require-stage-prompt-drift.sh
```
## Pitfalls
- Do not gate on total historical drift; it will fail immediately in legacy repos
- `origin/main` may not exist in shallow/local-only clones; skip cleanly instead of hard failing
- A surviving evidence package with no prompt files is not necessarily drift; treat evidence as a valid replacement path when intended
- Use full-history checkout in CI (`fetch-depth: 0`) so `origin/main...HEAD` diffing works reliably
- Keep the markdown summary human-readable; reviewers need to see exactly which work item and prompt paths caused the failure
## Reusable outcome
This pattern works for any repo with ephemeral/generated prompt assets:
1. audit historical references
2. generate package index
3. define valid replacement evidence
4. fail only on newly introduced drift in CI and pre-pushRelated Skills
plan-review-prompt-refresh-after-plan-edits
Refresh reviewer prompt files from the latest on-disk plan before every adversarial re-review. Prevents Codex/Gemini from critiquing stale plan text after local edits.
staged-issue-tree-creation-with-deduplication
Pattern for creating hierarchical GitHub issue trees from phased project plans while checking for duplicate/overlapping issues
label-driven-prompt-generation-architecture
Pattern for building automation scripts that classify GitHub issues into prompt templates using label-based routing and extract contextual data for batch processing
agent-team-prompt-generation
Create self-contained execution prompts that define multi-role workflows for Codex sessions without external dependencies
plan-review-rerun-cli-drift-and-git-contention
Recover iterative plan-review work when provider CLI wrappers drift, fresh reviews expose stale governance text, and active git pre-push processes make committing unsafe.
plan-review-fanout-runner-drift-recovery
Recover plan-review waves when provider wrapper/cwd/date drift creates false MAJOR or UNAVAILABLE artifacts instead of substantive review.
plan-review-artifact-authority-and-approval-drift
Keep iterative plan-review artifacts truthful when external reruns overtake self-reviews or stale approval signals remain on older revisions.
overnight-worktree-uv-warmup-and-log-path-guardrails
Prevent false stalls and missing-log failures in overnight Codex worktree batches by pre-warming uv environments, using exact log-path directory creation, and interpreting buffered logs correctly.
overnight-pre-plan-review-wave-artifact-drift
Run overnight planning-only waves for issues before status:plan-review, and reconcile cases where GitHub state advances but plan/review artifacts land in a sandbox or remote branch instead of the active local worktree.
overnight-plan-wave-artifact-drift-reconciliation
Reconcile overnight planning waves when Codex workers move GitHub issues to status:plan-review but local artifacts are missing, split across sandbox worktrees, or only present on a pushed remote branch.
overnight-plan-artifact-placement-drift-reconciliation
Reconcile overnight planning waves where Codex workers advance GitHub issue state but the expected plan/review artifacts are missing from the designated external worktree because the worker wrote from a sandbox/in-repo worktree and pushed directly to the branch.
live-writer-branch-cleanup-guard
Guardrails for multi-repo sync and branch cleanup when workspace-hub or another shared repo has active writer sessions, worktree-backed branches, or unrelated-history branches.