diff --git a/README.en.md b/README.en.md index c7a2f3e..10fc1cb 100644 --- a/README.en.md +++ b/README.en.md @@ -23,6 +23,8 @@ Codebase entropy is rarely just an unused function. It can be duplicated state, Static analysis can surface leads, but it cannot prove a deletion safe by itself. This Skill follows runtime consumers, dynamic registration, persisted formats, public interfaces, design history, and verification boundaries before classifying a candidate as remove, merge, retain, or unresolved. +It also recognizes implementation-shape guardrails: tests, static scans, inventories, and build/CI checks that constrain directory layout, literal source text, private defaults, exact component counts, or a historical implementation identity without protecting observable behavior. AI authorship is not removal evidence; business, API, security, persistence, concurrency, real deployment, integration behavior, and active engineering policy guards remain ordinary live contracts. + > **Core principle:** deleted lines are an outcome. The durable gain is deleting a fact, state, contract, or concept that no longer needs maintenance. ## How it works @@ -100,6 +102,12 @@ Use $simplify-codebase to remove one high-confidence source of accidental comple Use $simplify-codebase to verify and integrate the simplification findings from this PR. Preserve evidence, not finding counts. ``` +### Investigate implementation-shape guardrails + +```text +Use $simplify-codebase to audit tests, build/CI, and static checks that only preserve an obsolete implementation shape. Do not modify files, and retain checks that still protect business, security, deployment, integration behavior, or active engineering policy. +``` + ### Add a visual companion ```text @@ -138,6 +146,8 @@ Survey follows Locate, Trace, Cut, and Decide; Change follows Before, Cut, After │ ├── examples/ # Survey and Change inputs │ └── test/ # Contract, route, and artifact tests ├── docs/validation.md # Behavioral validation evidence +├── docs/fixtures/implementation-shape-guardrail/ +│ # Reproducible guardrail fixture, patches, and receipts ├── docs/visual-report-example.md └── assets/hero.png # Original hero artwork ``` diff --git a/README.md b/README.md index c44c668..b36c6c6 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ 静态检查可以提供线索,但不能单独证明一项删除是安全的。这个 Skill 会继续追踪运行时消费者、动态注册、持久化格式、公共接口、历史决策与验证边界,再决定应该删除、合并、保留,还是标记为暂时无法判断。 +它也会识别“实现形态守卫”:只约束目录结构、源文本、私有默认值、固定组件数量或历史实现身份,却不再保护可观察行为的测试、静态扫描、清单和构建/CI 检查。AI 是否生成过这些代码不是删除证据;业务、API、安全、持久化、并发、真实部署、集成行为和仍生效的工程策略守卫仍按普通契约保留。 + > **核心原则:** 删除代码行只是结果。真正的收益是删除一个需要长期维护的事实、状态、契约或概念。 ## 工作方式 @@ -98,6 +100,12 @@ git clone https://github.com/tt-a1i/simplify-codebase.git \ 使用 $simplify-codebase 复核并整合这个 PR 中的简化建议。保留证据,不保留候选数量。 ``` +### 调查实现形态守卫 + +```text +使用 $simplify-codebase 审计测试、构建/CI 和静态检查里只保护旧实现形态的守卫。不要修改文件,并保留仍然保护业务、安全、部署、集成行为或仍生效工程策略的检查。 +``` + ### 生成可视化伴随报告 ```text @@ -136,6 +144,8 @@ Survey 按“定位、路径、删除边界、判断”组织,Change 按“变 │ ├── examples/ # Survey 与 Change 输入示例 │ └── test/ # 契约、路径与产物测试 ├── docs/validation.md # 行为验证与质量证据 +├── docs/fixtures/implementation-shape-guardrail/ +│ # 实现形态守卫的可复现 fixture、补丁与回执 ├── docs/visual-report-example.md └── assets/hero.png # 原创 Hero 视觉 ``` diff --git a/SKILL.md b/SKILL.md index 38144f3..367c12e 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,6 +1,6 @@ --- name: simplify-codebase -description: Simplification audit or authorized codebase simplification whose stated objective is to remove accidental complexity. Use for evidence-backed deletion or consolidation of dead code, duplicate state, redundant APIs or layers, ownerless abstractions, obsolete compatibility or design records, and over-engineering in any language; also use for 代码简化 or 熵回收. Do not use for general code review, onboarding, style-only refactoring, or performance tuning. +description: Simplification audit or authorized codebase simplification whose stated objective is to remove accidental complexity. Use for evidence-backed deletion or consolidation of dead code, duplicate state, redundant APIs or layers, ownerless abstractions, obsolete compatibility or design records, over-engineering, and tests or checks that preserve an obsolete implementation shape; also use for 代码简化、熵回收、实现形态守卫审计或清理. Do not use for general code review, onboarding, style-only refactoring, or performance tuning. --- # Simplify Codebase @@ -14,6 +14,8 @@ First choose the authority mode: - **Survey** for simplification audit, investigation, or candidate-finding requests. Remain read-only and return ranked evidence. - **Change** for explicit simplify, remove, consolidate, refactor, or repository-documentation edit requests. Prove each cut, implement it within the authorized scope, and validate the surviving contract. +A request that only mentions defensive, anti-regression, or AI-generated guardrails without an explicit edit verb or other change authority remains Survey. AI provenance is not deletion evidence and does not lower the proof burden. When a request combines an implementation-shape guardrail with another simplification, keep separate proof records and cut boundaries even when they are validated in the same run. + Then choose the coverage scope: - **Focused** when the user names a subsystem, symbol, state machine, dependency, or suspected duplication. Cover that boundary thoroughly before expanding outward. @@ -36,6 +38,8 @@ The contract map is complete when all in-scope entrypoints and authority boundar For every Broad engagement, and for Focused work involving dynamic architecture or dependency substitution, read [investigation.md](references/investigation.md). Build a coverage map before ranking findings; the first plausible deletion must not end the survey. +Also read [investigation.md](references/investigation.md) when tests, source scans, inventories, import bans, or build/CI checks may preserve an implementation shape rather than observable behavior. Apply its implementation-shape guardrail lens within the ordinary proof workflow. + For concurrency, cancellation, readiness, cleanup, defensive copies, validation, authorization, security isolation, accessibility, data-loss prevention, or cross-process data, also read [boundaries-and-lifecycle.md](references/boundaries-and-lifecycle.md). Use repository-native search, compiler and linter output, dependency metadata, and history as discovery instruments. Treat their findings as leads until runtime consumers and contracts have been examined. diff --git a/docs/fixtures/implementation-shape-guardrail/README.md b/docs/fixtures/implementation-shape-guardrail/README.md new file mode 100644 index 0000000..13e8f0a --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/README.md @@ -0,0 +1,161 @@ +# Implementation-shape guardrail evidence + +This directory makes the implementation-shape validation reported in [`docs/validation.md`](../../validation.md) auditable without adding a runner or validation framework. `baseline/` is the exact dependency-free Node.js fixture used by the independent Skill runs. [`focused-change.patch`](./focused-change.patch) and [`mixed-change.patch`](./mixed-change.patch) record the two authorized outcomes. + +## Fixture contract + +The fixture contains three distinct kinds of evidence: + +- `tests/business.test.js` checks pricing, invalid-quantity handling, and authorization behavior; +- `scripts/deploy-check.js` exercises pricing and authorization as a deployment acceptance check; +- `tests/layout.guard.test.js` and `scripts/check-layout.js` both require the exact `src/catalog.js` filename and the literal spelling `function priceFor`, but own no observable behavior; +- the unexported `legacyLabel` helper has no fixture consumer and is a separate dead-code candidate. + +The baseline has no package dependencies. The recorded commands below were rechecked on 2026-09-05 with Node.js 20.15.0 and npm 10.7.0 on Windows. Use `npm` instead of `npm.cmd` on systems where that is the installed executable. + +## Independent Skill runs + +The runs used clean copies of `baseline/` and Skill head `6e4fdb9a24a4f0880d67c4c983633b19d10e2ebe`. + +### Ambiguous request + +```text +Use $simplify-codebase. There may be defensive or AI-generated guardrails in this repository. What should we do? +``` + +Observed result: Survey mode, no edits. The run ranked the layout guardrail and `legacyLabel` separately, retained quantity validation, authorization, the three business tests, and the deployment check, and recorded external CI invocation of `check:layout` as the only unresolved consumer risk. + +### Focused change + +```text +Use $simplify-codebase in Change mode. Remove only the proven implementation-shape guardrail: the layout test, layout-check script, and its package script entry. Preserve legacyLabel as a separate out-of-scope candidate, and retain all business, authorization, and deployment behavior. Validate the result and provide the complete operation receipt required by the skill. +``` + +Observed result: [`focused-change.patch`](./focused-change.patch), 18 deletions across the three authorized artifacts, no replacement machinery, 3/3 surviving tests, and a passing deployment check. The complete receipt appears below. + +### Mixed objectives + +```text +Use $simplify-codebase in Change mode. Remove both the implementation-shape layout guardrail and the separate dead legacyLabel helper. Keep them as distinct proof records and cut boundaries, validate each surviving contract, retain business, authorization, and deployment behavior, and provide one operation receipt that keeps the two cuts separate. +``` + +Observed result: [`mixed-change.patch`](./mixed-change.patch), 22 deletions across four files, no replacement machinery, an empty residue search, passing syntax and diff checks, 3/3 surviving tests, and a passing deployment check. The receipt below keeps Finding S1 and Finding S2 separate. + +## Exact command evidence + +Run these commands from the repository root. Each patch is reversed after its checks so `baseline/` remains reusable. + +### Baseline + +```powershell +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline test +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline run check:layout +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline run deploy:check +``` + +Observed result: + +```text +tests 4 +pass 4 +fail 0 +check:layout: exit 0 +deploy:check: exit 0 +``` + +### Focused-change commands + +```powershell +git apply --check docs/fixtures/implementation-shape-guardrail/focused-change.patch +git apply docs/fixtures/implementation-shape-guardrail/focused-change.patch +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline test +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline run deploy:check +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline run +rg -n 'check:layout|check-layout|layout\.guard|historical implementation shape' docs/fixtures/implementation-shape-guardrail/baseline +git diff --check -- docs/fixtures/implementation-shape-guardrail/baseline +git diff --stat -- docs/fixtures/implementation-shape-guardrail/baseline +git apply -R docs/fixtures/implementation-shape-guardrail/focused-change.patch +``` + +Observed result: + +```text +tests 3 +pass 3 +fail 0 +deploy:check: exit 0 +npm run: test and deploy:check only +residue search: no matches +diff check: exit 0 +3 files changed, 18 deletions(-) +``` + +### Mixed change + +```powershell +git apply --check docs/fixtures/implementation-shape-guardrail/mixed-change.patch +git apply docs/fixtures/implementation-shape-guardrail/mixed-change.patch +node --check docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js +node --check docs/fixtures/implementation-shape-guardrail/baseline/scripts/deploy-check.js +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline test +npm.cmd --prefix docs/fixtures/implementation-shape-guardrail/baseline run deploy:check +rg -n 'legacyLabel|check:layout|check-layout|layout\.guard|historical implementation shape' docs/fixtures/implementation-shape-guardrail/baseline +git diff --check -- docs/fixtures/implementation-shape-guardrail/baseline +git diff --stat -- docs/fixtures/implementation-shape-guardrail/baseline +git apply -R docs/fixtures/implementation-shape-guardrail/mixed-change.patch +``` + +Observed result: + +```text +syntax checks: exit 0 +tests 3 +pass 3 +fail 0 +deploy:check: exit 0 +residue search: no matches +diff check: exit 0 +4 files changed, 22 deletions(-) +``` + +## Focused-change operation receipt + +```text +Scope: Finding S1, the layout implementation-shape guardrail only. +Baseline: 4/4 tests, check:layout, and deploy:check passed. +Retired obligation: exact source filename, source-directory cardinality, and literal function-spelling enforcement. +Realized net effect: 3 artifacts changed, 18 lines deleted, no dependency, replacement, or migration machinery added. +Behavior: pricing, invalid-quantity handling, authorization, exports, deployment acceptance, and legacyLabel were preserved; only layout enforcement was intentionally removed. +Residual risk: an external CI consumer of check:layout cannot be disproved from this private fixture; no in-fixture consumer exists. +Retained candidates: legacyLabel remained unchanged and explicitly out of scope. +Undo: git apply -R docs/fixtures/implementation-shape-guardrail/focused-change.patch +``` + +Artifact accounting: + +| Artifact | Original check | Decisive removal evidence | Surviving behavior | Reintroduction condition | Verification | +| --- | --- | --- | --- | --- | --- | +| `tests/layout.guard.test.js` | Required the literal `function priceFor` text and exactly one file named `src/catalog.js`. | Removing the test changes no runtime path; the three behavior tests and deployment check still exercise pricing and authorization. | Pricing, invalid-quantity rejection, authorization, exports, and deployment acceptance. | Restore only if a current documented engineering or deployment policy makes the filename, file count, or spelling an active contract. | 3/3 tests and `deploy:check` passed; residue and diff checks were clean. | +| `scripts/check-layout.js` | Duplicated the test's exact filename, file-count, and literal-source assertions. | It had no runtime consumer and added no behavior beyond the removable test. | The same business, authorization, and deployment behavior. | Restore only for the same active, documented layout policy. | The script was absent, the remaining npm scripts were `test` and `deploy:check`, and both passed. | +| `package.json` section `check:layout` | Exposed the duplicate source-shape script as a package command. | No fixture command or configuration consumed the entry after the shape-only script was removed. | `test` and `deploy:check` remained available and passed. | Restore only with a justified layout guard and a current caller. | `npm run` listed only `test` and `deploy:check`; the residue search found no entry or caller. | + +## Mixed-change operation receipt + +```text +Scope: Finding S1, the layout guardrail, and Finding S2, the dead legacyLabel helper, as separate cuts. +Baseline: 4/4 tests, check:layout, and deploy:check passed. +Retired obligations: S1 exact source-shape enforcement; S2 an unexported, unconsumed legacy formatting helper. +Artifacts: S1 uses the three itemized artifacts above; S2 removes only the legacyLabel section of src/catalog.js. +Realized net effect: 4 files changed, 22 lines deleted, no dependency, replacement, or migration machinery added. +Behavior: pricing, invalid-quantity handling, authorization, exports, and deployment acceptance were preserved; layout enforcement and the unreachable helper were intentionally removed. +Residual risk: the fixture cannot disprove an external CI consumer of check:layout; the private, unexported helper has no external contract. +Retained candidates: none in this bounded fixture. +Undo: git apply -R docs/fixtures/implementation-shape-guardrail/mixed-change.patch +``` + +Cut-specific accounting: + +| Finding | Artifact | Original purpose | Decisive removal evidence | Surviving behavior | Reintroduction condition | Verification | +| --- | --- | --- | --- | --- | --- | --- | +| S1 | `tests/layout.guard.test.js`, `scripts/check-layout.js`, and `package.json` `check:layout` | Enforce the historical implementation shape. | The per-artifact evidence is recorded in the focused receipt above; S1 does not authorize S2. | Pricing, validation, authorization, exports, and deployment acceptance. | A current documented layout contract with an owner and caller. | 3/3 tests, deployment, residue, syntax, and diff checks passed. | +| S2 | `src/catalog.js` section `legacyLabel` | Format a legacy label, but remain private and unexported. | Repository search found no production, test, dynamic, external, or persisted consumer in the private fixture; S2 was proved independently of S1. | All exported pricing and authorization behavior. | A new observable label-format contract and consumer. | `node --check`, 3/3 tests, `deploy:check`, residue search, and diff check passed. | diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/package.json b/docs/fixtures/implementation-shape-guardrail/baseline/package.json new file mode 100644 index 0000000..3bf97ee --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/baseline/package.json @@ -0,0 +1,9 @@ +{ + "name": "implementation-shape-fixture", + "private": true, + "scripts": { + "test": "node --test", + "check:layout": "node scripts/check-layout.js", + "deploy:check": "node scripts/deploy-check.js" + } +} diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js b/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js new file mode 100644 index 0000000..051fde5 --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js @@ -0,0 +1,7 @@ +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const path = require("node:path"); + +const sourceDirectory = path.join(__dirname, "../src"); +assert.deepEqual(fs.readdirSync(sourceDirectory), ["catalog.js"]); +assert.match(fs.readFileSync(path.join(sourceDirectory, "catalog.js"), "utf8"), /function priceFor/); diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/scripts/deploy-check.js b/docs/fixtures/implementation-shape-guardrail/baseline/scripts/deploy-check.js new file mode 100644 index 0000000..291110f --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/baseline/scripts/deploy-check.js @@ -0,0 +1,5 @@ +const assert = require("node:assert/strict"); +const { authorize, priceFor } = require("../src/catalog"); + +assert.equal(priceFor(2, 11), 22); +assert.throws(() => authorize("guest"), /forbidden/); diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js b/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js new file mode 100644 index 0000000..7dd4a8b --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js @@ -0,0 +1,19 @@ +function priceFor(quantity, unitPrice) { + if (!Number.isInteger(quantity) || quantity < 1) { + throw new TypeError("quantity must be a positive integer"); + } + return quantity * unitPrice; +} + +function authorize(role) { + if (role !== "admin") { + throw new Error("forbidden"); + } + return true; +} + +function legacyLabel(value) { + return `legacy:${value}`; +} + +module.exports = { authorize, priceFor }; diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/tests/business.test.js b/docs/fixtures/implementation-shape-guardrail/baseline/tests/business.test.js new file mode 100644 index 0000000..5e1983e --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/baseline/tests/business.test.js @@ -0,0 +1,16 @@ +const assert = require("node:assert/strict"); +const test = require("node:test"); +const { authorize, priceFor } = require("../src/catalog"); + +test("prices an order", () => { + assert.equal(priceFor(3, 7), 21); +}); + +test("rejects invalid quantities", () => { + assert.throws(() => priceFor(0, 7), /positive integer/); +}); + +test("keeps authorization at the business boundary", () => { + assert.throws(() => authorize("viewer"), /forbidden/); + assert.equal(authorize("admin"), true); +}); diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js b/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js new file mode 100644 index 0000000..92b2b87 --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js @@ -0,0 +1,10 @@ +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const path = require("node:path"); +const test = require("node:test"); + +test("preserves the historical implementation shape", () => { + const source = fs.readFileSync(path.join(__dirname, "../src/catalog.js"), "utf8"); + assert.match(source, /function priceFor/); + assert.deepEqual(fs.readdirSync(path.join(__dirname, "../src")), ["catalog.js"]); +}); diff --git a/docs/fixtures/implementation-shape-guardrail/focused-change.patch b/docs/fixtures/implementation-shape-guardrail/focused-change.patch new file mode 100644 index 0000000..3ae4d0f --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/focused-change.patch @@ -0,0 +1,38 @@ +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/package.json b/docs/fixtures/implementation-shape-guardrail/baseline/package.json +--- a/docs/fixtures/implementation-shape-guardrail/baseline/package.json ++++ b/docs/fixtures/implementation-shape-guardrail/baseline/package.json +@@ -3,7 +3,6 @@ + "private": true, + "scripts": { + "test": "node --test", +- "check:layout": "node scripts/check-layout.js", + "deploy:check": "node scripts/deploy-check.js" + } + } +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js b/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js +deleted file mode 100644 +--- a/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js ++++ /dev/null +@@ -1,7 +0,0 @@ +-const assert = require("node:assert/strict"); +-const fs = require("node:fs"); +-const path = require("node:path"); +- +-const sourceDirectory = path.join(__dirname, "../src"); +-assert.deepEqual(fs.readdirSync(sourceDirectory), ["catalog.js"]); +-assert.match(fs.readFileSync(path.join(sourceDirectory, "catalog.js"), "utf8"), /function priceFor/); +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js b/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js +deleted file mode 100644 +--- a/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js ++++ /dev/null +@@ -1,10 +0,0 @@ +-const assert = require("node:assert/strict"); +-const fs = require("node:fs"); +-const path = require("node:path"); +-const test = require("node:test"); +- +-test("preserves the historical implementation shape", () => { +- const source = fs.readFileSync(path.join(__dirname, "../src/catalog.js"), "utf8"); +- assert.match(source, /function priceFor/); +- assert.deepEqual(fs.readdirSync(path.join(__dirname, "../src")), ["catalog.js"]); +-}); diff --git a/docs/fixtures/implementation-shape-guardrail/mixed-change.patch b/docs/fixtures/implementation-shape-guardrail/mixed-change.patch new file mode 100644 index 0000000..e1549c9 --- /dev/null +++ b/docs/fixtures/implementation-shape-guardrail/mixed-change.patch @@ -0,0 +1,47 @@ +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/package.json b/docs/fixtures/implementation-shape-guardrail/baseline/package.json +--- a/docs/fixtures/implementation-shape-guardrail/baseline/package.json ++++ b/docs/fixtures/implementation-shape-guardrail/baseline/package.json +@@ -3,7 +3,6 @@ + "private": true, + "scripts": { + "test": "node --test", +- "check:layout": "node scripts/check-layout.js", + "deploy:check": "node scripts/deploy-check.js" + } + } +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js b/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js +deleted file mode 100644 +--- a/docs/fixtures/implementation-shape-guardrail/baseline/scripts/check-layout.js ++++ /dev/null +@@ -1,7 +0,0 @@ +-const assert = require("node:assert/strict"); +-const fs = require("node:fs"); +-const path = require("node:path"); +- +-const sourceDirectory = path.join(__dirname, "../src"); +-assert.deepEqual(fs.readdirSync(sourceDirectory), ["catalog.js"]); +-assert.match(fs.readFileSync(path.join(sourceDirectory, "catalog.js"), "utf8"), /function priceFor/); +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js b/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js +--- a/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js ++++ b/docs/fixtures/implementation-shape-guardrail/baseline/src/catalog.js +@@ -15,5 +15 @@ +-function legacyLabel(value) { +- return `legacy:${value}`; +-} +- + module.exports = { authorize, priceFor }; +diff --git a/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js b/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js +deleted file mode 100644 +--- a/docs/fixtures/implementation-shape-guardrail/baseline/tests/layout.guard.test.js ++++ /dev/null +@@ -1,10 +0,0 @@ +-const assert = require("node:assert/strict"); +-const fs = require("node:fs"); +-const path = require("node:path"); +-const test = require("node:test"); +- +-test("preserves the historical implementation shape", () => { +- const source = fs.readFileSync(path.join(__dirname, "../src/catalog.js"), "utf8"); +- assert.match(source, /function priceFor/); +- assert.deepEqual(fs.readdirSync(path.join(__dirname, "../src")), ["catalog.js"]); +-}); diff --git a/docs/validation.md b/docs/validation.md index 782eada..cd95129 100644 --- a/docs/validation.md +++ b/docs/validation.md @@ -30,6 +30,14 @@ This document records the behavioral validation completed before the initial ope - Expected behavior: prove the cut below file granularity. - Result: the focused audit found 14 candidate-exclusive CSS classes, identified removable members inside mixed selectors, retained the shared stylesheet and surviving component, and found two stale documentation references. +### Implementation-shape guardrail + +- Auditable evidence: the [checked-in fixture, exact prompts and commands, patches, results, and itemized receipts](./fixtures/implementation-shape-guardrail/README.md). +- Fixture: a small dependency-free Node.js package with pricing and authorization behavior, an unexported dead helper, a deployment check, and a test plus script that asserted an exact source filename and function spelling. +- Ambiguous request: an independent Skill run was told only that defensive or AI-generated guardrails might exist. It selected Survey mode, made no edits, ranked the implementation-shape guard separately from the dead helper, and retained the quantity validation, authorization boundary, business tests, and deployment check. +- Focused change: an explicitly authorized run removed only `tests/layout.guard.test.js`, `scripts/check-layout.js`, and the `check:layout` package entry. The baseline passed 4 tests plus the layout and deployment checks; afterward all 3 surviving behavior tests and the deployment check passed. The operation receipt named every deleted artifact, its original check, the removal evidence, surviving behavior, reintroduction condition, verification, and undo path. +- Mixed objectives: an explicitly authorized run handled the shape guard and dead helper as separate proof records and cut boundaries. It removed 22 lines across 4 files with no replacement machinery, found no residue, passed syntax and diff checks, passed all 3 surviving behavior tests, and preserved the deployment check. The final receipt kept both cuts separate. + ### Cleanup Map renderer - Fixture: one Survey and one Change cleanup-map document covering a confirmed dispatch path and an adapter cut. diff --git a/references/execution-and-recovery.md b/references/execution-and-recovery.md index 2974d99..127f03d 100644 --- a/references/execution-and-recovery.md +++ b/references/execution-and-recovery.md @@ -6,6 +6,8 @@ Purpose: retire each proved obligation completely, validate the surviving system Prefer one high-confidence ownership boundary over a mixed cleanup batch. The selected change should retire a complete obligation and have a decisive check. If investigation reveals a larger product choice or broader migration than the user authorized, present the ranked plan and obtain one scope confirmation before applying it. +When one request includes an implementation-shape guardrail and another simplification, preserve separate proof records and cut boundaries. Removing the guardrail must not become authority to remove the implementation it once described, or vice versa. + Pause application when dynamic or external consumers remain unknown, stored data lacks a migration story, baseline failures erase the intended signal, the cut crosses unrelated ownership boundaries, or rollback would be impractical. Convert the result into an evidence report with the exact missing decision or fact. ## Remove the obligation vertically @@ -61,4 +63,6 @@ Undo: files or commit range to reverse and any data/config restoration required The undo path must match the side effects. Source-only changes may be reversible from the diff; migrations, published packages, deployments, and durable data require explicit restoration steps and separate authorization. +For a removed implementation-shape guardrail, the existing `Artifacts` entry must identify each deleted file or materially deleted section and state its original check, decisive removal evidence, surviving behavior, reintroduction condition, and verification. Use the same receipt rather than creating a parallel delivery schema. + The batch is complete only when the structural cut criterion, every applicable verification ring, the complete diff audit, and the operation receipt are all satisfied or reported as unavailable with the resulting evidence limitation. diff --git a/references/investigation.md b/references/investigation.md index 68e4367..c1ec119 100644 --- a/references/investigation.md +++ b/references/investigation.md @@ -31,9 +31,12 @@ Use these lenses to generate leads: - **Local infrastructure**: custom parsing, retry, framing, matching, diffing, scheduling, or collection code duplicates a suitable platform feature or dependency. - **Support drag**: tests, examples, snapshots, generated expectations, or documentation are the only reason an otherwise unused surface remains. - **Feature fossil**: implementation was abandoned or removed while schema, configuration, tests, compatibility logic, or design records still preserve its outline. +- **Implementation-shape guardrail**: a test, source scan, inventory, import ban, or build/CI check enforces file layout, literal source text, private defaults, exact component counts, or a historical implementation identity without owning observable behavior. Do not equate visual similarity with duplication. Independent implementations may test an interface, isolate failure domains, protect different owners, or support distinct compatibility contracts. +Do not use AI authorship or a label such as "defensive" as evidence that a guardrail is removable. Treat it as a candidate only when the consumer map shows that its remaining obligation is an obsolete implementation shape. Keep guards that protect business outcomes, public APIs, trust boundaries, security, persistence, concurrency, deployment acceptance, integration behavior, or an active engineering policy. + ## Climb the evidence ladder Classify each lead by the strongest evidence reached: