fix: reconcile Go linter with Kit factory

Author: walker-tx

.github/workflows/guide-draft.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Setup Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.22'
+          go-version-file: tools/lint-guide/go.mod
 
       - name: Build guide linter
         working-directory: tools/lint-guide

docs/superpowers/plans/2026-08-27-go-guide-linter-port-implementation.md

@@ -4,12 +4,28 @@
 
 **Goal:** Replace PR #171's TypeScript guide-lint semantics with one parity-tested Go checker in an isolated tools module while preserving current CLI, workflow, doctrine, and guide behavior.
 
-**Architecture:** `tools/lint-guide/internal/guidecheck` owns all validation and a goldmark-based rendered-URL classifier; `tools/lint-guide/cmd/lint-guide` preserves the current grouped human/JSON CLI contract. Remaining TypeScript workflow code calls the Go command through a semantics-free asynchronous process client until the rest of the pipeline is migrated.
+**Architecture:** `tools/lint-guide/internal/guidecheck` owns all validation and a goldmark-based rendered-URL classifier; `tools/lint-guide/cmd/lint-guide` preserves the grouped human/JSON CLI and adds the required `--meta-only` compatibility mode. The live Kit factory builds and consumes this nested command directly through `LINT_GUIDE_BIN`; no TypeScript workflow client remains.
 
-**Tech Stack:** Go 1.22+, goldmark 1.8.5, yaml.v3 3.0.1, jsonschema/v5 5.3.1, Node.js 24, TypeScript 7, `node:test`, and GitHub Actions.
+**Tech Stack:** Go 1.22+, goldmark 1.8.5, yaml.v3 3.0.1, jsonschema/v5 5.3.1, the Kit factory, Node.js 24 for remaining repository JavaScript tooling, and GitHub Actions.
 
 **Spec:** `docs/superpowers/specs/2026-08-27-markdown-url-placement-go-port-design.md`
 
+## Post-Prerequisite Reconciliation
+
+The factory prerequisite series through PR #178 merged before final review. The original task sequence below remains the historical record of the parity-first TypeScript-to-Go cutover, but steps that invoke `pipeline`, its temporary process client, npm tests, or TypeScript typecheck are superseded and are not commands for the final tree.
+
+The authoritative final integration is the Kit factory: production and Factory CI use `go-version-file: tools/lint-guide/go.mod`, build `tools/lint-guide/cmd/lint-guide` once, and pass the runner-temp executable as `LINT_GUIDE_BIN`; the factory image builds the same nested module. `factory/scripts/validate.sh` uses the supplied binary or a local nested-module fallback. The public `go` module contains no duplicate checker.
+
+`--meta-only` is now required for partial factory exports and is covered by checker, CLI, and host-validator regression tests. It preserves grouped human/JSON output and `0`/`1`/`2` exits. Current user invocations are:
+
+```bash
+mise run lint-guide -- asana
+mise run lint-guide -- --json guides/asana
+mise run lint-guide -- --meta-only guides/asana
+```
+
+The resolved-tree acceptance matrix is: tools-module fmt/test/vet/tidy drift; focused CLI and `--meta-only` contracts; all 21 guides; the complete factory suite with `LINT_GUIDE_BIN`; `actionlint` and structural workflow assertions; shellcheck; public Go tests and `go/check.sh`; linux/amd64 factory-image build; deletion/duplication searches; and Git diff/status hygiene.
+
 ## Global Constraints
 
 - Keep all linter dependencies in the nested `tools/lint-guide` module; do not modify the published `go/go.mod` for authoring-tool dependencies.
@@ -19,21 +35,23 @@
 - Exclude real link/image/reference destinations, autolinks, resolved reference syntax, definition labels/destinations, and fenced code; scan prose, labels/alt text, titles, inline/indented code, raw HTML, and unresolved references.
 - Do not add URL suppression, network validation, GFM, or linkify behavior.
 - Never run two authoritative linters in production; TypeScript remains only as a temporary oracle during parity work.
-- Retain Node 24, TypeScript 7, doctrine changes, six migrated guide sources, and generated Go copies already in PR #171.
+- Retain Node 24 for repository JavaScript tooling, doctrine changes, six migrated guide sources, and generated Go copies already in PR #171. The merged prerequisite removed the obsolete TypeScript 7 drafting pipeline; do not reintroduce it.
 
-## File Structure
+## Final Reconciled File Structure
 
