[feature] Full remark-lint integration

[paudley]

Summary

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

Parent tracker: #77

pyqa_lint source: ~/Active/pyqa_lint/tooling/catalog/languages/markdown/remark-lint.json

Scope

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

Required Integration Surface

1. Tool Acquisition

• Add deterministic managed acquisition for remark-lint.
• 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 remark-lint 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 remark-lint 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 remark-lint 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 Markdown 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 Markdown files can be indexed, or explicitly document why AST facts are not applicable for this tool.

5. CEL and Policy Alignment

• Expose remark-lint 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 remark-lint 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 remark-lint 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 Markdown path.
• If coding-ethos generates config for remark-lint, add drift checks and hash manifest entries.

Acceptance Criteria

• remark-lint is acquired through the managed toolchain with version/checksum/provenance recorded where applicable.
• The hook runner or managed capture path invokes remark-lint without shell glue or implicit host config discovery.
• Native diagnostics are parsed into normalized diagnostics and SARIF.
• AST/language fact support for Markdown is present or explicitly documented as not applicable.
• CEL policy inputs can reason over remark-lint findings by tool/code/file/severity.
• MCP lint and SARIF advice surfaces include remark-lint 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 remark-lint on a representative fixture.
• make build, make pre-commit, and relevant Go package tests pass.

[paudley]

Stage 1 plan for #88.

Issue summary:

• Add full coding-ethos integration for remark-lint from the pyqa_lint Markdown catalog.
• pyqa source: /home/paudley/Active/pyqa_lint/tooling/catalog/languages/markdown/remark-lint.json.
• Command shape from catalog: remark --use remark-preset-lint-recommended --report json --frail --quiet --no-color <files>.

Workspace:

• Worktree: /home/paudley/Active/gmeow/coding-ethos/.worktrees/paudley-88-full-remark-lint-integration
• Branch: paudley/88-full-remark-lint-integration

Implementation tasks:

• Add a managed npm toolchain entry and lockfile for the remark package set: remark-cli, remark-lint, remark-preset-lint-recommended, and vfile-reporter-json.
• Add remark-lint tool catalog metadata, capture args, file matching for .md, .mdx, .markdown, and hook-runner command wiring for a Markdown hook group.
• Add a normalized diagnostics parser for remark JSON output, including file arrays, files/results wrapper shapes, fatal/severity mapping, location fallback, rule IDs, and malformed-output diagnostics.
• Confirm existing Markdown AST fact support is sufficient and add/extend fixture coverage where needed rather than adding a text scanner.
• Update docs for managed acquisition, Markdown hook usage, and JSON reporter behavior.
• Add focused Go tests for parser behavior, catalog metadata, managed capture args, hook selection, and Markdown AST facts.

Validation gates:

• Focused Go package tests for diagnostics, tool catalog, hook-runner, managed capture, toolchain CLI, and AST facts.
• make build because this changes hook/runtime/toolchain behavior.
• make check as the canonical repo gate.
• git diff --check.

Commit/publish:

• Commit through bin/coding-ethos-run policy-git only.
• This likely touches protected admin files under pre-commit/; if git.staged_admin_files blocks the commit, I will leave the staged work intact and post an admin handoff with exact validation evidence and commit command.

[paudley]

Stage 1 implementation is prepared and staged, but the policy-managed commit is blocked by protected administrative files.

Worktree: /home/paudley/Active/gmeow/coding-ethos/.worktrees/paudley-88-full-remark-lint-integration
Branch: paudley/88-full-remark-lint-integration
Base: main at 8dc4fab

Implemented:

• Added managed remark-lint catalog support backed by the remark npm binary.
• Added JSON parser coverage for remark/vfile-reporter output, including wrapped files/results, direct arrays, single-file objects, line/column, location.start, place.start, string/numeric severities, fatal, empty output, and malformed output diagnostics.
• Wired policy-remark-lint into the hook registry and markdown hook group.
• Added managed capture argument enforcement for --report json, --use remark-preset-lint-recommended, --frail, --quiet, and --no-color.
• Extended Markdown AST fact detection to .mdx and .markdown.
• Added the managed npm lock package for remark-cli 12.0.1 with remark-lint, remark-preset-lint-recommended, and vfile-reporter-json.
• Updated README, hook runtime docs, and pre-commit docs for the new Markdown hook/toolchain path.
• Fixed a coding-ethos-run test fixture race by installing executable fixtures through a closed temporary file and rename; the full gate was otherwise hitting ETXTBSY in TestManagedLintScopeFromArgsReadsStagedGitFiles.

Validation:

• npm install --package-lock-only --ignore-scripts in pre-commit/hooks/npm-locks/remark-cli-12.0.1 completed with 0 vulnerabilities.
• go test -buildvcs=false ./diagnostics ./toolcatalog ./internal/hookrunnercli ./internal/managedcapture ./internal/toolchaincli ./internal/astfacts passed.
• go test -buildvcs=false -count=1 ./cmd/coding-ethos-run passed after the fixture-race fix.
• make build passed and installed the managed remark wrapper.
• Verified build/toolchain/manifest.tsv contains remark-lint with github-bin/remark and that build/toolchain/github-bin/remark exists and is executable.
• make check passed; it reported only the existing non-blocking testing.go_coverage_goal warning.
• git diff --check passed.

Commit blocker:
bin/coding-ethos-run policy-git commit -m "feat(toolchain): add managed remark-lint integration" is blocked by git.staged_admin_files.

Protected staged files:

• pre-commit/PRE-COMMIT.md
• pre-commit/hooks/managed-toolchain.tsv
• pre-commit/hooks/npm-locks/remark-cli-12.0.1/package-lock.json
• pre-commit/hooks/npm-locks/remark-cli-12.0.1/package.json

Admin handoff command from the worktree:

git commit -m 'feat(toolchain): add managed remark-lint integration'