Skip to content

feat: add implementation-shape guardrail lens - #3

Open
zhouyuanxinand wants to merge 4 commits into
tt-a1i:mainfrom
zhouyuanxinand:codex/upstream-defensive-and-harness-support
Open

feat: add implementation-shape guardrail lens#3
zhouyuanxinand wants to merge 4 commits into
tt-a1i:mainfrom
zhouyuanxinand:codex/upstream-defensive-and-harness-support

Conversation

@zhouyuanxinand

@zhouyuanxinand zhouyuanxinand commented Sep 2, 2026

Copy link
Copy Markdown

Summary

Closes #2.

This adds one focused implementation-shape guardrail lens to the existing $simplify-codebase workflow.

  • recognize tests, source scans, inventories, import bans, and build/CI checks that preserve obsolete implementation shape rather than observable behavior
  • treat AI authorship and defensive labels only as discovery hints, never as deletion evidence
  • retain guards that protect business outcomes, APIs, security, persistence, concurrency, deployment acceptance, integration behavior, or active engineering policy
  • reuse the existing proof record, execution sequence, validation rings, and operation receipt
  • require per-artifact deletion accounting in the existing receipt, including original purpose, removal evidence, surviving behavior, reintroduction condition, and verification
  • document the lens and a read-only audit example in both READMEs

The earlier parallel defensive-cleanup workflow and harness-portability implementation have been removed from this PR. Harness compatibility can be proposed independently.

Behavioral validation

An independent Skill run exercised a small Node.js fixture containing pricing and authorization behavior, a deployment check, one dead helper, and a test/script pair that enforced exact source layout and spelling.

  • Ambiguous request: selected Survey mode, made no edits, ranked the shape guard separately from the dead helper, and retained business, authorization, and deployment guards.
  • Focused change: removed only tests/layout.guard.test.js, scripts/check-layout.js, and check:layout; baseline was 4/4 tests plus layout/deployment checks, and the result passed all 3 surviving behavior tests plus deployment verification. The receipt accounted for every deleted artifact.
  • Mixed objectives: maintained separate proof records and cut boundaries for the shape guard and dead helper; removed 22 lines across 4 files with no replacement machinery; residue, syntax, behavior, deployment, and diff checks passed.

Mechanical validation

  • Skill structure/frontmatter validation: passed
  • internal Markdown link validation: passed
  • stale parallel-workflow and harness-reference scan: clean
  • git diff --check upstream/main...HEAD: passed

@tt-a1i tt-a1i left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution. The problem is real, especially for tests and static checks that preserve an obsolete implementation shape rather than an active contract. However, I do not think this should become a second top-level objective based on whether a change was AI-generated.

AI provenance is usually neither observable nor relevant to deletion safety. The existing Support drag, Boundary theater, and Feature fossil lenses already cover most of this surface. A smaller implementation-shape guardrail lens, reusing the existing proof record and execution workflow, would preserve the value without adding a parallel decision model.

Before merging, this also needs behavioral validation for the new deletion path. The current PR adds structural checks only. Please add scenarios covering an ambiguous request, a removable implementation-shape guard, a retained business/security/deployment guard, separation of mixed objectives, and a complete deletion receipt.

The portability portion also needs revision:

  • the documented python scripts/verify_harness_contract.py command fails in a common macOS environment where only python3 is available;
  • the Codex paths are stale: current official documentation uses $HOME/.agents/skills and repository .agents/skills;
  • the custom parser can report valid for invalid YAML and allows relative links to escape the package root;
  • agents/openai.yaml is described as optional but enforced as mandatory;
  • directory-name verification follows symlinks and can validate the target name instead of the installed alias;
  • the hand-written seven-harness matrix and 102-line validator add ongoing compatibility debt without tests or CI.

There are also routing inconsistencies: category definitions are loaded only after the category has supposedly been selected, selected-objective-only references can conflict with the shared investigation/lifecycle rules, and the default OpenAI prompt always asks for an objective even when the user intent is already clear. The defensive proof and delivery reference also duplicates the existing proof record, execution sequence, and receipt.

I recommend splitting the harness compatibility work into a separate PR, reducing defensive cleanup to one focused implementation-shape-guardrail lens under ordinary simplification, reusing the current evidence model, and adding behavior-level fixtures before reconsidering the change.

@zhouyuanxinand zhouyuanxinand changed the title feat: add AI defensive-layer cleanup mode and harness guidance feat: add implementation-shape guardrail lens Sep 2, 2026
@zhouyuanxinand

Copy link
Copy Markdown
Author

Addressed the requested changes in 8e45841, ec9eee2, and 6e4fdb9:

  • removed the parallel AI-defensive objective, category/proof/delivery references, custom validator, and harness matrix from this PR;
  • reduced the feature to one implementation-shape guardrail lens under the existing simplification workflow;
  • made AI provenance non-evidence and explicitly retained business, API, security, persistence, concurrency, deployment, integration, and policy guards;
  • reused the existing proof record, execution flow, validation rings, and operation receipt;
  • added artifact-level purpose/evidence/surviving-behavior/reintroduction/verification requirements to that receipt;
  • added behavior validation for ambiguous routing, removable shape guards, retained live guards, mixed-objective separation, and complete receipts;
  • left agents/openai.yaml unchanged and removed all harness-portability claims from the final diff.

The PR title and body now reflect the narrowed scope. @tt-a1i, please re-review when convenient.

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.

feat: add AI defensive-layer cleanup mode and portable harness guidance

2 participants