-- `tools/lint-guide/go.mod`, `go.sum`: isolated authoring dependencies.
-- `tools/lint-guide/internal/guidecheck/check.go`: file orchestration and all non-URL guide rules.
+- `tools/lint-guide/go.mod`, `go.sum`: isolated authoring dependencies and Go version authority.
+- `tools/lint-guide/internal/guidecheck/check.go`: file orchestration, metadata-only compatibility, and all non-URL guide rules.
 - `tools/lint-guide/internal/guidecheck/markdown.go`: goldmark parsing, source recovery, projection, and URL findings.
-- `tools/lint-guide/internal/guidecheck/*_test.go`: rule and Markdown parity tables.
-- `tools/lint-guide/internal/guidecheck/testdata/`: valid/malformed guide directories and golden findings.
-- `tools/lint-guide/cmd/lint-guide/main.go`: target resolution, output formatting, and exits.
-- `tools/lint-guide/cmd/lint-guide/main_test.go`: CLI contract tests.
-- `pipeline/src/lint-guide-client.ts`: asynchronous Go-process adapter only.
-- `pipeline/src/lint-guide-client.test.ts`: process and JSON/error contract tests.
-- `pipeline/src/workflow.ts`: await the Go client.
-- `pipeline/package.json`, lockfile, `mise.toml`, and Pipeline CI: build/invoke the Go tool and remove linter-only npm dependencies.
+- `tools/lint-guide/internal/guidecheck/*_test.go` and `testdata/`: rule, metadata-only, Markdown parity, and golden finding tests.
+- `tools/lint-guide/cmd/lint-guide/main.go` and `main_test.go`: Mise-facing usage, target resolution, grouped output, `--meta-only`, and exit contracts.
+- `.github/workflows/guide-draft.yml` and `factory-ci.yml`: version-file setup, build-once, and `LINT_GUIDE_BIN` wiring.
+- `factory/scripts/validate.sh`, `factory/Dockerfile`, and factory tests: live host, image, fallback, and compatibility consumers.
+- `mise.toml`: `mise run lint-guide -- ...` developer entry point.
+- `go/cmd/lint-guide` and `go/internal/guidecheck`: absent after duplicate prerequisite implementations were reconciled into the nested tool.
+
+### Historical Pre-Prerequisite Files (Superseded)
+
+The original plan temporarily used `pipeline/src/lint-guide-client.ts`, its process tests, `pipeline/src/workflow.ts`, pipeline package files, and Pipeline CI to bridge TypeScript orchestration to Go. The merged Kit factory deleted that pipeline before final reconciliation; these paths remain in the task history below only to document the parity-first cutover.
 
 ---
 
@@ -642,6 +660,9 @@ Do not delete the historical rationale or falsely rewrite completed history.
 
 - [ ] **Step 2: Run final acceptance verification**
 
+> Historical pre-prerequisite command block: the `pipeline` npm command and its
+> expected typecheck are superseded by the post-prerequisite matrix above.
+
 ```bash
 (cd tools/lint-guide && go test ./... && go vet ./...)
 (cd go && go test ./...)
@@ -657,7 +678,7 @@ git diff --check
 test -z "$(git status --porcelain)"
 ```
 
-Expected: tools/public Go tests pass, 21 guides and zero findings, pipeline tests/typecheck pass, and the worktree is clean after the documentation commit.
+Historical expectation at the time of the original plan: tools/public Go tests, 21 guides with zero findings, and pipeline tests/typecheck. In the reconciled tree, the complete Kit factory suite and workflow checks supersede the deleted pipeline checks; the worktree must still be clean after the documentation commit.
 
 - [ ] **Step 3: Commit documentation**
 
@@ -670,7 +691,7 @@ Rerun `git status --short`; expected output is empty.
 
 - [ ] **Step 4: Update the draft PR**
 
-Update PR #171 without changing its draft state. The title should describe deterministic Go guide linting. The body must summarize the nested module, parity-preserved CLI/workflow cutover, doctrine/guide migration, Node 24/TypeScript 7 baseline retained for remaining pipeline code, and exact final verification counts. Keep the prerequisite merge-order note.
+Update PR #171 without changing its draft state. The title should describe deterministic Go guide linting. The body must summarize the nested module, parity-preserved CLI, live Kit-factory integration, doctrine/guide migration, retained Node 24 tooling pin, superseded TypeScript pipeline, and exact final factory verification count. Keep the prerequisite merge-order history and record that reconciliation completed.
 
 - [ ] **Step 5: Request broad whole-branch review**
 
@@ -685,8 +706,8 @@ Review the complete PR range, not only the last task. Require explicit checks fo
 - [ ] Go and the former TypeScript oracle matched on every committed guide and malformed fixture before deletion.
 - [ ] URL behavior includes rendered entities/escapes/formatting, destination exclusions, unresolved references, non-ASCII byte columns, and linear traversal.
 - [ ] Human/JSON output, target order/resolution, and `0/1/2` exits match the current CLI.
