jared/cc-os

Watch

Fork 0

contract-auditor: treat a lint-mandated class comment as an external constraint and reconcile refactorer evidence before re-raising an item #620

New issue

Closed

opened 2026-09-21 22:02:49 +00:00 by jared · 2 comments

jared commented

2026-09-21 22:02:49 +00:00

Owner

Context

Implementation 9 for ticket #563 escalated with bound_exhausted:contract-auditor/fail after a three-round cycle over one CORRECTION that should not have survived round one.

Observed

Contract-auditor dispatch 114 raised two CORRECTIONs: replace a hidden @stack ivar with a threaded local, and delete the class comment # Fence-aware line mask consumed as document.skip_mask. on plugins/os-aidd-lint/lib/aidd_lint/fence_mask.rb.
Refactorer 115 fixed the ivar item. The comment-deletion item carried forward.
Refactorer 118 tried the deletion. The lint gate failed with:

Missing top-level documentation comment for class AiddLint::FenceMask

Refactorer 118 reverted the deletion and returned NO-REFACTOR-NEEDED with that rationale.
Contract-auditor 117 and 120 re-raised the same CORRECTION verbatim, with all CONTRACT lines "intact". Dispatch 120 did not engage the rationale. The Runner escalated.
Cost: two extra refactorer, suite-check, and auditor rounds on a change with no remaining design item.

Reproduce

rubocop --only Style/Documentation plugins/os-aidd-lint/lib/aidd_lint/document.rb

That sibling file has no class comment and the cop reports the offense. fence_mask.rb with its comment is clean. .rubocop.yml does not inherit rubocop-base.yml, so Style/Documentation is enabled for this repo.
Handoffs: implementation 9, dispatches 114, 117, 118, 120 in .sdlc/pipeline.db.

Expected

The contract-auditor charter (plugins/os-sdlc/agents/contract-auditor.md) treats a comment that an enabled rubocop cop requires as an external-constraint comment, not a CORRECTION.
When a refactorer returns NO-REFACTOR-NEEDED with a stated reason for an item, the auditor either refutes the reason with evidence or drops the item. Re-raising it verbatim is not allowed.
Consider a Runner guard: identical CORRECTION text on three consecutive auditor dispatches escalates as wrong_verdict instead of spending another refactorer round.

Origin

Trigger: /os-sdlc:implement #563 escalation.
Improvised this session: implementation-close 9, hand-commit 1ab89c6d in worktree ticket-563.
Chain: auditor ignored refactorer rationale ← charter lacks the constraint-comment rule ← Style/Documentation enabled repo-wide is undocumented for agents.
Root candidate: none (this is the root).
Where: plugins/os-sdlc/agents/contract-auditor.md
Session: 8858ead3-4a18-4793-a17b-b548ce11a3a9
Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/8858ead3-4a18-4793-a17b-b548ce11a3a9.jsonl

VERDICT: CREATE — Observed failure from a complete implementation run (three wasted refactorer/auditor rounds, bound_exhausted escalation) with concrete dispatch evidence; no existing mechanism covers the constraint-comment gap, and Origin traces to this ticket as the root.

