create-anpunkit 2.1.0 → 2.3.0

package/template/knowledge/webapp.md

@@ -0,0 +1,265 @@
+# knowledge/webapp.md — matured web-app practice (preinstalled)
+
+> **What this file is.** Use-case knowledge for browser-facing web apps,
+> consulted by `researcher` (STEP 0.5) when `knowledge/webapp.md` appears in
+> the `knowledge_docs:` list of `docs/OVERVIEW.md`. Selection is deterministic
+> — declared at `/overview`, never inferred (hard rule 10).
+>
+> **Templates below are materialized per-project** — copied to the stated path
+> the first time the phase work needs them. Once materialized they are
+> user-owned project files: adjust freely, the kit never overwrites them.
+
+## Browser boundary practice (E2E_KIND: browser)
+
+- `ui` spec cases carry a `fixtures/<case-id>-ui.json` descriptor with a
+  closed, kit-versioned assert vocabulary: `visible`, `text-equals`,
+  `enabled`, `count`. `e2e-runner` EMITS Playwright specs from descriptors —
+  it never authors blind from prose.
+- Each emitted spec block carries a `// spec: <case-id>` citation
+  (`spec-conformance.sh` checks it).
+- EVIDENCE (hard rule 13): at each UI-existence assertion, capture a
+  screenshot regardless of pass/fail to
+  `docs/evidence/e2e-phase-<n>/<case-id>-<element-slug>.png` — one shot per
+  asserted element, on green as well as red.
+- `ui` cases have NO mock mirror — the browser IS the boundary.
+
+## E2E stack ritual
+
+Two target modes, recorded in `docs/INFRA.md`:
+
+- **azure-deployed** (`E2E_STACK_EXTERNAL=1` in `.env.test`): tests hit the
+  deployed app; `e2e-stack.sh up` only health-checks reachability.
+- **local-docker**: `e2e-stack.sh up` builds + starts the compose stack and
+  polls health.
+
+Sequence, always: `bash scripts/e2e-stack.sh up` -> `npx playwright test` ->
+`bash scripts/e2e-stack.sh down`. Stack didn't come up -> classify
+**STACK NOT READY** (not a bug; no debug budget).
+
+## Web deploy ritual (DEPLOY_KIND: cloud-deploy)
+
+- Deploy task lives in the final phase (DEPLOY_KIND completion, hard rules).
+- After deploy: record the deployed base URL in `docs/INFRA.md`
+  (`## Deployed base URL`) and confirm `docs/ENDPOINTS.md` entries resolve
+  against it; run a `/health` (or equivalent) check before calling it done.
+
+## .gitignore lines a materialized stack needs
+
+```
+e2e/.auth/
+playwright-report/
+test-results/
+```
+
+---
+
+## Templates
+
+### `playwright.config.ts` — materialize to project root
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  globalSetup: './e2e/global-setup.ts',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 1 : 0,
+  workers: 1,
+  reporter: [['list'], ['html', { open: 'never' }]],
+  use: {
+    baseURL: process.env.E2E_BASE_URL || 'http://localhost:8080',
+    storageState: 'e2e/.auth/state.json',
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    actionTimeout: 15_000,
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+  ],
+  webServer: process.env.E2E_STACK_EXTERNAL ? undefined : {
+    command: 'bash scripts/e2e-stack.sh up',
+    url: process.env.E2E_BASE_URL || 'http://localhost:8080',
+    timeout: 180_000,
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+### `e2e/global-setup.ts` — materialize to `e2e/`
+
+Entra ID ROPC token injection (Azure/MSAL apps — see `knowledge/azure.md` for
+the auth practice). Known gap: the localStorage keys (`e2e.access_token`,
+`e2e.id_token`) are a stub convention — align them with your app's real MSAL
+cache keys when materializing.
+
+```ts
+// e2e/global-setup.ts
+import { chromium } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const AUTH_DIR = path.join(__dirname, '.auth');
+const STATE = path.join(AUTH_DIR, 'state.json');
+
+async function fetchRopcToken() {
+  const tenant = reqEnv('E2E_TENANT_ID');
+  const body = new URLSearchParams({
+    grant_type: 'password',
+    client_id: reqEnv('E2E_CLIENT_ID'),
+    username: reqEnv('E2E_TEST_USER'),
+    password: reqEnv('E2E_TEST_PASSWORD'),
+    scope: `openid profile ${reqEnv('E2E_SCOPE')}`,
+  });
+  const url = `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+  if (!res.ok) {
+    const txt = await res.text();
+    throw new Error(
+      `ROPC token fetch failed (${res.status}). ` +
+      `Check: ROPC enabled on app registration, test user exists, ` +
+      `MFA excluded via Conditional Access. Response: ${txt}`
+    );
+  }
+  return res.json() as Promise<{ access_token: string; id_token: string; expires_in: number }>;
+}
+
+function reqEnv(k: string): string {
+  const v = process.env[k];
+  if (!v) throw new Error(`Missing env ${k} — run /infra to regenerate .env.test`);
+  return v;
+}
+
+async function globalSetup() {
+  fs.mkdirSync(AUTH_DIR, { recursive: true });
+  const token = await fetchRopcToken();
+  const baseURL = reqEnv('E2E_BASE_URL');
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(baseURL);
+  await page.evaluate((t) => {
+    localStorage.setItem('e2e.access_token', t.access_token);
+    localStorage.setItem('e2e.id_token', t.id_token);
+  }, token);
+  await page.context().storageState({ path: STATE });
+  await browser.close();
+  console.log('E2E auth ready — real Entra token injected, MFA UI bypassed.');
+}
+
+export default globalSetup;
+```
+
+### `docker-compose.test.yml` — materialize to project root
+
+```yaml
+# docker-compose.test.yml — E2E test stack (local-docker mode).
+# TEMPLATE — adjust build contexts and ports for your project layout.
+services:
+  backend:
+    build:
+      context: ./backend          # <-- adjust
+    environment:
+      SQL_SERVER: ${E2E_SQL_SERVER}
+      SQL_DB: ${E2E_SQL_DB}
+      SQL_USER: ${E2E_SQL_USER}
+      SQL_PASSWORD: ${E2E_SQL_PASSWORD}
+      TENANT_ID: ${E2E_TENANT_ID}
+      CLIENT_ID: ${E2E_CLIENT_ID}
+      STORAGE_CONN: ${E2E_STORAGE_CONN:-}
+    ports:
+      - "8081:8081"
+    healthcheck:
+      test: ["CMD", "curl", "-fs", "http://localhost:8081/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 12
+
+  webapp:
+    build:
+      context: ./frontend         # <-- adjust
+    environment:
+      API_BASE_URL: http://backend:8081
+      TENANT_ID: ${E2E_TENANT_ID}
+      CLIENT_ID: ${E2E_CLIENT_ID}
+    ports:
+      - "8080:80"
+    depends_on:
+      backend:
+        condition: service_healthy
+```
+
+### `scripts/e2e-stack.sh` — materialize to `scripts/`
+
+```bash
+#!/usr/bin/env bash
+# scripts/e2e-stack.sh — E2E test stack lifecycle.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+CMD="${1:-}"
+COMPOSE="docker-compose.test.yml"
+ENVFILE=".env.test"
+
+[ -f "$ENVFILE" ] || { echo "missing $ENVFILE — run /infra to generate it"; exit 1; }
+set -a; . "./$ENVFILE"; set +a
+
+if [ "${E2E_STACK_EXTERNAL:-}" = "1" ]; then
+  echo "[e2e-stack] E2E_STACK_EXTERNAL=1 — targeting deployed Azure app at ${E2E_BASE_URL:-<unset>}"
+  case "$CMD" in
+    up)
+      echo "[e2e-stack] Verifying Azure app is reachable..."
+      for i in $(seq 1 10); do
+        if curl -fs "${E2E_BASE_URL:-http://localhost:8080}/health" >/dev/null 2>&1 \
+        || curl -fs "${E2E_BASE_URL:-http://localhost:8080}" >/dev/null 2>&1; then
+          echo "[e2e-stack] Azure app reachable."
+          exit 0
+        fi
+        sleep 3
+      done
+      echo "[e2e-stack] WARNING: Azure app not reachable. Classify as AZURE UNAVAILABLE."
+      exit 1
+      ;;
+    down)
+      echo "[e2e-stack] External mode — nothing to stop."
+      exit 0
+      ;;
+    *)
+      echo "usage: e2e-stack.sh up|down"
+      exit 1
+      ;;
+  esac
+fi
+
+if docker compose version >/dev/null 2>&1; then DC="docker compose"; else DC="docker-compose"; fi
+
+case "$CMD" in
+  up)
+    echo "[e2e-stack] building + starting local app containers..."
+    $DC -f "$COMPOSE" --env-file "$ENVFILE" up -d --build
+    for i in $(seq 1 30); do
+      if curl -fs "${E2E_BASE_URL:-http://localhost:8080}" >/dev/null 2>&1; then
+        echo "[e2e-stack] up."
+        exit 0
+      fi
+      sleep 3
+    done
+    echo "[e2e-stack] ERROR: app did not become healthy — STACK NOT READY"
+    exit 1
+    ;;
+  down)
+    echo "[e2e-stack] stopping local containers..."
+    $DC -f "$COMPOSE" --env-file "$ENVFILE" down
+    echo "[e2e-stack] down."
+    ;;
+  *)
+    echo "usage: e2e-stack.sh up|down"
+    exit 1
+    ;;
+esac
+```

package/template/scripts/spec-conformance.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# spec-conformance.sh — block GREEN until the phase spec is fully filled and every
+# case is verified by a boundary test (v2.2). Runs between RED and GREEN, replacing
+# the v2.1 human TEST REVIEW gate. (§5.55, rule 18)
+#
+# Two checks, both loud-fail (nonzero), no side effects:
+#   1. NO `TBD` remains in docs/spec-phase-<n>.md or any fixture it references.
+#   2. EVERY case-id in the spec table is cited by a test via `# spec: <case-id>`
+#      (or `// spec: <case-id>`) under tests/ or e2e/.
+#
+#   bash scripts/spec-conformance.sh <phase-n>
+#
+# The case→test citation here, plus the placement convention (contract/transition
+# tests live in tests/regression/), is what closes the rule-14 chain: reachable
+# transition → filled case (rule 14) → cited boundary test (this) → regression corpus.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+N="${1:-}"
+[ -n "$N" ] || { echo "spec-conformance: usage: spec-conformance.sh <phase-n>" >&2; exit 2; }
+
+SPEC="docs/spec-phase-${N}.md"
+[ -f "$SPEC" ] || { echo "spec-conformance: $SPEC not found." >&2; exit 2; }
+
+FAIL=0
+
+# ---- 1. no TBD left in the spec ----
+if grep -nE '\bTBD\b' "$SPEC" >/dev/null 2>&1; then
+  echo "spec-conformance: FAIL — unfilled 'TBD' marker(s) remain in $SPEC:" >&2
+  grep -nE '\bTBD\b' "$SPEC" | sed 's/^/    /' >&2
+  echo "  Every case must be filled (or escalated as CASE-SET-DIVERGENCE) before GREEN." >&2
+  FAIL=1
+fi
+
+# ---- referenced fixtures: must exist + carry no TBD ----
+FIXREFS="$(grep -oE 'fixtures/[A-Za-z0-9_./-]+\.json' "$SPEC" | sort -u || true)"
+if [ -n "$FIXREFS" ]; then
+  while IFS= read -r fx; do
+    [ -n "$fx" ] || continue
+    if [ ! -f "$fx" ]; then
+      echo "spec-conformance: FAIL — referenced fixture missing: $fx" >&2
+      FAIL=1
+    elif grep -nE '\bTBD\b' "$fx" >/dev/null 2>&1; then
+      echo "spec-conformance: FAIL — 'TBD' marker in fixture: $fx" >&2
+      FAIL=1
+    fi
+  done <<EOF
+$FIXREFS
+EOF
+fi
+
+# ---- 2. every case-id cited by a boundary test ----
+# case-ids = the FIRST table-column cell of each row, matching PH<n>-... exactly.
+# (Parse the column, not a free grep — else `fixtures/PH1-ORDER-01-input.json`
+#  would yield a bogus `PH1-ORDER-01-input` case-id.)
+CASE_IDS="$(grep -E '^\|' "$SPEC" \
+  | awk -F'|' '{ id=$2; gsub(/^[ \t]+|[ \t]+$/,"",id); print id }' \
+  | grep -E "^PH${N}-[A-Za-z0-9_-]+$" | sort -u || true)"
+if [ -z "$CASE_IDS" ]; then
+  echo "spec-conformance: WARN — no PH${N}-* case-ids found in $SPEC (empty spec?)." >&2
+fi
+
+SEARCH_DIRS=""
+[ -d tests ] && SEARCH_DIRS="$SEARCH_DIRS tests"
+[ -d e2e ]   && SEARCH_DIRS="$SEARCH_DIRS e2e"
+
+if [ -n "$CASE_IDS" ]; then
+  if [ -z "$SEARCH_DIRS" ]; then
+    echo "spec-conformance: FAIL — case-ids exist but no tests/ or e2e/ dir to cite them." >&2
+    FAIL=1
+  else
+    while IFS= read -r cid; do
+      [ -n "$cid" ] || continue
+      # cite convention: `spec: <case-id>` with a non-id char (or EOL) after, so
+      # PH2-ORDER-01 does not match PH2-ORDER-011.
+      if grep -rEq -- "spec:[[:space:]]*${cid}([^0-9A-Za-z_-]|$)" $SEARCH_DIRS 2>/dev/null; then
+        :
+      else
+        echo "spec-conformance: FAIL — case ${cid} has no boundary test citing it (# spec: ${cid})." >&2
+        FAIL=1
+      fi
+    done <<EOF
+$CASE_IDS
+EOF
+  fi
+fi
+
+if [ "$FAIL" -ne 0 ]; then
+  echo "spec-conformance: BLOCKED — fix the above before GREEN." >&2
+  exit 1
+fi
+echo "spec-conformance: OK — phase ${N} spec fully filled; every case-id cited by a boundary test."
+exit 0