-- [ ] Workflow uses only the semantics-free TypeScript process client.
-- [ ] TypeScript semantic files and linter-only npm dependencies are absent.
+- [ ] Workflow and factory image consume only the nested Go command; no TypeScript process client remains.
+- [ ] TypeScript semantic files, the deleted pipeline, duplicate public-module checker, and linter-only npm dependencies are absent.
 - [ ] Doctrine and all six guide migrations remain intact; generated copies match.
-- [ ] Tools Go tests, public Go checks, pipeline tests/typecheck, all-guide lint, and diff hygiene pass.
+- [ ] Tools Go tests/vet/tidy/fmt, public Go checks, complete factory tests, workflow checks, all-guide lint, Docker build, and diff hygiene pass.
 - [ ] PR #171 remains a draft and documents prerequisite merge ordering.

docs/superpowers/specs/2026-08-27-markdown-url-placement-go-port-design.md

@@ -185,11 +185,23 @@ Exit codes remain:
 - `1`: one or more findings;
 - `2`: usage, help, or unresolved target.
 
-Unknown options continue to be interpreted according to the current argument behavior rather than silently adopting Go's standard `flag` semantics. Factory-specific flat JSON, `--meta-only`, or alternate exit conventions are outside this PR and must be introduced later as explicit modes or separate thin commands.
+Unknown options continue to be interpreted according to the current argument behavior rather than silently adopting Go's standard `flag` semantics. `--meta-only` is now a required compatibility surface for partial Kit-factory exports: it validates `meta.yaml` against the repository schema without requiring published Markdown files, retains grouped human/JSON output, and uses the same `0`/`1`/`2` exit contract. Focused checker, CLI, and host-validator tests cover this mode.
 
-## TypeScript Workflow Adapter
+The supported human entry point and usage text are exactly:
 
-The existing TypeScript drafting workflow currently imports the checker in-process. During this broader repository migration, it calls the Go command through a thin process/JSON adapter with no lint semantics.
+```text
+Usage: mise run lint-guide -- [--json] [--meta-only] <slug|guides/<slug>|path>…
+```
+
+For example, `mise run lint-guide -- asana` checks one guide and `mise run lint-guide -- --json guides/asana` requests grouped JSON.
+
+## TypeScript Workflow Adapter (Historical, Superseded)
+
+> This section records the approved pre-prerequisite cutover. The merged Kit
+> factory removed the TypeScript drafting pipeline and client before final
+> reconciliation; no TypeScript adapter or pipeline check exists in the final tree.
+
+The pre-prerequisite TypeScript drafting workflow imported the checker in-process. During that migration stage, it called the Go command through a thin process/JSON adapter with no lint semantics.
 
 Binary resolution is:
 
@@ -224,9 +236,9 @@ After cutover, delete:
 - `pipeline/src/markdown-url-placement.ts`;
 - `pipeline/src/markdown-url-placement.test.ts`.
 
-Add one small TypeScript process adapter under a name that does not imply semantic ownership, such as `pipeline/src/lint-guide-client.ts`, only while TypeScript workflow orchestration remains.
+The pre-prerequisite plan allowed one small semantics-free TypeScript process adapter only while TypeScript workflow orchestration remained. The merged Kit prerequisite removed that orchestration, so the final reconciled tree contains no adapter or pipeline package.
 
-Remove npm dependencies only after a repository-wide import search proves they are unused. Node 24 and TypeScript 7 standardization remains in PR #171 as previously requested; unrelated TypeScript pipeline tools continue to use that baseline.
+The historical cutover removed linter-only npm dependencies after a repository-wide import search. Node 24 remains pinned for repository JavaScript tooling; the prerequisite removed the obsolete TypeScript 7 drafting pipeline rather than this port reintroducing it.
 
 ## Existing Content Migration
 
