froid-plane-test-architecture-enterprise 1.23.4

package/.github/workflows/quality.yaml

@@ -0,0 +1,171 @@
+name: Quality & Validation
+
+# Runs comprehensive quality checks on all PRs:
+# - Prettier (formatting)
+# - ESLint (linting)
+# - markdownlint (markdown quality)
+# - Schema validation (YAML structure)
+# - Agent schema tests (fixture-based validation)
+# - Installation component tests (compilation)
+#
+# The `validate` job must stay a superset of `npm test`'s non-lint half. Three
+# suites used to run ONLY from .husky/pre-commit — test:knowledge, test:changelog,
+# and test:tea-workflow-descriptions — and `git commit --no-verify` skips that
+# hook, as does every edit made through the GitHub web UI. test:knowledge is the
+# one carrying the knowledge-copy parity check across the eight froid-testarch workflows, so for as long as it was
+# absent here nothing in CI stopped the workflow copies of the knowledge base from
+# silently diverging from the agent's.
+#
+# test:cli is the deliberate exception in the other direction: it runs here and
+# NOT in `npm test`, because it takes ~12 minutes (measured: 12m21s) and `npm test`
+# runs on every commit through the pre-commit hook.
+
+"on":
+  pull_request:
+    branches: ["**"]
+  workflow_dispatch:
+
+jobs:
+  prettier:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Prettier format check
+        run: npm run format:check
+
+  eslint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: ESLint
+        run: npm run lint
+
+  markdownlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: markdownlint
+        run: npm run lint:md
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate documentation links
+        run: npm run docs:validate-links
+
+      - name: Build documentation
+        run: npm run docs:build
+
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate YAML schemas
+        run: npm run validate:schemas
+
+      - name: Run agent schema validation tests
+        run: npm run test:schemas
+
+      - name: Validate release metadata
+        run: npm run test:release-metadata
+
+      - name: Test agent compilation components
+        run: npm run test:install
+
+      - name: Test knowledge base (index sync, link resolution, workflow-copy parity)
+        run: npm run test:knowledge
+
+      - name: Validate criteria-registry to fragment traceability
+        run: npm run test:criteria-fragments
+
+      - name: Test write-time enforcement hook
+        run: npm run test:enforce-hook
+
+      - name: Validate fragment-selection eval data
+        run: npm run test:eval-data
+
+      - name: Test changelog stamping
+        run: npm run test:changelog
+
+      - name: Validate TEA workflow descriptions
+        run: npm run test:tea-workflow-descriptions
+
+  # Split out of `validate` on its own: it takes ~12 minutes, and leaving it in
+  # line meant every fast check behind it reported 12 minutes late.
+  cli:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          # This job only reads. actions/checkout persists the job token in
+          # .git/config by default, where any step or test process could read it.
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Test TEA test-review CLI
+        run: npm run test:cli

package/.github/workflows/tea-test-review.yaml