## Context Implementation 9 for ticket #563 escalated with `bound_exhausted:contract-auditor/fail` after a three-round cycle over one CORRECTION that should not have survived round one. ## Observed Contract-auditor dispatch 114 raised two CORRECTIONs: replace a hidden `@stack` ivar with a threaded local, and delete the class comment `# Fence-aware line mask consumed as document.skip_mask.` on `plugins/os-aidd-lint/lib/aidd_lint/fence_mask.rb`. Refactorer 115 fixed the ivar item. The comment-deletion item carried forward. Refactorer 118 tried the deletion. The lint gate failed with: ``` Missing top-level documentation comment for class AiddLint::FenceMask ``` Refactorer 118 reverted the deletion and returned `NO-REFACTOR-NEEDED` with that rationale. Contract-auditor 117 and 120 re-raised the same CORRECTION verbatim, with all CONTRACT lines "intact". Dispatch 120 did not engage the rationale. The Runner escalated. Cost: two extra refactorer, suite-check, and auditor rounds on a change with no remaining design item. ## Reproduce ``` rubocop --only Style/Documentation plugins/os-aidd-lint/lib/aidd_lint/document.rb ``` That sibling file has no class comment and the cop reports the offense. `fence_mask.rb` with its comment is clean. `.rubocop.yml` does not inherit `rubocop-base.yml`, so `Style/Documentation` is enabled for this repo. Handoffs: implementation 9, dispatches 114, 117, 118, 120 in `.sdlc/pipeline.db`. ## Expected - [ ] The contract-auditor charter (`plugins/os-sdlc/agents/contract-auditor.md`) treats a comment that an enabled rubocop cop requires as an external-constraint comment, not a CORRECTION. - [ ] When a refactorer returns `NO-REFACTOR-NEEDED` with a stated reason for an item, the auditor either refutes the reason with evidence or drops the item. Re-raising it verbatim is not allowed. - [ ] Consider a Runner guard: identical CORRECTION text on three consecutive auditor dispatches escalates as `wrong_verdict` instead of spending another refactorer round. ## Origin - Trigger: /os-sdlc:implement #563 escalation. - Improvised this session: implementation-close 9, hand-commit 1ab89c6d in worktree ticket-563. - Chain: auditor ignored refactorer rationale ← charter lacks the constraint-comment rule ← `Style/Documentation` enabled repo-wide is undocumented for agents. - Root candidate: none (this is the root). - Where: plugins/os-sdlc/agents/contract-auditor.md - Session: 8858ead3-4a18-4793-a17b-b548ce11a3a9 - Transcript: /home/jared/.claude/projects/-home-jared-dev-cc-os/8858ead3-4a18-4793-a17b-b548ce11a3a9.jsonl VERDICT: CREATE — Observed failure from a complete implementation run (three wasted refactorer/auditor rounds, bound_exhausted escalation) with concrete dispatch evidence; no existing mechanism covers the constraint-comment gap, and Origin traces to this ticket as the root.

jared added the

plugin/os-sdlc

filed-by/agent

labels

2026-09-21 22:02:49 +00:00

jared referenced this issue

2026-09-22 17:13:50 +00:00

aidd-lint hard-wrap cop joins code lines inside a nested fence #563

jared referenced this issue

2026-09-28 16:30:08 +00:00

Sweep the class comments that Style/Documentation forced #799

jared commented

2026-09-28 16:30:12 +00:00

Author

Owner

Resolution

Done: Style/Documentation cop disabled; the refactorer's NO-REFACTOR-NEEDED was correct and the cop was the defect, no charter change

Evidence: a2bf4a29, configs changed: .rubocop.yml; rubocop --only Style/Documentation reports 0

Follow-ups: #799 comment sweep

## Resolution **Done:** Style/Documentation cop disabled; the refactorer's NO-REFACTOR-NEEDED was correct and the cop was the defect, no charter change **Evidence:** a2bf4a29, configs changed: .rubocop.yml; rubocop --only Style/Documentation reports 0 **Follow-ups:** #799 comment sweep

jared closed this issue

2026-09-28 16:30:12 +00:00

jared commented

2026-09-28 16:30:23 +00:00

Author

Owner

Correction to prior evidence: rubocop --only Style/Documentation forces the cop to run regardless of Enabled:false (it still reports offenses under --only). The correct verification is a plain gate run: rubocop --config .rubocop.yml plugins/os reports 0 Style/Documentation offenses, confirming the cop is off in the normal lint path.

Correction to prior evidence: `rubocop --only Style/Documentation` forces the cop to run regardless of Enabled:false (it still reports offenses under --only). The correct verification is a plain gate run: `rubocop --config .rubocop.yml plugins/os` reports 0 Style/Documentation offenses, confirming the cop is off in the normal lint path.

jared referenced this issue from a commit

2026-09-28 19:36:44 +00:00

chore(lint): disable Style/Documentation; the repo comment rule forbids the comments it demanded (#620)

jared referenced this issue from a commit

2026-09-28 19:36:44 +00:00

fix(lint): Style/Documentation block moved below AllCops so Exclude stays under AllCops (#620)