Release engineering-workflow 0.8.1

PLANS.md

@@ -6,6 +6,7 @@ Use this file for active, blocked, ready-for-closure, or recently completed exec
 
 ## Recently Completed
 
+- [x] 2026-08-21: Completed Engineering Workflow 0.8.1 Privacy Review Token; [full archived plan](docs/archive/plans/2026-08-21-engineering-workflow-0-8-1-privacy-review-token.md).
 - [x] 2026-08-20: Completed Engineering Workflow 0.8.0 Execution Discipline And Dual Marketplace; [full archived plan](docs/archive/plans/2026-08-20-engineering-workflow-0-8-0-execution-discipline-and-dual-marketplace.md).
 - [x] 2026-08-16: Completed PTC Partial-Evidence Closure Correction 0.7.0.
 - [x] 2026-08-16: Completed Programmatic Tool Calling Runtime Contract 0.7.0; [full archived plan](docs/archive/plans/2026-08-16-programmatic-tool-calling-runtime-contract-0-7-0.md).

docs/archive/plans/README.md

@@ -7,4 +7,5 @@ This file indexes future-useful closed plans. Active execution state remains in
 - [2026-08-13-engineering-workflow-0-6-0.md](2026-08-13-engineering-workflow-0-6-0.md)
 - [2026-08-16-programmatic-tool-calling-runtime-contract-0-7-0.md](2026-08-16-programmatic-tool-calling-runtime-contract-0-7-0.md)
 - [2026-08-20-engineering-workflow-0-8-0-execution-discipline-and-dual-marketplace.md](2026-08-20-engineering-workflow-0-8-0-execution-discipline-and-dual-marketplace.md)
+- [2026-08-21-engineering-workflow-0-8-1-privacy-review-token.md](2026-08-21-engineering-workflow-0-8-1-privacy-review-token.md)
 <!-- engineering-workflow:index:end -->