@@ -0,0 +1,240 @@
+# Dogfoods tea-test-review on this repo's own test suite (test/*.js). Unlike
+# cli/examples/pr-test-review.yml, this repo IS the skill source, so it points
+# --skill-root at src/workflows/testarch/froid-testarch-test-review directly
+# instead of installing a pinned npm tarball.
+#
+# NOT YET ENABLED: no ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN repository
+# secret exists yet, so the agent-running steps below are commented out and
+# the trigger is workflow_dispatch only, not pull_request. A run without
+# either secret would just fail and post a confusing "infrastructure failure"
+# comment on every real PR.
+#
+# To enable: add one of the two secrets, uncomment the "Install the pinned
+# agent CLI" and "Run headless test review" steps, and switch `on:` back to
+# `pull_request: { types: [opened, synchronize, reopened] }`.
+#   - ANTHROPIC_API_KEY: pay-per-token via the Anthropic Console.
+#   - CLAUDE_CODE_OAUTH_TOKEN: a long-lived token from an existing Claude
+#     subscription, generated locally with `claude setup-token`. No separate
+#     API billing. Already supported by cli/lib/run-agent.js's env allowlist.
+#
+# Honest limitation: forks receive no secrets, so the review skips for fork
+# PRs (the fork guard below) rather than failing. A skipped required check
+# still satisfies branch protection, so this cannot be the sole gate against
+# untrusted external contributions; see cli/examples/pr-test-review.yml's
+# header comment for the same caveat.
+name: TEA Test Review
+
+on:
+  workflow_dispatch: {}
+
+permissions: {}
+
+jobs:
+  review:
+    name: Headless test review
+    runs-on: ubuntu-latest
+    # Self-adapting fork guard: on workflow_dispatch there's no pull_request
+    # context to check, so this is trivially true; on pull_request it skips
+    # forks (no secrets there). No change needed when switching triggers back.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    permissions:
+      contents: read
+    outputs:
+      verdict: ${{ steps.verdict.outputs.verdict }}
+    steps:
+      - name: Checkout (full history for the PR diff)
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version-file: ".nvmrc"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      # - name: Install the pinned agent CLI
+      #   env:
+      #     CLAUDE_CODE_VERSION: 2.1.220
+      #   run: npm install --global "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+
+      # - name: Run headless test review
+      #   id: run-review
+      #   env:
+      #     ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      #     # or: CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      #     BASE_REF: origin/${{ github.base_ref }}
+      #   run: node cli/test-review.js --base "$BASE_REF" --agent claude --skill-root src/workflows/testarch/froid-testarch-test-review --test-dir test --output test-review.md --json test-review.json
+
+      - name: Upload review artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tea-test-review
+          path: |
+            test-review.md
+            test-review.json
+
+      - name: Export the verdict as a job output
+        id: verdict
+        if: always()
+        env:
+          REVIEW_OUTCOME: ${{ steps.run-review.outcome }}
+        run: |
+          verdict="failed"
+          if [ "$REVIEW_OUTCOME" = "success" ]; then
+            verdict="passed"
+          fi
+          echo "verdict=$verdict" >> "$GITHUB_OUTPUT"
+
+  comment:
+    name: Comment the outcome
+    needs: review
+    # Only meaningful with a PR to comment on; skips cleanly on workflow_dispatch.
+    if: always() && github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Download review artifacts
+        id: download
+        uses: actions/download-artifact@v4
+        continue-on-error: true
+        with:
+          name: tea-test-review
+
+      - name: Find-and-update the review comment
+        uses: actions/github-script@v7
+        env:
+          DOWNLOAD_OUTCOME: ${{ steps.download.outcome }}
+          REVIEW_RESULT: ${{ needs.review.result }}
+          REVIEW_VERDICT: ${{ needs.review.outputs.verdict }}
+        with:
+          # Kept in sync by hand with cli/examples/pr-test-review.yml's
+          # "Find-and-update the review comment" step: same comment-building
+          # logic, duplicated because that file is a standalone copy-paste
+          # template for other repos and cannot depend on this one.
+          script: |
+            const fs = require("fs");
+            const marker = "<!-- tea-test-review -->";
+            const artifactsUrl = `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}#artifacts`;
+            // GitHub caps a comment body at 65536 chars; this leaves headroom
+            // for the digest and wrapper around the inlined report.
+            const MAX_INLINE_REPORT_CHARS = 40000;
+
+            let body = null;
+            const artifactAvailable = process.env.DOWNLOAD_OUTCOME === "success" && fs.existsSync("test-review.json");
+            if (artifactAvailable) {
+              try {
+                const verdict = JSON.parse(fs.readFileSync("test-review.json", "utf8"));
+                if (verdict.skipped) {
+                  body = [
+                    marker,
+                    "## TEA Test Review: skipped",
+                    "",
+                    `${verdict.reason ?? "No changed test files in this PR"}.`,
+                    "",
+                    `[Review job artifacts](${artifactsUrl})`,
+                  ].join("\n");
+                } else {
+                  const counts = verdict.violations ?? {};
+                  const violations = `${counts.critical ?? 0} Critical / ${counts.high ?? 0} High / ${counts.medium ?? 0} Medium / ${counts.low ?? 0} Low`;
+                  const weaknesses = (verdict.keyWeaknesses ?? []).slice(0, 3);
+                  // Named, not just counted: a finding that cites "line 200" is
+                  // unattributable on a PR touching more than one test file.
+                  const reviewed = Array.isArray(verdict.reviewedFiles) ? verdict.reviewedFiles : [];
+                  const markdownCodeSpan = (value) => {
+                    const text = String(value);
+                    const longestBacktickRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+                    const fence = "`".repeat(longestBacktickRun + 1);
+                    const padding = text.startsWith("`") || text.endsWith("`") ? " " : "";
+                    return `${fence}${padding}${text}${padding}${fence}`;
+                  };
+
+                  const lines = [
+                    marker,
+                    `## TEA Test Review: ${verdict.recommendation}`,
+                    "",
+                    `- **Quality score**: ${verdict.qualityScore ?? "n/a"}/100`,
+                    `- **Recommendation**: ${verdict.recommendation}`,
+                    `- **Violations**: ${violations}`,
+                    `- **Reviewed files**: ${reviewed.length}`,
+                    ...reviewed.slice(0, 10).map((f) => `  - ${markdownCodeSpan(f)}`),
+                    ...(reviewed.length > 10 ? [`  - … and ${reviewed.length - 10} more`] : []),
+                  ];
+                  if (weaknesses.length > 0) {
+                    lines.push("", "**Key weaknesses**:", ...weaknesses.map((w) => `- ${w}`));
+                  }
+                  lines.push("");
+
+                  // Inline the full report (not just the digest above) so a
+                  // reviewer can paste it straight into an AI coding agent to
+                  // apply the fixes, no artifact download required. Falls back
+                  // to the artifact link alone if the report is too large or
+                  // missing from the download.
+                  const reportText = fs.existsSync("test-review.md") ? fs.readFileSync("test-review.md", "utf8") : null;
+                  if (reportText && reportText.length <= MAX_INLINE_REPORT_CHARS) {
+                    // A reviewed file's own content can contain a literal
+                    // </details>; inserting a zero-width space breaks that as
+                    // an HTML closing tag while leaving the visible text
+                    // effectively unchanged, so it cannot end this block early
+                    // and spill raw markdown into the rest of the comment.
+                    const safeReportText = reportText.replace(/<\/details>/gi, "<\u200B/details>");
+                    lines.push(
+                      "<details>",
+                      "<summary>Full report (paste into your AI coding agent to apply the fixes)</summary>",
+                      "",
+                      safeReportText,
+                      "",
+                      "</details>",
+                      "",
+                      `[Verdict JSON](${artifactsUrl})`,
+                    );
+                  } else {
+                    lines.push(`[Full report and verdict JSON](${artifactsUrl})`);
+                  }
+                  body = lines.join("\n");
+                }
+              } catch {
+                body = null;
+              }
+            }
+            if (body === null) {
+              body = [
+                marker,
+                "## TEA Test Review: infrastructure failure",
+                "",
+                "The review job did not produce a readable verdict artifact.",
+                "This is **not** a review verdict; treat the gate as broken, not as approved tests.",
+                "",
+                `Review job result: ${process.env.REVIEW_RESULT} (verdict output: ${process.env.REVIEW_VERDICT || "n/a"}).`,
+                `[Review job artifacts](${artifactsUrl})`,
+              ].join("\n");
+            }
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+            const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

