jared/cc-os
Watch
1
0
Fork
You've already forked cc-os
 0
Code Issues 147 Pull requests Projects Releases Packages Wiki Activity

aidd-lint: system map (umbrella) #109

New issue
Open
opened 2026-07-23 11:31:45 +00:00 by jared · 7 comments
jared commented 2026-07-23 11:31:45 +00:00
Owner
Copy link

What this is

The umbrella/mapping ticket for the aidd-lint system: linting AiDD files (SKILL.md, prompts, instructions, reference files) so they stay clean, clear, and flexible. Refer to THIS ticket to work on the system; the components below are its parts. Born from the mine-lints simplification (commit c6a4177, 2026-07-23), where three prose smells -- war stories, gate logic in prose, misplaced tool quirks -- were removed by hand and found to be mechanically detectable.

Architecture: three tiers (mirrors the code-lint split)

  • Tier 1 -- deterministic cops (markdown/regex/arithmetic, no model). Structural symptoms proxy for semantic smells: gate-logic-in-prose has no lexical signature but reliably makes steps long, so bulk limits catch it.
  • Tier 2 -- AI charter pass: closed catalog of smells with no structural signature; single-shot cheap-model judge. Also the anti-gaming backstop for Tier-1 proxies. Ship WITH Tier 1, not after.
  • Tier 3 -- human residue: "is this sentence essential sequencing or relocatable" stays a session-level human call, per the ADR-0048 pattern. Not automated; not ticketed beyond this line.

Principles

  • Thresholds are config (.aidd-lint.yml), not constants -- glanceability limits are malleable by design.
  • Audit existing tools before hand-rolling (mdformat/prettier for unwrapping, readability gems for grade scoring).
  • Fix pattern is relocate-don't-delete: detail moves to references/*.md, templates, or Ruby -- which is why the dead-pointer cop is load-bearing.
  • Ticket titles use the aidd-lint prefix, deliberately distinct from os-sdlc lint rule: so mine-lints novelty searches stay clean.

Components

Tier 1 (each follows lint-rule-ticket-template.md):

  • #100 workflow-war-story
  • #101 step-bulk (glanceability; tunable thresholds)
  • #102 dead-reference-pointer
  • #103 cross-section-duplication
  • #104 hard-wrap (autocorrecting; no-wrap policy for AiDD prose)
  • #105 sentence-complexity (words/sentence + FK grade advisory)
  • #106 skill-frontmatter-name (suggested tracer: smallest end-to-end cop)

System:

  • #107 Tier-2 prose-smell charter (AI pass)
  • #108 trigger architecture (PostToolUse hook, edit-size gate, home-plugin ADR)

Suggested order

T9's ADR (home decision) -> T7 as tracer through new infra -> T5 (autofix, immediate daily value) -> T1/T2/T3/T4/T6 -> T8 charter alongside T2.

