Skip to content

Add judgment-layer mistake entries to AGENTS.md#136

Merged
nateshpp merged 1 commit into
mainfrom
docs/Governance-guidelines-update
Jul 16, 2026
Merged

Add judgment-layer mistake entries to AGENTS.md#136
nateshpp merged 1 commit into
mainfrom
docs/Governance-guidelines-update

Conversation

@nateshpp

@nateshpp nateshpp commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

What this PR does

Adds three entries to AGENTS.md's mistake catalog (section 4) and one trigger to its
escalation list (section 6). All three name a failure mode no deterministic gate can
catch: silently picking one reading of an ambiguous goal, building past the stated
need, and drifting into unrelated code inside an otherwise in-scope file. Today these
get caught only in review, if at all. This gives reviewers, human or agent, a citable
rule instead of ad hoc pushback. Tracked as WI-054.

Details

  • Entry 19, silent interpretation. A goal with two or more materially different
    readings gets named and escalated (in session, or as a DECISIONS.md Open entry with
    options and a recommendation), never silently resolved one way.
  • Entry 20, speculative scope. No feature, config control, or abstraction beyond the
    stated need. Every config control already costs four synced representations plus a
    changelog entry (section 5); this makes the discipline explicit and citable.
  • Entry 21, within-file scope drift. Complements entry 9: entry 9 polices which
    files change (the edit-set gate); entry 21 polices the lines inside a file the item
    already allows, where no gate can see. Unrelated dead code gets flagged in review, not
    deleted.
  • Section 6, item 10. New escalation trigger: a goal that supports more than one
    materially different reading routes to the owner with the readings and a
    recommendation, reusing the options format DECISIONS.md Open entries already carry.
  • Documentation only. No script, schema, or config control changes; schema_version
    stays at 1.

Governance checklist

  • npm run verify passes locally (drift guard, style check, tests, AgentProof)
  • No em dashes in any tracked file
  • Prose states conclusions directly
  • No AI co-author lines in commit messages
  • N/A: no ratchet logic changed
  • N/A: no new AgentProof scenario
  • N/A: no config schema changed; CHANGELOG entry added regardless
  • N/A: prompts/ untouched, no bundle rebuild needed

Test evidence

# tests 914
# suites 17
# pass 914
# fail 0
Score: 25/25 normative | 10/10 extended (35/35 total)
Level: HARDENED

Append entries 19-21 to the section 4 mistake catalog: silent
interpretation of an ambiguous goal, speculative scope, and within-file
scope drift. Insert a section 6 escalation trigger for goals that
support materially different readings. Record the change in the
changelog, add the WI-054 work item at checking, and regenerate the
snapshot and release evidence.
@nateshpp
nateshpp requested a review from techseek4vr as a code owner July 16, 2026 02:29
@nateshpp
nateshpp merged commit b7ae460 into main Jul 16, 2026
7 of 8 checks passed
@nateshpp
nateshpp deleted the docs/Governance-guidelines-update branch July 16, 2026 03:36
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.

2 participants