ci: provision Go guide linter for factory

Author: walker-tx

.github/workflows/factory-ci.yml

@@ -7,8 +7,7 @@ on:
       - 'factory/**'
       - '.github/workflows/guide-draft.yml'
       - '.github/workflows/factory-ci.yml'
-      - 'go/internal/guidecheck/**'
-      - 'go/cmd/lint-guide/**'
+      - 'tools/lint-guide/**'
       - 'FACTORY.md'
       - 'mise.toml'
   push:
@@ -18,8 +17,7 @@ on:
       - 'factory/**'
       - '.github/workflows/guide-draft.yml'
       - '.github/workflows/factory-ci.yml'
-      - 'go/internal/guidecheck/**'
-      - 'go/cmd/lint-guide/**'
+      - 'tools/lint-guide/**'
       - 'FACTORY.md'
       - 'mise.toml'
 
@@ -37,17 +35,24 @@ jobs:
 
       - uses: actions/setup-go@v5
         with:
-          go-version-file: go/go.mod
+          go-version-file: tools/lint-guide/go.mod
+
+      - name: Test guide linter
+        working-directory: tools/lint-guide
+        run: go test ./...
+
+      - name: Build guide linter
+        working-directory: tools/lint-guide
+        run: go build -o "$RUNNER_TEMP/lint-guide" ./cmd/lint-guide
 
       - name: Factory tests
