playbook/antigravity-awesome-skills/skills/ecl-harness-engineer/agents/creator-linters.md

Linter Creation Agent

You are creating or updating linter scripts for agent harness infrastructure.

Input

You will receive:

• Architecture analysis with full layer hierarchy (from harness/.analysis/architecture.json)
• Existing linter state (from harness/.analysis/audit.json)
• Delta list of what to create/update

Files You Create/Update

scripts/lint-deps.{ext}

Purpose: Enforce layer boundaries — prevent forbidden imports.

Must include:

• Complete layer map with EVERY package from the architecture analysis
• No blind spots — if a package exists, it must be in the layer map
• Layer rules: Layer N can only import from layers < N

Error message format (agent-actionable):

{file}:{line} imports {forbidden_package} (layer {N} → layer {M}).
Layer {N} packages can only import from layers < {N}.

Fix options:
1. Move {logic description} to a higher layer (e.g., {suggestion})
2. Pass the value as a parameter instead of importing directly
3. Define an interface in layer {N} and implement in layer {M}

This is the most important quality requirement. An error message that only says "Forbidden import" is useless to an agent. The message must tell WHAT is wrong, WHY it matters, and HOW to fix it.

scripts/lint-quality.{ext}

Purpose: Enforce code quality patterns.

Common rules (customize based on codebase patterns):

• File size limits (e.g., > 500 lines → warning)
• Structured logging enforcement
• Error wrapping convention
• Naming conventions
• Test file presence

Same error message quality: WHAT + WHY + HOW.

scripts/lint-ecl.{ps1|sh|mjs|py}

Purpose: Enforce ECL change lifecycle integrity.

Must check:

• harness/changes/active/ has summary.md, spec.md, plan.md, tasks.md, and reviews/ when active exists.
• Markdown front matter status is internally consistent.
• Active changes in implement, validate, or done phase have no high-impact [NEEDS CLARIFICATION: ...] markers in spec.md.
• Active changes cannot enter implementation until plan_review is approved in summary.md or an equivalent approved Plan Review exists in reviews/review.md.
• Executable task lines in tasks.md use T### ids, and implementation tasks include target paths plus validation notes.
• completed changes have validation results.
• tasks.md with unexplained pending items cannot be completed.
• docs/STATUS.md exists for ECL-enabled projects and clearly says active change files override it.
• A temporary regenerated index matches harness/changes/INDEX.json; otherwise fail and tell the user to run the generated scripts/harness-change.* reindex equivalent.
• scripts/harness-evolve.* and harness/evolution/state.json exist for core auto-evolve threshold checking.
• If harness/evolution/pending.md exists, lint may report it as pending context, but must not apply or delete it automatically.

scripts/lint-encoding.{ps1|sh|mjs|py}

Purpose: Enforce UTF-8 and prevent mojibake from being written into source or docs.

Must check:

• Scan text files for known mojibake markers listed in references/ecl-harness.md.
• Exclude generated/vendor/cache directories.
• Return actionable file and line messages.

Language-Specific Templates

Use templates from references/linter-templates.md as starting points, then customize:

• Go: Go script that parses imports, checks against layer map
• TypeScript/Node.js: read references/adapters/typescript.md first; generate Node/TS-native scripts such as scripts/lint-deps.mjs and scripts/lint-quality.mjs, and wire them through npm/package-manager scripts
• Python: Python script that parses from/import statements
• ECL/Encoding: use the selected command surface profile from references/ecl-harness.md (.ps1, .sh, .mjs, or .py)

Critical Rules

1. Day-one pass required: The linter MUST pass on the current codebase without errors. If the codebase has existing violations, document them in docs/exec-plans/tech-debt-tracker.md instead of failing the linter.

2. Complete coverage: Every package in the codebase must appear in the layer map. Missing packages = blind spots = undetected violations.

3. Executable: Scripts must run from the project root. Bash/Node/Python scripts should be executable when the environment supports file modes; Windows-only profiles may use explicit interpreter commands.

4. Makefile integration: Ensure make lint-arch target runs these scripts.

5. Generated index, evolution, and handoff discipline: lint-ecl verifies INDEX.json freshness, auto-evolve state presence, and docs/STATUS.md presence, but never rewrites those files. Rewriting belongs to the generated harness-change reindex, harness-evolve check/mark-complete, and explicit agent/human handoff updates.

6. Command surface consistency: Select the script profile automatically from project evidence. If the project rejects .ps1, do not generate PowerShell as the only entrypoint. For Windows projects using Bash, document Git Bash, WSL, MSYS2, or CI Linux shell as a prerequisite. If the PowerShell profile is selected, scripts must run on Windows PowerShell 5.1 as well as PowerShell 7.

7. Strict business gates: Do not remove or weaken existing project lint, typecheck, test, or build checks to make CI pass. If those checks fail before harness creation, report them as pre-existing project debt; keep the generated CI strict unless the user explicitly asks for staged rollout.

Verification

After creating linters, verify:

# Linters are executable
chmod +x scripts/lint-deps* scripts/lint-quality*

# Linters pass on current codebase
make lint-arch

# ECL and encoding checks pass
{ecl_lint_command}
{encoding_lint_command}

# Count covered packages vs total packages
# (should be 100%)