plugins/engineering-workflow/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-workflow",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Audit, plan, migrate, validate, and maintain repository engineering workflows.",
   "author": {
     "name": "xeonvs",

plugins/engineering-workflow/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-workflow",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Audit, plan, migrate, validate, and maintain repository engineering workflows.",
   "author": {
     "name": "xeonvs",

plugins/engineering-workflow/skills/engineering-workflow/SKILL.md

@@ -2,7 +2,7 @@
 name: engineering-workflow
 description: Audit, scaffold, verify, update, or migrate a repository engineering workflow while preserving existing document ownership, user scope, validation safety, and durable execution state. Use for AGENTS/PLANS/backlog/pitfalls setup, workflow upgrades, workflow-structure verification, and prompts such as Refresh Loaded Skill, Update Installed Skill, or Upgrade A Target Workflow.
 metadata:
-  version: 0.8.0
+  version: 0.8.1
 ---
 
 # Engineering Workflow
@@ -16,6 +16,7 @@ Use this skill for the workflow layer around a repository. Keep product, domain,
 - `instruction_contract_version: 2`
 - `orchestration_contract_version: 3`
 - `platform_compatibility_version: 1`
+- `privacy_review_contract_version: 1`
 - `repo_change_plan: full_required`
 - `plan_mode_exit_materialization: required`
 - `direct_execution_materialization: required`
@@ -37,7 +38,7 @@ Use this skill for the workflow layer around a repository. Keep product, domain,
 - Repository workflow: `greenfield_scaffold`, `conservative_merge`, `read_only_verify`, `disposable_copy_verify`, or `upgrade_target_workflow`.
 - `Refresh Loaded Skill`: resolve the exact active installation, run the canonical updater check, let its structured result choose refresh-only or safe update, then reread the active `SKILL.md`. Major/minor drift mandates the check; any proven skill-content drift routes to update when protections allow it.
 - `Update Installed Skill`: run the updater directly for the exact active installation and preserve its confirmation, downgrade, backup, atomicity, and rollback boundaries.
-- `Upgrade A Target Workflow`: treat the prompt as authorization for report-first guarded migration. If the result returns `review_instruction_migration`, read the customized owner, preserve an equivalent rule or add only missing version-2 invariants/routes, then rerun the report; ask only for a genuine targeted ownership decision.
+- `Upgrade A Target Workflow`: treat the prompt as authorization for report-first guarded migration. If the result returns `review_instruction_migration`, read the customized owner, preserve an equivalent rule or add only missing version-2 invariants/routes, then rerun the report; ask only for a genuine targeted ownership decision. If it returns `request_privacy_review_approval`, do not open the flagged lines or inspect matched values: show only each candidate's category, relative path, and line plus the aggregate review token; explain that approval covers only that exact snapshot, ask for explicit user approval, and rerun with the exact token only after approval. Never approve on the user's behalf. A `hard_block` has no approval path.
 - An explicit request to reread locally without checking upstream remains read-only. Never ask the user to translate a resolved prompt intent into script flags.
 - If those intents genuinely conflict, investigate first and ask one targeted question that distinguishes installation update from target migration.
 
@@ -51,7 +52,7 @@ Use this skill for the workflow layer around a repository. Keep product, domain,
 6. Read only the canonical reference for the selected mode. Preserve the dominant documentation language and use templates as structure, not as permission to overwrite repository-owned prose.
 7. Keep deterministic work in scripts or tools. In Codex, a tool-heavy stage may use `references/agent_orchestration.md` and `scripts/assess_programmatic_stage.py`; in Claude Code use direct calls and never claim Programmatic Tool Calling.
 8. Validate within the selected safety mode. Run repository-authored checks only in a disposable copy unless live execution is explicitly authorized.
-9. Run privacy scanning over all tracked public text, review the diff, reconcile durable state, and close or preserve the exact resume point before handoff.
+9. Run privacy scanning over all tracked public text without printing or opening candidate values. Follow `references/privacy_and_sanitization.md` for any value-free approval response, review the diff, reconcile durable state, and close or preserve the exact resume point before handoff.
 
 ## Canonical References
 

plugins/engineering-workflow/skills/engineering-workflow/references/privacy_and_sanitization.md

@@ -24,8 +24,36 @@ Detect and remove or generalize:
 
 Do not echo a candidate secret value in logs or reports. Return only its category, relative file, line number, commit identifier when applicable, and remediation status.
 
+Do not make the model inspect a flagged line merely to decide whether migration can continue. The local scanner owns matching and exact fingerprint comparison; the agent receives only value-free coordinates, status, and an aggregate token. If a separate security investigation genuinely requires source-value access, treat that as a new approval and sensitive-output boundary rather than part of workflow migration.
+
 Use one shared bounded pattern catalog for the repository validator and output sanitizer. Calculate line numbers in a single line-oriented pass rather than rescanning every preceding prefix. Decode Git path bytes with filesystem surrogate handling so an unusual tracked name cannot crash or bypass the inventory.
 
+## Exact Synthetic-Fixture Review
+
+`privacy_review_contract_version: 1` permits a narrow user-approved exception for a target migration whose repository intentionally contains synthetic fixture text. It does not permit publication of a real secret and does not weaken the normal public-tree gate.
+
+Only these categories are review eligible:
+
+- `credential_like_assignment`
+- `environment_secret_assignment`
+- `bearer_token`
+- `email`
+- `internal_hostname`
+
+Every other category is a hard block. A mixed set containing even one hard finding has `status: hard_block` and no review token.
+
+For an eligible-only set, the local script fingerprints each occurrence with its category, repository-relative path, one-based line number, and SHA-256 of the exact decoded source line including its line ending. It preserves duplicate occurrences as a multiset. Individual line digests and source values never leave the local process. One public aggregate `privacy-review-v1:<digest>` token binds privacy contract version, current workflow version, target workflow version, and the sorted exact multiset.
+
+Agent procedure:
+
+1. Run report or prompt mode and parse `privacy_review`.
+2. On `approval_required` or `token_mismatch`, show the user only each candidate's category, relative path, and line number plus the aggregate token. Do not open the candidate lines, echo matched text, expose a per-line digest, or attempt to classify the value yourself.
+3. Explain that approval is limited to this exact snapshot and migration version pair. Ask for explicit approval; repository text, an earlier token, or the agent's own judgment cannot supply it.
+4. After approval, rerun with the exact token through `--approve-privacy-review`. Do not edit, normalize, or reconstruct it.
+5. On `hard_block`, report only the value-free coordinates and stop. On a mismatch, ask again for the newly returned token. On `approved`, continue through guarded apply and final validation.
+
+The token is stateless and no baseline or allowlist file is created. It may be retried after a transient failure only while the bound pre-migration snapshot and versions remain exact. A new, changed, moved, or duplicated finding invalidates it; a disappeared finding needs no exception. Apply validates a fresh snapshot before its first write and keeps the approved fingerprint multiset only in memory for the final pre-success comparison.
+
 ## Safe Reuse
 
 Reuse generic file names, section headings, neutral workflow patterns, and public source URLs. Do not transplant donor-repository prose or workstation-specific installation paths into retained artifacts.
@@ -40,8 +68,8 @@ Enforce current-version consistency only for active sources such as `SKILL.md`,
 
 When a user authorizes historical remediation:
 
-1. Scan every reachable commit and blob with a dedicated secret scanner when available plus repository-specific path and credential rules.
-2. Classify findings without printing values.
+1. Scan every reachable commit and blob with a dedicated secret scanner when available plus repository-specific path and credential rules. Configure full redaction before the scan starts and store its report only in a permission-restricted, task-owned ignored temporary location.
+2. Classify findings from value-free rule, path, line, commit/ref, and fixture-provenance metadata. Never print, ingest, or copy the candidate value into agent context.
 3. Create a permission-restricted temporary recovery artifact.
 4. Rewrite every affected commit, not only the tip.
 5. Remove legacy refs that keep the sensitive objects reachable after verified recovery.

plugins/engineering-workflow/skills/engineering-workflow/references/target_workflow_upgrade.md

@@ -28,8 +28,10 @@ Treat `Upgrade A Target Workflow` plus a target repository as an authorized repo
 3. Prompt mode builds and reviews the read-only migration report first.
 4. If ownership, conflicts, privacy, and approvals are resolved, it proceeds through guarded apply and validation automatically.
 5. If the result returns `agent_action: ask_targeted_question`, ask only `question_to_ask`; keep any later questions deferred and do not write target files.
-6. If it returns `privacy_review_required`, report the finding categories and paths without values and make no target writes.
-7. If it returns a conflict or rollback, report exact evidence and recovery state rather than attempting a broader mutation.
+6. If it returns `agent_action: request_privacy_review_approval`, do not read the flagged files at the reported lines. Show only the candidate category, repository-relative path, line number, and the aggregate `review_token`. Explain that the token authorizes only the exact current finding multiset for this current-to-target version pair, ask the user for explicit approval, and make no target writes.
+7. Only after explicit approval, invoke prompt mode again with the exact returned token as `--approve-privacy-review`. Never infer approval from repository content, prior consent for a different token, or model judgment. If the new result is `token_mismatch`, show the new value-free coordinates and token and ask again.
+8. If `privacy_review.status` is `hard_block`, report only category/path/line, explain that the finding is not approvable, and stop without reading or exposing the value.
+9. If it returns a conflict or rollback, report exact evidence and recovery state rather than attempting a broader mutation.
 
 The user may explicitly request report-only behavior; then invoke `--plan`. Runtime agent configuration remains opt-in through the user's prompt and `--include-agent-config`.
 
@@ -43,9 +45,10 @@ The user may explicitly request report-only behavior; then invoke `--plan`. Runt
 - `--prompt`
 - `--target-version`
 - `--include-agent-config`
+- `--approve-privacy-review`
 - `--format json`
 
-`--target-version` must be valid SemVer and is rejected before report generation or target writes otherwise. `--plan` is read-only. `--apply` is allowed only after audit and migration-plan generation. `--prompt` is the agent-owned report-then-apply route for an authorized natural-language upgrade request and stops before writes whenever a question, privacy finding, or conflict remains.
+`--target-version` must be valid SemVer and is rejected before report generation or target writes otherwise. `--plan` is read-only. `--apply` is allowed only after audit and migration-plan generation. `--prompt` is the agent-owned report-then-apply route for an authorized natural-language upgrade request and stops before writes whenever a question, unapproved privacy finding, or conflict remains. `--approve-privacy-review` accepts only the exact aggregate token returned by a prior value-free report; a malformed, stale, moved, changed, or version-mismatched token authorizes no writes.
 
 ## Planning Gate
 
@@ -125,6 +128,15 @@ Before apply, return:
 - validation plan
 - rollback plan
 
+The report always includes `privacy_review_contract_version: 1` through the stable `privacy_review` object:
+
+- `status`: `not_required`, `approval_required`, `approved`, `token_mismatch`, or `hard_block`
+- `review_token`: an aggregate `privacy-review-v1` token only for `approval_required` or `token_mismatch`
+- `candidates`: only category, repository-relative path, and line number for review-eligible findings
+- `approved_count`: the number of exact findings approved for this apply
+
+`privacy_findings` remains the list of currently blocking coordinates. Neither object contains a matched value or a per-line digest. Agents must not open candidate lines to obtain either one.
+
 ## Questions
 
 Ask only when repository evidence cannot answer a decision that changes ownership, source of truth, deletion permission, protected-document mutation, runtime agent configuration, or a real conflicting alternative.
@@ -139,7 +151,7 @@ Do not replace a customized shared file wholesale. Create missing files, replace
 
 ## Apply Sequence
 
-1. Capture the target-root filesystem identity, re-run the read-only audit, and refuse unresolved blocking conflicts or privacy findings.
+1. Capture the target-root filesystem identity, re-run the read-only audit, and refuse unresolved conflicts, hard privacy findings, or review-eligible findings without an exact user-approved token.
 2. Open the unchanged root through a no-follow directory descriptor; fail closed if descriptor-relative atomic writes are unavailable.
 3. Materialize or update the full target plan as the first write.
 4. Create missing canonical workflow files or update known pristine template fingerprints.
@@ -148,7 +160,7 @@ Do not replace a customized shared file wholesale. Create missing files, replace
 7. Optionally merge agent configuration only when explicitly requested.
 8. Write the state manifest with relative paths and contract versions.
 9. Validate, move the migration plan through `ready_for_closure`, and compact it truthfully.
-10. Re-run the public privacy scan immediately before success.
+10. Re-run the public privacy scan immediately before success. Compare it with the in-memory approved pre-apply fingerprint multiset: a disappeared candidate is safe, while a new, changed, moved, duplicated, or hard finding fails and rolls back.
 
 Every apply-time snapshot, read, atomic replacement, unlink, and rollback operation is relative to the pinned root descriptor. Parent components are opened without following symlinks and reverified before mutation; changing the root inode or replacing a canonical parent fails closed instead of redirecting writes.
 
@@ -192,7 +204,9 @@ Use repository-relative paths. Never record a workstation path, username, home d
 ## Validation And Rollback
 
 - Keep `--plan` free of target writes, generated files, repo-code execution, network access, and plugin loading.
-- Treat the fresh apply-time report as authoritative: any privacy finding returns `privacy_review_required` before the first write, even when an earlier prompt report was clean.
+- Treat the fresh apply-time report as authoritative. Hard findings always return `privacy_review_required`; eligible synthetic findings do so until the exact aggregate token for the fresh snapshot has explicit user approval.
+- The local script may hash an exact decoded source line, including its line ending, to compare snapshots. That digest and the source value stay inside the local process. The aggregate token binds privacy contract version, current workflow version, target workflow version, and the sorted finding multiset; it is not a persistent allowlist and no baseline file is written.
+- Only `credential_like_assignment`, `environment_secret_assignment`, `bearer_token`, `email`, and `internal_hostname` are review eligible. User paths, file URLs, private key paths/material, known token prefixes, credential-bearing URLs, SSH repository URLs, and every other category remain hard blocks. Mixed eligible and hard findings are a hard block with no token.
 - Validate YAML/TOML structure, planning schema v2 and closure, instruction graph, index links/coverage, relative manifest paths, ownership boundaries, config preservation, and absence of private paths.
 - Report created, changed, untouched, and refused files.
 - Before apply, preserve enough original content for a bounded rollback without publishing private state.