package/.husky/pre-commit

@@ -0,0 +1,20 @@
+#!/usr/bin/env sh
+
+# Auto-fix changed files and stage them
+npx --no-install lint-staged
+
+# Validate everything
+npm test
+
+# Validate docs links only when docs change
+if command -v rg >/dev/null 2>&1; then
+  if git diff --cached --name-only | rg -q '^docs/'; then
+    npm run docs:validate-links
+		npm run docs:build
+  fi
+else
+  if git diff --cached --name-only | grep -Eq '^docs/'; then
+    npm run docs:validate-links
+		npm run docs:build
+  fi
+fi

package/.markdownlint-cli2.yaml

@@ -0,0 +1,36 @@
+# markdownlint-cli2 configuration
+# https://github.com/DavidAnson/markdownlint-cli2
+
+ignores:
+  - node_modules/**
+  - website/node_modules/**
+  - test/fixtures/**
+  - CODE_OF_CONDUCT.md
+  - _froid/**
+  - _froid*/**
+  - .*/**
+  - z*/**
+
+# Rule configuration
+config:
+  # Disable all rules by default
+  default: false
+
+  # Heading levels should increment by one (h1 -> h2 -> h3, not h1 -> h3)
+  MD001: true
+
+  # Duplicate sibling headings (same heading text at same level under same parent)
+  MD024:
+    siblings_only: true
+
+  # Trailing commas in headings (likely typos)
+  MD026:
+    punctuation: ","
+
+  # Bare URLs - may not render as links in all parsers
+  # Should use <url> or [text](url) format
+  MD034: true
+
+  # Spaces inside emphasis markers - breaks rendering
+  # e.g., "* text *" won't render as emphasis
+  MD037: true