## What this is The umbrella/mapping ticket for the **aidd-lint system**: linting AiDD files (SKILL.md, prompts, instructions, reference files) so they stay clean, clear, and flexible. Refer to THIS ticket to work on the system; the components below are its parts. Born from the mine-lints simplification (commit c6a4177, 2026-07-23), where three prose smells -- war stories, gate logic in prose, misplaced tool quirks -- were removed by hand and found to be mechanically detectable. ## Architecture: three tiers (mirrors the code-lint split) - **Tier 1 -- deterministic cops** (markdown/regex/arithmetic, no model). Structural symptoms proxy for semantic smells: gate-logic-in-prose has no lexical signature but reliably makes steps long, so bulk limits catch it. - **Tier 2 -- AI charter pass**: closed catalog of smells with no structural signature; single-shot cheap-model judge. Also the anti-gaming backstop for Tier-1 proxies. Ship WITH Tier 1, not after. - **Tier 3 -- human residue**: "is this sentence essential sequencing or relocatable" stays a session-level human call, per the ADR-0048 pattern. Not automated; not ticketed beyond this line. ## Principles - Thresholds are config (`.aidd-lint.yml`), not constants -- glanceability limits are malleable by design. - Audit existing tools before hand-rolling (mdformat/prettier for unwrapping, readability gems for grade scoring). - Fix pattern is relocate-don't-delete: detail moves to references/*.md, templates, or Ruby -- which is why the dead-pointer cop is load-bearing. - Ticket titles use the `aidd-lint` prefix, deliberately distinct from `os-sdlc lint rule:` so mine-lints novelty searches stay clean. ## Components Tier 1 (each follows lint-rule-ticket-template.md): - #100 workflow-war-story - #101 step-bulk (glanceability; tunable thresholds) - #102 dead-reference-pointer - #103 cross-section-duplication - #104 hard-wrap (autocorrecting; no-wrap policy for AiDD prose) - #105 sentence-complexity (words/sentence + FK grade advisory) - #106 skill-frontmatter-name (suggested tracer: smallest end-to-end cop) System: - #107 Tier-2 prose-smell charter (AI pass) - #108 trigger architecture (PostToolUse hook, edit-size gate, home-plugin ADR) ## Suggested order T9's ADR (home decision) -> T7 as tracer through new infra -> T5 (autofix, immediate daily value) -> T1/T2/T3/T4/T6 -> T8 charter alongside T2.
jared commented 2026-07-23 12:09:09 +00:00
Author
Owner
Copy link

aidd-lint execution plan (2026-07-23)

Home decision: new plugin os-aidd-lint — ADR-0058. Branch: aidd-lint/tier-1.