@@ -247,7 +259,7 @@ Add focused tools-module checks:
 cd tools/lint-guide && go test ./...
 ```
 
-The pipeline workflow builds the command once before TypeScript tests and exports `LINT_GUIDE_BIN`. Mise's `lint-guide` task invokes the built Go command while preserving current examples. CI continues to run Node/TypeScript checks for remaining pipeline code and Go checks for both the public module and nested linter module.
+The live Kit integration builds the nested command once. `guide-draft.yml` uses `actions/setup-go@v5` with `go-version-file: tools/lint-guide/go.mod`, writes the executable to `${{ runner.temp }}/lint-guide`, and supplies it to export validation through `LINT_GUIDE_BIN`. Factory CI uses the same module version file, tests and builds the command, and supplies the binary to the complete factory suite. The factory image builds the nested module into `/usr/local/bin/lint-guide`; local validation falls back to building that same command. Mise invokes `go run ./cmd/lint-guide` from `tools/lint-guide`.
 
 The command must not require network access at runtime. Dependencies are resolved only during module download/build.
 
@@ -257,7 +269,7 @@ The command must not require network access at runtime. Dependencies are resolve
 - Operational file/process/configuration failures are returned errors and produce usage/runtime failure rather than partial findings.
 - JSON output is never mixed with human diagnostics on stdout.
 - Human diagnostics and usage text go to stderr where the current contract requires it.
-- The TypeScript adapter includes stderr in operational errors but does not expose environment contents or credentials.
+- Factory consumers validate grouped JSON and preserve stderr for operational errors without exposing environment contents or credentials.
 - No ignore or suppression mechanism is added for URL placement.
 
 ## Verification and Acceptance
@@ -269,18 +281,19 @@ The port is accepted only when all of the following pass:
 - Go CLI contract and exit-code tests;
 - temporary TypeScript-to-Go parity fixtures;
 - all committed guides with zero findings;
-- existing pipeline tests and TypeScript typecheck;
-- `go test ./...` in `tools/lint-guide`;
+- the complete Kit factory regression suite with the prebuilt `LINT_GUIDE_BIN`;
+- workflow structural checks, `actionlint`, and changed-script `shellcheck`;
+- `go test ./...` and `go vet ./...` in `tools/lint-guide`;
 - `go test ./...` in `go`;
 - `go/check.sh` generation, formatting, vet, and tests;
 - source/generated guide parity;
 - `git diff --check`;
 - final whole-branch review.
 
-The final PR tree contains one authoritative Go semantic checker, one temporary semantics-free TypeScript client for the remaining workflow, and no TypeScript guide-lint rules.
+The final reconciled PR tree contains one authoritative Go semantic checker, direct Kit-factory consumers, and no TypeScript client, pipeline package, duplicate public-module checker, or TypeScript guide-lint rules.
 
 ## Rollout and Compatibility
 
-PR #171 remains a draft until prerequisite work identified by the author has merged. This port is implemented directly on PR #171 rather than stacked on the local `feat/kit-guide-factory` branch. After any prerequisite merge, rebase or merge conflict resolution must rerun the full parity and acceptance matrix.
+The prerequisite factory series through PR #178 has merged. PR #171 remains draft while its rebased reconciliation and checks complete. Every prerequisite merge and rebase reruns the resolved-tree acceptance matrix.
 
-If a later factory migration introduces a different Go CLI protocol, preserve both consumer contracts through explicit modes or thin adapters first. Protocol consolidation is a separate design and must not silently change this PR's human/Mise contract.
+The live factory protocol preserves the human/Mise contract and adds the explicit `--meta-only` compatibility mode. Any later protocol consolidation must preserve both surfaces or introduce a tested thin adapter rather than silently changing either consumer.

factory/tests/test-coordinator.sh

@@ -123,7 +123,7 @@ for phrase in \
   'group: guide-draft-issue-${{ github.event.issue.number }}' \
   'cancel-in-progress: false' 'TMPDIR=%s\n' \
   'uses: actions/setup-go@v5' \
-  "go-version: '1.22'" \
+  'go-version-file: tools/lint-guide/go.mod' \
   'go build -o "$RUNNER_TEMP/lint-guide" ./cmd/lint-guide' \
   'LINT_GUIDE_BIN: ${{ runner.temp }}/lint-guide' \
   'contents: write' 'issues: write' 'pull-requests: write' \

tools/lint-guide/cmd/lint-guide/main.go

@@ -10,7 +10,7 @@ import (
 	"github.com/speakeasy-api/mcp-setup-docs/tools/lint-guide/internal/guidecheck"
 )
 
-const usageText = "Usage: npm run lint-guide -- [--json] [--meta-only] <slug|guides/<slug>|path>…"
+const usageText = "Usage: mise run lint-guide -- [--json] [--meta-only] <slug|guides/<slug>|path>…"
 
 type guideResult struct {
 	Guide    string               `json:"guide"`

tools/lint-guide/cmd/lint-guide/main_test.go

@@ -42,7 +42,7 @@ func TestUsageAndHelp(t *testing.T) {
 			if got.stdout != "" {
 				t.Fatalf("stdout = %q, want empty", got.stdout)
 			}
-			if got.stderr != "Usage: npm run lint-guide -- [--json] [--meta-only] <slug|guides/<slug>|path>…\n" {
+			if got.stderr != "Usage: mise run lint-guide -- [--json] [--meta-only] <slug|guides/<slug>|path>…\n" {
 				t.Fatalf("stderr = %q", got.stderr)
 			}
 		})