package/template/scripts/spec-staleness.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# spec-staleness.sh — guard the per-phase spec header against upstream drift (v2.2).
+#
+# The behavioral contract docs/spec-phase-<n>.md carries a GENERATED header that
+# transcludes the phase's PLAN.md `- acceptance:` line + the in-scope DATAFLOW.md
+# transition rows, plus an embedded hash. If PLAN.md / DATAFLOW.md change after the
+# skeleton was stamped (e.g. via /replan), the stored hash no longer matches the
+# upstream → the spec must be regenerated/re-filled before SPEC REVIEW. (§5.55, rule 17)
+#
+# Hashing lives ONLY here (no duplication in agent prompts):
+#   bash scripts/spec-staleness.sh stamp <n>    # compute + embed the hash (at /overview, on regenerate)
+#   bash scripts/spec-staleness.sh check <n>    # default: recompute + compare; nonzero on drift
+#   bash scripts/spec-staleness.sh <n>          # alias for: check <n>
+#
+# set -euo pipefail; nonzero = loud fail; `stamp` is the only side effect.
+set -euo pipefail
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# ---- args ----
+SUB="check"
+case "${1:-}" in
+  stamp) SUB="stamp"; shift;;
+  check) SUB="check"; shift;;
+esac
+N="${1:-}"
+[ -n "$N" ] || { echo "spec-staleness: usage: spec-staleness.sh [stamp|check] <phase-n>" >&2; exit 2; }
+
+SPEC="docs/spec-phase-${N}.md"
+PLAN="docs/PLAN.md"
+DATAFLOW="docs/DATAFLOW.md"
+[ -f "$SPEC" ] || { echo "spec-staleness: $SPEC not found." >&2; exit 2; }
+[ -f "$PLAN" ] || { echo "spec-staleness: $PLAN not found." >&2; exit 2; }
+
+# ---- sha256 of stdin (portable: sha256sum -> shasum -> node) ----
+sha_stdin() {
+  if   command -v sha256sum >/dev/null 2>&1; then sha256sum | cut -d' ' -f1
+  elif command -v shasum    >/dev/null 2>&1; then shasum -a 256 | cut -d' ' -f1
+  else node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(require('crypto').createHash('sha256').update(d).digest('hex')))"
+  fi
+}
+
+# normalize: NFC-ish arrow unify (→ -> ->), collapse spaces, trim. Content-sensitive,
+# whitespace-insensitive — so cosmetic reflow does not trip the guard, content does.
+norm() { sed -e 's/→/->/g' -e 's/[[:space:]]\{1,\}/ /g' -e 's/^ //' -e 's/ $//'; }
+
+# ---- extract this phase's block from PLAN.md (## Phase <n>: ... up to next ## Phase) ----
+phase_block() {
+  awk -v n="$N" '
+    $0 ~ ("^## Phase " n ":") {inblk=1; print; next}
+    inblk && /^## Phase /      {inblk=0}
+    inblk                      {print}
+  ' "$PLAN"
+}
+
+BLOCK="$(phase_block || true)"
+[ -n "$BLOCK" ] || { echo "spec-staleness: no '## Phase ${N}:' block in $PLAN." >&2; exit 2; }
+
+# acceptance line(s) + dataflow line, normalized
+ACC_LINE="$(printf '%s\n' "$BLOCK"   | grep -E '^- acceptance:' | norm || true)"
+DF_LINE="$(printf '%s\n'  "$BLOCK"   | grep -E '^- dataflow:'   | norm || true)"
+
+# in-scope transition tokens (from->to) named on the dataflow line
+TOKENS="$(printf '%s\n' "$DF_LINE" | norm | grep -oE '[A-Za-z0-9_]+->[A-Za-z0-9_]+' | sort -u || true)"
+
+# matching DATAFLOW.md data-rows (table rows naming an in-scope transition)
+DF_ROWS=""
+if [ -n "$TOKENS" ] && [ -f "$DATAFLOW" ]; then
+  while IFS= read -r tok; do
+    [ -n "$tok" ] || continue
+    rows="$(grep -E '^\|' "$DATAFLOW" | norm | grep -F "$tok" || true)"
+    DF_ROWS="${DF_ROWS}${rows}
+"
+  done <<EOF
+$TOKENS
+EOF
+fi
+DF_ROWS="$(printf '%s\n' "$DF_ROWS" | grep -v '^$' | sort -u || true)"
+
+# ---- the upstream signature + its hash ----
+SIG="$(printf 'ACC:%s\nDF:%s\nROWS:\n%s\n' "$ACC_LINE" "$DF_LINE" "$DF_ROWS")"
+WANT="$(printf '%s' "$SIG" | sha_stdin)"
+
+HASH_RE='^<!-- spec-hash: .* -->$'
+HAVE="$(grep -E "$HASH_RE" "$SPEC" | head -1 | sed -E 's/^<!-- spec-hash: (.*) -->$/\1/' || true)"
+
+if [ "$SUB" = "stamp" ]; then
+  if grep -qE "$HASH_RE" "$SPEC"; then
+    tmp="$(mktemp)"
+    awk -v h="$WANT" '
+      /^<!-- spec-hash: .* -->$/ && !done { print "<!-- spec-hash: " h " -->"; done=1; next }
+      { print }
+    ' "$SPEC" > "$tmp" && mv "$tmp" "$SPEC"
+  else
+    echo "spec-staleness: $SPEC has no '<!-- spec-hash: ... -->' header line to stamp." >&2
+    exit 2
+  fi
+  echo "spec-staleness: stamped phase ${N} -> ${WANT}"
+  exit 0
+fi
+
+# ---- check ----
+if [ -z "$HAVE" ] || [ "$HAVE" = "PENDING" ]; then
+  echo "spec-staleness: FAIL — phase ${N} spec hash is unstamped (${HAVE:-missing})." >&2
+  echo "  Run: bash scripts/spec-staleness.sh stamp ${N}" >&2
+  exit 1
+fi
+if [ "$HAVE" != "$WANT" ]; then
+  echo "spec-staleness: FAIL — phase ${N} spec is STALE." >&2
+  echo "  Upstream PLAN.md acceptance / DATAFLOW.md rows changed since the skeleton was stamped." >&2
+  echo "  stored=${HAVE}  current=${WANT}" >&2
+  echo "  Regenerate the skeleton header from current PLAN/DATAFLOW, re-stamp, and re-fill." >&2
+  exit 1
+fi
+echo "spec-staleness: OK — phase ${N} spec header matches upstream (${WANT})."
+exit 0