This round (Tier 1)

  • ADR-0058: home = os-aidd-lint (prerequisite from #108)
  • Batch 0 — infra tracer: MarkdownCop base, registry, .aidd-lint.yml loader, test helper + #106 skill-frontmatter-name (autocorrect)
  • Batch 1 — structural cops: #100 workflow-war-story, #101 step-bulk, #103 cross-section-duplication
  • Batch 2 — text metrics (audit-defaults-first): #104 hard-wrap (autocorrect via mdformat/prettier), #105 sentence-complexity
  • Batch 3 — filesystem: #102 dead-reference-pointer (advisory only, no autocorrect)
  • Verify pass: report-only scan over AiDD corpus, false-positive review

Future sessions

  • Tier 2: #107 closed-catalog AI charter judge (judgment-tier; backstops #101 gaming risk)
  • #108 trigger architecture: PostToolUse hook wiring, ~20-changed-word gate, report-only (ADR prerequisite now met)
  • Plan Tier 3 residue handling; create tickets when scoped
  • Session-start/plugin registration + bin/refresh-plugins once hooks exist
## aidd-lint execution plan (2026-07-23) Home decision: new plugin `os-aidd-lint` — ADR-0058. Branch: `aidd-lint/tier-1`. ### This round (Tier 1) - [x] ADR-0058: home = os-aidd-lint (prerequisite from #108) - [x] Batch 0 — infra tracer: MarkdownCop base, registry, .aidd-lint.yml loader, test helper + #106 skill-frontmatter-name (autocorrect) - [x] Batch 1 — structural cops: #100 workflow-war-story, #101 step-bulk, #103 cross-section-duplication - [x] Batch 2 — text metrics (audit-defaults-first): #104 hard-wrap (autocorrect via mdformat/prettier), #105 sentence-complexity - [x] Batch 3 — filesystem: #102 dead-reference-pointer (advisory only, no autocorrect) - [x] Verify pass: report-only scan over AiDD corpus, false-positive review ### Future sessions - [ ] Tier 2: #107 closed-catalog AI charter judge (judgment-tier; backstops #101 gaming risk) - [ ] #108 trigger architecture: PostToolUse hook wiring, ~20-changed-word gate, report-only (ADR prerequisite now met) - [ ] Plan Tier 3 residue handling; create tickets when scoped - [ ] Session-start/plugin registration + bin/refresh-plugins once hooks exist
jared commented 2026-07-23 12:44:29 +00:00
Author
Owner
Copy link

Tier 1 complete on branch aidd-lint/tier-1 (uncommitted, pending review). Open judgment items for human: #103 threshold miscalibration (ticket's own example scores Jaccard 0.19 vs 0.8 threshold); #104 hand-rolled join chosen over prettier (Node dep); #102 resolution scope gaps (CLAUDE_PLUGIN_ROOT paths, runtime artifacts → 51 mostly-false-positive hits); severity calls on #102/#104 (:offense) were implementer judgment, tickets silent; odyssey gem is an optional dependency for #105 grade-level advisory (no Gemfile yet).

Tier 1 complete on branch aidd-lint/tier-1 (uncommitted, pending review). Open judgment items for human: #103 threshold miscalibration (ticket's own example scores Jaccard 0.19 vs 0.8 threshold); #104 hand-rolled join chosen over prettier (Node dep); #102 resolution scope gaps (CLAUDE_PLUGIN_ROOT paths, runtime artifacts → 51 mostly-false-positive hits); severity calls on #102/#104 (:offense) were implementer judgment, tickets silent; odyssey gem is an optional dependency for #105 grade-level advisory (no Gemfile yet).
jared commented 2026-07-23 15:40:50 +00:00
Author
Owner
Copy link

Decisions recorded: #103 stays at 0.8, near-verbatim only, paraphrase detection deferred to #107 Tier 2. #104 hand-rolled join accepted. #102 demoted to :advisory pending resolution-widening ticket #110. odyssey confirmed installed globally, no Bundler.

Decisions recorded: #103 stays at 0.8, near-verbatim only, paraphrase detection deferred to #107 Tier 2. #104 hand-rolled join accepted. #102 demoted to `:advisory` pending resolution-widening ticket #110. odyssey confirmed installed globally, no Bundler.
jared commented 2026-07-23 17:40:24 +00:00
Author
Owner
Copy link

Tier-2 round complete on branch aidd-lint/tier-2, uncommitted pending review. #107 + #108 both implemented (see their comments), ADR-0059 + ADR-0060, full plugin suite 151 runs / 316 assertions green, opus diff review passed after 3 small fixes.

Notable for the system map: the extra catalog-validation mining pass (3 unrelated files, blind-then-reconcile) confirmed only duplicated-authority as a recurring Tier-2 smell; the other two charter entries are provisional pending real-world instances. Novel duplication variants surfaced for future consideration (not added to the closed catalog): frontmatter-vs-body restatement; multi-level "rule ladder" paraphrase chains that dodge the Jaccard cop.

Remaining after merge: queue-drain wiring ticket, Tier-3 residue planning, refresh-plugins + sandbox hook verification, worktree cleanup.

Tier-2 round complete on branch aidd-lint/tier-2, uncommitted pending review. #107 + #108 both implemented (see their comments), ADR-0059 + ADR-0060, full plugin suite 151 runs / 316 assertions green, opus diff review passed after 3 small fixes. Notable for the system map: the extra catalog-validation mining pass (3 unrelated files, blind-then-reconcile) confirmed only duplicated-authority as a recurring Tier-2 smell; the other two charter entries are provisional pending real-world instances. Novel duplication variants surfaced for future consideration (not added to the closed catalog): frontmatter-vs-body restatement; multi-level "rule ladder" paraphrase chains that dodge the Jaccard cop. Remaining after merge: queue-drain wiring ticket, Tier-3 residue planning, refresh-plugins + sandbox hook verification, worktree cleanup.
jared commented 2026-07-23 18:12:45 +00:00
Author
Owner
Copy link

Registration + live sandbox hook verification complete (2026-07-23): small-edit gate skip, large-edit Tier-1 fire, SessionEnd finalize, and post-registration plugin-path firing all confirmed. Hooks are now live.

Registration + live sandbox hook verification complete (2026-07-23): small-edit gate skip, large-edit Tier-1 fire, SessionEnd finalize, and post-registration plugin-path firing all confirmed. Hooks are now live.
jared commented 2026-08-13 18:14:59 +00:00
Author
Owner
Copy link

Still accurate: os-aidd-lint.md confirms hooks registered in marketplace.json but 'not yet live' -- registration/sandbox verification tracked as open item on this ticket, matches ticket's own remaining checklist. Leaving open.

Still accurate: os-aidd-lint.md confirms hooks registered in marketplace.json but 'not yet live' -- registration/sandbox verification tracked as open item on this ticket, matches ticket's own remaining checklist. Leaving open.
jared commented 2026-08-16 14:31:32 +00:00
Author
Owner
Copy link

Frozen in the 2026-08-16 backlog reset — see #419 for the expiry procedure. Do not work unless a live run rediscovers this issue.

Frozen in the 2026-08-16 backlog reset — see #419 for the expiry procedure. Do not work unless a live run rediscovers this issue.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
No results found.
Labels
Clear labels   
P0
Priority 0 — drop everything

  
P1
Priority 1 — next up

  
P2
Priority 2 — normal

  
P3
Priority 3 — someday

  
bug
Something is broken

  
create
Ticket creates something new

  
delete
Ticket removes something

  
enhancement
New feature or improvement

  
filed-by/agent

   
filed-by/user

   
frozen
Pre-reset backlog freeze 2026-08-16; do not work unless rediscovered by a live run

  
lint-rule
Ticket proposes/modifies a lint rule or cop

  
needs-info
Waiting on reporter for more information

  
needs-triage
Maintainer needs to evaluate this issue

  
next
Human-curated next up — AI never applies or removes

  
plugin/cc-architect
Scope: the cc-architect plugin

  
plugin/os
Scope: the os plugin

  
plugin/os-adr
Scope: the os-adr plugin

  
plugin/os-aidd-lint
Scope: the os-aidd-lint plugin

  
plugin/os-backlog
Scope: the os-backlog plugin

  
plugin/os-context
Scope: the os-context plugin

  
plugin/os-doc-hygiene
Scope: the os-doc-hygiene plugin

  
plugin/os-sdlc
Scope: the os-sdlc plugin

  
plugin/os-vault
Scope: the os-vault plugin

  
project/cc-os
Parent-scope: cc-os repo-wide, not specific to one plugin

  
ready-for-agent
Triage complete; an agent can pick this up

  
ready-for-human
Human-owned; never picked up autonomously

  
recurring
Recurring flavor: occurrence outcomes commented, never closed by AI

  
review
Shipped semi work awaiting human sign-off

  
update
Ticket updates something existing

  
waiting
Blocked; blocker named in a comment

  
wayfinder:grilling

   
wayfinder:map

   
wayfinder:map
wayfinder map ticket

  
wayfinder:research

   
wayfinder:task

   
wayfinder:task
wayfinder map child: task

  
wontfix
Will not be actioned

  
worklist/deviations
Deviation incidents from skill/pipeline runs — evidence pile for correcting the owning artifact

  
worklist/lint-rule
Proposed os-sdlc or os-aidd-lint rule

  
worklist/new-implement-build
Updated implementation harness (ast-grep + stepper)

No labels
P0
P1
P2
P3
bug
create
delete
enhancement
filed-by/agent
filed-by/user
frozen
lint-rule
needs-info
needs-triage
next
plugin/cc-architect
plugin/os
plugin/os-adr
plugin/os-aidd-lint
plugin/os-backlog
plugin/os-context
plugin/os-doc-hygiene
plugin/os-sdlc
plugin/os-vault
project/cc-os
ready-for-agent
ready-for-human
recurring
review
update
waiting
wayfinder:grilling
wayfinder:map
wayfinder:map
wayfinder:research
wayfinder:task
wayfinder:task
wontfix
worklist/deviations
worklist/lint-rule
worklist/new-implement-build
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
jared/cc-os#109
No description provided.