[feature] Full Stylelint integration

[paudley]

Summary

Add full coding-ethos integration for stylelint from the pyqa_lint catalog.

Parent tracker: #77

pyqa_lint source: ~/Active/pyqa_lint/tooling/catalog/languages/css/stylelint.json

Scope

This issue covers one tool only. Integration is complete only when coding-ethos owns acquisition, execution, diagnostics, CSS language facts, CEL/SARIF output, policy alignment, MCP/agent visibility, docs, and tests.

Required Integration Surface

1. Tool Acquisition

• Add deterministic managed acquisition for stylelint.
• Pin the version and checksum where a release artifact is downloaded.
• Record provenance in the managed toolchain manifest.
• Validate the acquired executable during bootstrap and fail fast with a structured diagnostic if validation fails.
• Do not rely on an arbitrary host-installed stylelint from PATH.

2. Command Orchestration

• Build command construction in Go through the hook runner or managed capture path.
• Select staged/changed targets when safe; if stylelint requires project-level execution, document the reason and isolate the scope.
• Pass config paths explicitly and log the selected source of truth.
• Respect sandboxing, timeout, filesystem, and network policy.
• Avoid shell glue and Go-to-shell-to-Go execution paths.

3. Diagnostics Parsing

• Parse native stylelint output into normalized diagnostics with tool, file, line, column, severity, rule/code, and message.
• Convert unparseable output into structured tool-failure diagnostics.
• Preserve raw output in traces without flooding TOON or MCP summaries.
• Add parser fixtures for success, warning/error severity mapping, empty output, and malformed output.

4. Language AST Facts

• Confirm Tree-sitter/AST fact support for CSS files is sufficient for policy context and SARIF locations.
• Extend shared AST fact collection first if policy context is missing.
• Do not add ad hoc text scanners or policy-specific AST walkers before checking the AST/CEL/SARIF architecture path.
• Add fixtures proving representative CSS files can be indexed, or explicitly document why AST facts are not applicable for this tool.

5. CEL and Policy Alignment

• Expose stylelint findings through the existing CEL diagnostic inputs by tool, rule/code, file, severity, and path metadata.
• Add policy mappings only where coding-ethos has a clear repo-trust, maintainability, security, or safety opinion.
• Align actionable findings with relevant ethos principles and remediation skills.
• Keep advisory versus blocking behavior explicit and configurable.

6. SARIF Integration

• Emit SARIF with stable ruleId, source tool metadata, severity, and location data.
• Include related locations, fixes, or help text when stylelint exposes them.
• Add SARIF shape tests for at least one real diagnostic.
• Preserve stable identities so CI, PR review, and IDE surfaces can correlate findings over time.

7. MCP and Agent Surface

• Ensure lint_check, lint_advice, SARIF remediation, risk summary, trend analysis, and hook traces identify stylelint correctly.
• Add capability metadata for file reads, file writes, tool execution, network use, autofix support, and advisory/blocking role.
• Make failure modes actionable for agents and human contributors.

8. Docs and Config

• Document managed acquisition, config source of truth, generated config behavior, and common remediation guidance.
• Update README/tooling docs and examples for the CSS path.
• If coding-ethos generates config for stylelint, add drift checks and hash manifest entries.

Acceptance Criteria

• stylelint is acquired through the managed toolchain with version/checksum/provenance recorded where applicable.
• The hook runner or managed capture path invokes stylelint without shell glue or implicit host config discovery.
• Native diagnostics are parsed into normalized diagnostics and SARIF.
• AST/language fact support for CSS is present or explicitly documented as not applicable.
• CEL policy inputs can reason over stylelint findings by tool/code/file/severity.
• MCP lint and SARIF advice surfaces include stylelint output cleanly.
• Documentation explains config ownership and expected operator workflow.
• Unit tests cover acquisition, command construction, parser success, parser failure, and SARIF shape.
• A functional workflow test exercises stylelint on a representative fixture.
• make build, make pre-commit, and relevant Go package tests pass.

