Skip to content

Commit deb103a

Browse files
committed
fix(agents-md): preserve child hand-written sections + sync threshold docs
Refs #1 (epic: internal AI guardrails thin distribution). Follow-up to ff221cc addressing PR-C round-2 review findings. - CRITICAL: dedupe now skips non-auto sections (was deleting child hand-written sections identical to ancestors). The parent-vs-child pass should only apply to generator-owned auto sections; a child file's hand-written `## House Rules` may legitimately echo its ancestor verbatim and must survive. - HIGH: sync --create-new threshold docs from stale '>= 5' to current '>= 2' in init-deep.md and types.ts public option JSDoc. - MEDIUM: fix score.ts docstring calibration example (3.6 -> 4.5); sqrt(3)*2 + 0 + (5/10)*(1+1) = 4.464, rounds to 4.5 not 3.6. - 2 new regression tests: child hand-written section preservation + auto section dedupe still works (carve-out is narrow). Refs PR-C re-review (Codex CLI route A round 2)
1 parent ff221cc commit deb103a

5 files changed

Lines changed: 58 additions & 3 deletions

File tree

‎.opencode/command/init-deep.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The pipeline runs in four phases: Discovery → Scoring → Generate → Review/
88
Arguments (parse from `$ARGUMENTS`, all optional):
99

1010
- `--max-depth=N` — maximum traversal depth from the working directory (default: 4).
11-
- `--create-new` — bypass the standard scoring threshold and emit at every directory with score >= 5.
11+
- `--create-new` — bypass the standard scoring threshold and emit at every directory with score >= 2.
1212
- `--dry-run` — compute the plan and print it without writing any files.
1313

1414
Steps:

‎packages/plugin/src/agents-md/dedupe.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,13 @@ export function dedupe(input: DedupeInput): DedupeOutput {
6565
if (rel === "." || rel === "AGENTS.md") continue
6666
const ancestors = ancestorPaths(rel).filter((a) => parsed.has(a))
6767
const filtered = sections.filter((s) => {
68+
// Skip preamble, preserve-marked, AND hand-written (non-auto) sections.
69+
// dedupe should only deduplicate sections that the generator owns; a
70+
// child file's hand-written `## House Rules` may legitimately echo its
71+
// ancestor verbatim and must not be silently deleted.
6872
if (s.heading === "") return true
6973
if (s.preserved) return true
74+
if (!s.isAuto) return true
7075
for (const a of ancestors) {
7176
const ancestorSection = parsed.get(a)?.find((x) => x.heading === s.heading)
7277
if (!ancestorSection) continue

‎packages/plugin/src/agents-md/score.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
* Calibration (typical values, with totalLoc large enough that loc_share
1818
* stays under the cap unless the directory really dominates):
1919
* - 1 file, 0 subdirs, 1 language, ~0% LOC → ≈ 2.0 → skip
20-
* - 3 files, 0 subdirs, 1 language, ~5% LOC → ≈ 3.6 → mid band
20+
* - 3 files, 0 subdirs, 1 language, ~5% LOC → ≈ 4.5 → mid band
2121
* - 4 files, 0 subdirs, 1 language, share→10 → 4 + 0 + 2 = 6 → high
2222
* - 5 files, 2 subdirs, 2 langs, share→10 → 4.47+2+3 = 9.47 → high
2323
* - 10 files, 4 subdirs, 2 langs, share→10 → 6.32+4+3 = 13.32 → strong high

‎packages/plugin/src/agents-md/types.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ export type InitDeepOpts = {
9292
cwd?: string
9393
/** Maximum depth from `cwd` (root = depth 0). Defaults to 4. */
9494
maxDepth?: number
95-
/** Bypass scoring and emit at every directory with score >= 5. */
95+
/** Bypass scoring and emit at every directory with score >= 2. */
9696
createNew?: boolean
9797
/** Compute a plan and return it without touching the filesystem. */
9898
dryRun?: boolean

‎packages/plugin/test/agents-md/dedupe.test.ts‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,4 +75,54 @@ describe("dedupe()", () => {
7575
expect(result.removed[0]!.heading).toBe("Overview")
7676
expect(result.files.get("pkg/AGENTS.md")!).not.toContain("shared overview")
7777
})
78+
79+
// Regression for round-2 CRITICAL — the parent-vs-child dedupe pass used to
80+
// run against *every* section (not just generator-owned auto sections), so a
81+
// child file's hand-written `## House Rules` that echoed an ancestor
82+
// verbatim was silently deleted. Hand-written sections must survive even
83+
// when their content matches an ancestor exactly.
84+
test("child hand-written sections matching an ancestor are preserved", () => {
85+
const root = [
86+
"# Project",
87+
"",
88+
"## House Rules",
89+
"",
90+
"- ship on Fridays",
91+
"- no force push",
92+
].join("\n")
93+
const child = [
94+
"# Pkg",
95+
"",
96+
"## House Rules",
97+
"",
98+
"- ship on Fridays",
99+
"- no force push",
100+
].join("\n")
101+
const input = new Map<string, string>([
102+
["AGENTS.md", root],
103+
["pkg/AGENTS.md", child],
104+
])
105+
const result = dedupe({ files: input })
106+
const childOut = result.files.get("pkg/AGENTS.md")!
107+
expect(childOut).toContain("## House Rules")
108+
expect(childOut).toContain("- ship on Fridays")
109+
expect(childOut).toContain("- no force push")
110+
expect(result.removed.find((r) => r.child === "pkg/AGENTS.md" && r.heading === "House Rules")).toBeUndefined()
111+
})
112+
113+
// Companion to the above — auto sections (Overview, Build & Test, etc.) MUST
114+
// still be deduped against ancestors. The hand-written carve-out is narrow:
115+
// only sections the generator does not own are exempt.
116+
test("child auto sections matching an ancestor are still removed", () => {
117+
const root = ["# Project", "", "## Build & Test", "", "Run `bun test`."].join("\n")
118+
const child = ["# Pkg", "", "## Build & Test", "", "Run `bun test`."].join("\n")
119+
const input = new Map<string, string>([
120+
["AGENTS.md", root],
121+
["pkg/AGENTS.md", child],
122+
])
123+
const result = dedupe({ files: input })
124+
const childOut = result.files.get("pkg/AGENTS.md")!
125+
expect(childOut).not.toContain("Run `bun test`.")
126+
expect(result.removed.find((r) => r.child === "pkg/AGENTS.md" && r.heading === "Build & Test")).toBeDefined()
127+
})
78128
})

0 commit comments

Comments
 (0)