+        env:
+          LINT_GUIDE_BIN: ${{ runner.temp }}/lint-guide
         run: bash factory/tests/run.sh
 
       - name: Shellcheck
         run: shellcheck factory/scripts/*.sh factory/tests/*.sh
 
-      - name: Guidecheck tests
-        working-directory: go
-        run: go test ./internal/guidecheck ./cmd/lint-guide
 
       - name: Build factory image
         run: |

.github/workflows/guide-draft.yml

@@ -25,6 +25,15 @@ jobs:
           fetch-depth: 0
           token: ${{ secrets.AGENT_PAT || secrets.GITHUB_TOKEN }}
 
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+
+      - name: Build guide linter
+        working-directory: tools/lint-guide
+        run: go build -o "$RUNNER_TEMP/lint-guide" ./cmd/lint-guide
+
       - name: Configure runner temp
         run: printf 'TMPDIR=%s\n' "$RUNNER_TEMP" >>"$GITHUB_ENV"
 
@@ -125,6 +134,8 @@ jobs:
       - name: Validate export
         id: validate
         if: success() && steps.refusal.outcome != 'success'
+        env:
+          LINT_GUIDE_BIN: ${{ runner.temp }}/lint-guide
         run: |
           printf '%s\n' 'Factory export validation failed.' >"$RUNNER_TEMP/failure-reason.txt"
           bash factory/scripts/validate.sh "$RUNNER_TEMP/export" "$GITHUB_WORKSPACE"

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

@@ -6,6 +6,28 @@ Rewrite PR #171 so its authoritative guide validator is implemented in Go rather
 
 This port removes the TypeScript guide-linter implementation and linter-only npm dependencies. It does not claim to remove Node or TypeScript from the whole repository: drafting, orchestration, stale sweep, and other pipeline commands remain separate future migrations.
 
+## Reconciliation After the Factory Prerequisite
+
+The prerequisite factory work merged before this branch was finalized and removed the
+remaining TypeScript drafting pipeline. Reconciliation with current `main` therefore
+replaces the temporary TypeScript adapter described below with direct factory consumers;
+the adapter sections remain the approved pre-reconciliation rationale, not the final tree.
+Node 24 remains pinned for repository JavaScript tooling, while the prerequisite removed
+the TypeScript 7 pipeline rather than this port reintroducing obsolete code.
+
+`tools/lint-guide` remains the sole semantic implementation. Factory CI tests and builds
+that nested module. The production guide-draft workflow installs Go 1.22, builds the
+command once to `${{ runner.temp }}/lint-guide`, and exports `LINT_GUIDE_BIN` at job scope.
+`factory/scripts/validate.sh` consumes that binary and falls back to building the same
+nested command for local use. The factory image also builds the nested command and copies
+only the static executable into the runtime image. The public `go` module contains only
+published API and generation code; duplicate checker and CLI packages are removed.
+
+The factory's partial-export contract adds `--meta-only` without changing the original
+human/JSON target, ordering, or `0`/`1`/`2` contracts. The factory coordinator accepts
+exit `0` or `1`, validates exactly one grouped JSON guide result, and flattens only its
+`findings`; exit `2` or malformed output is operational failure.
+
 ## Module Boundary
 
 Create a nested Go module at `tools/lint-guide`:

factory/Dockerfile

@@ -1,9 +1,9 @@
 FROM golang:1.22.12-bookworm@sha256:3d699e4d15d0f8f13c9195c0632a16702b8cbdece2955af1c23b37ae5d55a253 AS lint-builder
 WORKDIR /src
-COPY go/go.mod go/go.sum ./
+COPY tools/lint-guide/go.mod tools/lint-guide/go.sum ./
 RUN go mod download
-COPY go/cmd ./cmd
-COPY go/internal ./internal
+COPY tools/lint-guide/cmd ./cmd
+COPY tools/lint-guide/internal ./internal
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
     go build -trimpath -ldflags='-s -w' -o /out/lint-guide ./cmd/lint-guide
 

factory/coordinator.md

@@ -40,7 +40,7 @@ REVIEWER 1/3 — technical and source accuracy, using `doctrine/roles/technical-
 REVIEWER 2/3 — setup-file and doctrine fidelity, using `doctrine/roles/fidelity.md`.
 REVIEWER 3/3 — editorial clarity and audience fit, using `doctrine/roles/review.md` and the selected persona file.
 
-Each reviewer runs in its own caught boundary with `output_schema` equal to `factory/schemas/review-findings.schema.json` and the universal one-repair protocol. The full concurrent dispatch/collection runs in an enclosing caught boundary. Run the shell/linter in its own caught boundary from `/workspace`, exactly `/usr/local/bin/lint-guide --json /workspace/guides/<slug>`; never invoke `go` or `go run`. Validate parsed linter JSON before use. A completed review wave means valid output from all 3 reviewers plus a successfully parsed linter result. A failed reviewer output, malformed output after repair, linter failure, or invalid linter JSON fails the wave and must not complete the wave and therefore do not increment `review_rounds`; it selects `failed` and routes to reporting.
+Each reviewer runs in its own caught boundary with `output_schema` equal to `factory/schemas/review-findings.schema.json` and the universal one-repair protocol. The full concurrent dispatch/collection runs in an enclosing caught boundary. Run the shell/linter in its own caught boundary from `/workspace`, exactly `/usr/local/bin/lint-guide --json /workspace/guides/<slug>`; never invoke `go` or `go run`. Accept linter exit `0` (clean) or `1` (findings), reject exit `2`, and validate exactly one grouped JSON result whose `guide` is `/workspace/guides/<slug>` and whose `findings` is an array; flatten only that `findings` array for review. A completed review wave means valid output from all 3 reviewers plus a successfully parsed linter result. A failed reviewer output, malformed output after repair, linter invocation failure, or invalid linter JSON fails the wave and must not complete the wave and therefore do not increment `review_rounds`; it selects `failed` and routes to reporting.
 
 Only after a completed review wave increment actual `review_rounds` by one (maximum 3). Normalize semantic duplicates without dropping sources; linter blockers equal reviewer blockers. If there are no blockers, select `converged`. If blockers remain and `review_rounds < 3`, start exactly one revision in a caught boundary with all normalized findings, doctrine, current files, and the selected persona; forbid external research and outside edits. Its strict `output_schema` has only `completed` (boolean), `addressed` (array), and `disputed` (array). Apply one repair and revision completion verification, then always run a confirmatory review wave; a revision can never directly converge. Repeat while capacity remains. If the confirmatory third wave has final-round blockers, select `blocked`; do not revise again. Thus at most three review/revision rounds occur, represented by at most three complete waves, and the report records the actual count.
 

factory/scripts/validate.sh

@@ -15,7 +15,8 @@ backup_dir=
 diff_file=
 untracked_file=
 tree_file=
-lint_bin=
+lint_bin=${LINT_GUIDE_BIN:-}
+lint_owned=false
 anchor_active=false
 target_displaced=false
 new_installed=false
@@ -60,7 +61,7 @@ cleanup_transaction() {
   [[ -z "$diff_file" ]] || rm -f -- "$diff_file" || true
   [[ -z "$untracked_file" ]] || rm -f -- "$untracked_file" || true
   [[ -z "$tree_file" ]] || rm -f -- "$tree_file" || true
-  [[ -z "$lint_bin" ]] || rm -f -- "$lint_bin" || true
+  [[ "$lint_owned" != true || -z "$lint_bin" ]] || rm -f -- "$lint_bin" || true
   exit "$status"
 }
 trap cleanup_transaction EXIT
@@ -161,8 +162,14 @@ validate_artifacts "$guide_dir"
 
 [[ -d "$repo_root/.git" || -f "$repo_root/.git" ]] || fatal "repository root is not a Git worktree"
 if [[ -f "$guide_dir/meta.yaml" ]]; then
-  lint_bin=$(mktemp) || fatal "could not create guide lint executable"
-  (cd "$script_root/go" && go build -o "$lint_bin" ./cmd/lint-guide) || fatal "could not build guide linter"
+  if [[ -n "$lint_bin" ]]; then
+    [[ -x "$lint_bin" ]] || fatal "LINT_GUIDE_BIN is not executable: $lint_bin"
+    lint_bin="$(cd "$(dirname "$lint_bin")" && pwd -P)/$(basename "$lint_bin")"
+  else
+    lint_bin=$(mktemp) || fatal "could not create guide lint executable"
+    lint_owned=true
+    (cd "$script_root/tools/lint-guide" && go build -o "$lint_bin" ./cmd/lint-guide) || fatal "could not build guide linter"
+  fi
 fi
 
 [[ -d "$guides_dir" && ! -L "$guides_dir" ]] || fatal "repository guides path must be a physical directory"

factory/tests/test-container.sh

@@ -25,6 +25,9 @@ test_dockerfile_builds_static_linter_without_go_in_final_image() {
   assert_contains "FROM debian:trixie-slim@sha256:d7e12182ce18b85b93007c1dedf31f2d29e01ccf3182cc4017c709b6259bc132" "$dockerfile"
   assert_contains "CGO_ENABLED=0" "$dockerfile"
   assert_contains "go build" "$dockerfile"
+  assert_contains "COPY tools/lint-guide/go.mod tools/lint-guide/go.sum ./" "$dockerfile"
+  assert_contains "COPY tools/lint-guide/cmd ./cmd" "$dockerfile"
+  assert_contains "COPY tools/lint-guide/internal ./internal" "$dockerfile"
   assert_contains "./cmd/lint-guide" "$dockerfile"
   assert_contains "COPY --from=lint-builder /out/lint-guide /usr/local/bin/lint-guide" "$dockerfile"
   assert_contains "COPY factory/scripts/validate-report.sh /usr/local/bin/validate-report" "$dockerfile"
@@ -40,7 +43,7 @@ test_docker_context_excludes_credentials_and_keeps_build_inputs() {
   grep -Fqx '.git' "$ignore" || fail ".dockerignore does not exclude root .git"
   mkdir -p "$context/nested/.git" "$context/.worktrees/private" \
     "$context/.claude/worktrees/private" "$context/tools/pulse-catalog" \
-    "$context/.tmp-run" "$context/go" "$context/factory/scripts"
+    "$context/.tmp-run" "$context/tools/lint-guide" "$context/factory/scripts"
   printf '%s\n' 'gitdir: /credential-bearing/worktree' >"$context/.git"
   printf '%s\n' credential-bearing-metadata >"$context/nested/.git/config"
   printf '%s\n' secret >"$context/.worktrees/private/token"
@@ -51,8 +54,8 @@ test_docker_context_excludes_credentials_and_keeps_build_inputs() {
   printf '%s\n' secret >"$context/pulse-catalog.json"
   printf '%s\n' secret >"$context/tools/pulse-catalog/pulse-catalog.json"
   printf '%s\n' secret >"$context/.tmp-run/token"
-  cp "$ROOT/go/go.mod" "$ROOT/go/go.sum" "$context/go/"
-  cp -R "$ROOT/go/cmd" "$ROOT/go/internal" "$context/go/"
+  cp "$ROOT/tools/lint-guide/go.mod" "$ROOT/tools/lint-guide/go.sum" "$context/tools/lint-guide/"
+  cp -R "$ROOT/tools/lint-guide/cmd" "$ROOT/tools/lint-guide/internal" "$context/tools/lint-guide/"
   cp "$ROOT/factory/Dockerfile" "$ROOT/factory/config.env" "$context/factory/"
   cp "$ROOT/factory/scripts/validate-report.sh" \
     "$ROOT/factory/scripts/container-entrypoint.sh" "$context/factory/scripts/"
@@ -64,7 +67,7 @@ test_docker_context_excludes_credentials_and_keeps_build_inputs() {
       fail "Docker context contains local-only path: $excluded"
     fi
   done
-  for required in go/go.mod go/go.sum go/cmd/ go/internal/ factory/Dockerfile \
+  for required in tools/lint-guide/go.mod tools/lint-guide/go.sum tools/lint-guide/cmd/ tools/lint-guide/internal/ factory/Dockerfile \
     factory/config.env factory/scripts/validate-report.sh factory/scripts/container-entrypoint.sh; do
     grep -Fq "$required" <<<"$listing" || fail "Docker context excludes required input: $required"
   done

factory/tests/test-contracts.sh

@@ -487,6 +487,19 @@ test_validation_partial_backup_cleanup_failure_keeps_commit() {
   grep -q '^outcome<<' "$VALIDATE_TMP/outputs" || fail "partial cleanup warning suppressed GitHub outputs"
 }
 
+test_validation_uses_supplied_linter_binary() {
+  reset_validation_fixture
+  make_export_report converged
+  copy_valid_guide
+  local supplied="$VALIDATE_TMP/supplied-lint-guide"
+  (cd "$ROOT/tools/lint-guide" && CGO_ENABLED=0 go build -o "$supplied" ./cmd/lint-guide)
+  export REAL_GIT REAL_CP REAL_MV REAL_RM REPO SWAPPED_GUIDES
+  (cd "$VALIDATE_TMP" && \
+    PATH="$VALIDATE_TMP/bin:$PATH" GITHUB_OUTPUT="$VALIDATE_TMP/outputs" \
+    LINT_GUIDE_BIN=supplied-lint-guide "$VALIDATOR" "$EXPORT" "$REPO")
+  [[ -x "$supplied" ]] || fail "validator removed the supplied linter binary"
+}
+
 test_validation_rejects_preexisting_out_of_scope_diff() {
   reset_validation_fixture
   printf 'changed
@@ -515,4 +528,5 @@ test_validation_rejects_staged_nested_and_nonregular_entries
 test_validation_rejects_staged_artifact_mismatch
 test_validation_backup_cleanup_failure_warns_after_commit
 test_validation_partial_backup_cleanup_failure_keeps_commit
+test_validation_uses_supplied_linter_binary
 test_validation_rejects_preexisting_out_of_scope_diff

factory/tests/test-coordinator.sh

@@ -119,6 +119,10 @@ for phrase in \
   'timeout-minutes: 180' \
   '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 build -o "$RUNNER_TEMP/lint-guide" ./cmd/lint-guide' \
+  'LINT_GUIDE_BIN: ${{ runner.temp }}/lint-guide' \
   'contents: write' 'issues: write' 'pull-requests: write' \
   'factory/scripts/preflight.sh' \
   'factory/scripts/prepare-input.sh' \
@@ -367,11 +371,16 @@ if PATH="$workflow_tmp/bin:$PATH" GH_REPO=acme/docs ISSUE_NUMBER=42 \
 fi
 test -s "$COMMENT_STATE" || fail 'bootstrap fallback did not comment after a mutation failure'
 
+# Literal workflow expressions are intentionally matched without expansion.
+# shellcheck disable=SC2016
 for phrase in \
   '.dockerignore' \
   'bash factory/tests/run.sh' \
   'shellcheck factory/scripts/*.sh factory/tests/*.sh' \
-  'go test ./internal/guidecheck ./cmd/lint-guide' \
+  'tools/lint-guide/**' \
+  'go test ./...' \
+  'go build -o "$RUNNER_TEMP/lint-guide" ./cmd/lint-guide' \
+  'LINT_GUIDE_BIN: ${{ runner.temp }}/lint-guide' \
   'KIT_VERSION=0.1.98' \
   'KIT_SHA256=7d14561469ced8af21df1075a9071d04a7bad1b1c5ff90d685142d3231abae85' \
   '-f factory/Dockerfile .'; do