package/.nvmrc

@@ -0,0 +1 @@
+22

package/.prettierignore

@@ -0,0 +1,9 @@
+# Test fixtures with intentionally broken/malformed files
+test/fixtures/**
+
+# Contributor Covenant (external standard)
+CODE_OF_CONDUCT.md
+
+# FROID runtime folders (user-specific, not in repo)
+_froid/
+_froid*/

package/.vscode/settings.json

@@ -0,0 +1,47 @@
+{
+  "chat.agent.enabled": true,
+  "chat.agent.maxRequests": 15,
+  "github.copilot.chat.agent.runTasks": true,
+  "chat.mcp.discovery.enabled": {
+    "claude-desktop": true,
+    "windsurf": true,
+    "cursor-global": true,
+    "cursor-workspace": true
+  },
+  "github.copilot.chat.agent.autoFix": true,
+  "chat.tools.autoApprove": false,
+  "cSpell.words": ["Agentic", "atdd", "froid", "Decisioning", "Playwright", "solutioning", "testarch", "webskip"],
+  "json.schemas": [
+    {
+      "fileMatch": ["package.json"],
+      "url": "https://json.schemastore.org/package.json"
+    },
+    {
+      "fileMatch": [".vscode/settings.json"],
+      "url": "vscode://schemas/settings/folder"
+    }
+  ],
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "[javascript]": {
+    "editor.defaultFormatter": "vscode.typescript-language-features"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "vscode.json-language-features"
+  },
+  "[yaml]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[markdown]": {
+    "editor.defaultFormatter": "yzhang.markdown-all-in-one"
+  },
+  "yaml.format.enable": false,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "editor.rulers": [140],
+  "[xml]": {
+    "editor.defaultFormatter": "redhat.vscode-xml"
+  },
+  "xml.format.maxLineWidth": 140
+}

package/AGENTS.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Shape
+
+- Core TEA module content lives in `src/`.
+- Public documentation lives in `docs/`; the Starlight site consumes it through `website/`.
+- GitHub Actions workflows live in `.github/workflows/`.
+- Release metadata must stay synchronized across `package.json`, `package-lock.json`, and `.claude-plugin/marketplace.json`.
+
+## Common Commands
+
+- `npm test`: full quality gate used before release.
+- `npm run format:check`: Prettier check.
+- `npm run lint`: ESLint check.
+- `npm run lint:md`: markdownlint check.
+- `npm run docs:validate-links`: docs link validation.
+- `npm run docs:build`: full docs and site build.
+- `npm run test:release-metadata`: package/lockfile/marketplace version sync check.
+
+## Changelog Discipline
+
+- For any user-facing change, documentation change, workflow/CI change, release behavior change, or bug fix, update `CHANGELOG.md` in the same PR.
+- Put unreleased work under the top `## [Unreleased]` section using Keep a Changelog headings such as `Added`, `Changed`, `Fixed`, `Deprecated`, or `Removed`.
+- Stable releases convert `[Unreleased]` into a dated version section on their own. The publish workflow runs `node tools/stamp-changelog.js` after the version bump and commits the result, so do not hand-write a `## [1.16.0] - YYYY-MM-DD` heading in a normal PR. Writing entries under `[Unreleased]` is the whole job.
+- Keep the `## [Unreleased]` heading present. The stamping step targets it and fails the release if it is gone.
+- Repairing history is the one case for editing a version section by hand, for example when an earlier release shipped without notes.
+
+## PR Notes
+
+- Mention validation commands actually run.
+- For docs-only changes, at minimum run `npm run docs:validate-links`, `npm run lint:md`, and `npm run format:check`.
+- For workflow or release changes, run `npm run format:check`, `npm run lint:md`, `npm run lint`, and `npm run test:release-metadata`.