[paudley]

Stage 1 plan for #81:

Assumptions:

• Use the existing npm-managed toolchain path; do not rely on host stylelint.
• Pin stylelint@17.13.0, the current npm version, with npm dist integrity sha512-G1WYzMerp7ihOaIe9VJCHLt12MoAD2QLf1AFerYP37+BCRBUK5UCpq8e/mN+zCIaJPKQcaxhE4WlPmqdiOx/gw==.
• Stylelint requires an explicit config. I will support a repo-owned .stylelintrc.json when present and add a checked-in bundle fallback config so managed capture never depends on implicit host or parent config discovery.
• Add CSS AST facts through github.com/tree-sitter/tree-sitter-css/bindings/go rather than adding text scanners.

Implementation steps:

1. Add locked npm acquisition for stylelint and record it in managed-toolchain.tsv.
2. Add a bundle fallback Stylelint config and managed-capture enforcement for JSON output, explicit config path, and stripped caller config flags.
3. Add catalog metadata, hook command/group wiring, CSS target selection, and autofix metadata where supported.
4. Add native JSON diagnostics parsing, malformed-output handling, SARIF shape coverage, and hook/capture/toolchain tests.
5. Add CSS AST language support and fixture tests for representative .css files.
6. Update README, hook runtime, pre-commit, and hook docs for acquisition, config ownership, CSS workflow, and operator expectations.
7. Validate with focused Go tests, a managed Stylelint smoke test, make build, make check, and policy-git diff --check before commit/PR.

[paudley]

Stage 1 implementation is prepared and staged in the isolated worktree, but the protected git policy requires a human/admin commit for the staged administrative files.

Worktree: /home/paudley/Active/gmeow/coding-ethos/.worktrees/paudley-81-full-stylelint-integration
Branch: paudley/81-full-stylelint-integration

Implemented:

• Added managed stylelint@17.13.0 npm acquisition, lockfiles, manifest entry, and fallback bundle config.
• Registered Stylelint in the tool catalog, managed capture, parser, SARIF formatting, and css hook group.
• Added config hardening so managed capture strips caller config flags, prefers repo .stylelintrc.json, and otherwise injects pre-commit/hooks/stylelint.config.json.
• Added CSS Tree-sitter facts for .css style rules and code-intel query support.
• Updated README and hook/runtime docs for Stylelint, CSS hook coverage, and CSS AST coverage.

Validation passed:

• go test -buildvcs=false ./diagnostics ./toolcatalog ./internal/toolchaincli ./internal/hookrunnercli ./internal/managedcapture ./internal/hookoutput ./internal/astfacts ./internal/codeintel
• make build
• build/toolchain/github-bin/stylelint --version -> 17.13.0
• rg -n "stylelint" build/toolchain/manifest.tsv pre-commit/hooks/managed-toolchain.tsv
• Managed smoke test: bin/coding-ethos-run policy-tool stylelint --config local.stylelintrc.json stylelint-smoke.css returned normalized color-no-invalid-hex and declaration-block-no-duplicate-properties findings with exit 2.
• make check passed; it reported the existing non-blocking testing.go_coverage_goal warning.
• bin/coding-ethos-run policy-git diff --check

Commit block:

status: blocked
policy_id: git.staged_admin_files
message: Administrative staged files require explicit handling.
files:
  pre-commit/PRE-COMMIT.md
  pre-commit/hooks/HOOKS.md
  pre-commit/hooks/managed-toolchain.tsv
  pre-commit/hooks/npm-locks/stylelint-17.13.0/package-lock.json
  pre-commit/hooks/npm-locks/stylelint-17.13.0/package.json
  pre-commit/hooks/stylelint.config.json

Admin commit command:

cd /home/paudley/Active/gmeow/coding-ethos/.worktrees/paudley-81-full-stylelint-integration
git commit -m 'feat(toolchain): add managed Stylelint integration'

The staged index has been left intact for admin review.