pi-evalset-lab 0.1.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pi-evalset-lab",
+  "version": "0.1.0",
+  "description": "pi extension package: pi-evalset-lab",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["pi-package"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tryingET/pi-evalset-lab.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tryingET/pi-evalset-lab/issues"
+  },
+  "homepage": "https://github.com/tryingET/pi-evalset-lab#readme",
+  "scripts": {
+    "check": "bash ./scripts/validate-structure.sh",
+    "test": "bash ./scripts/validate-structure.sh",
+    "docs:list": "bash ./scripts/docs-list.sh",
+    "docs:list:workspace": "bash ./scripts/docs-list.sh --workspace --discover",
+    "docs:list:json": "bash ./scripts/docs-list.sh --json"
+  },
+  "pi": {
+    "extensions": ["./extensions/evalset.ts"],
+    "prompts": ["./prompts"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-ai": "*"
+  }
+}

package/policy/security-policy.json

@@ -0,0 +1,10 @@
+{
+  "default": {
+    "maxRiskScore": 70,
+    "requireIntegrity": true,
+    "requireSignatures": false,
+    "allowNpmDiffFallback": false,
+    "minReleaseAgeHours": 0
+  },
+  "packages": {}
+}

package/prek.toml

@@ -0,0 +1,15 @@
+minimum_prek_version = "0.3.0"
+
+[[repos]]
+repo = "local"
+hooks = [
+  {
+    id = "validate-structure",
+    name = "validate structure",
+    language = "system",
+    entry = "bash ./scripts/validate-structure.sh",
+    pass_filenames = false,
+    always_run = true,
+    stages = ["pre-commit"]
+  }
+]

package/prompts/implementation-planning.md

@@ -0,0 +1,17 @@
+---
+description: Draft an implementation plan for a requested change
+system4d:
+  container: "Prompt template for implementation planning."
+  compass: "Turn requests into actionable, risk-aware plans."
+  engine: "Scope -> tasks -> validation -> rollout."
+  fog: "Hidden constraints unless assumptions are surfaced."
+---
+
+Create an implementation plan for this request: $@
+
+Include:
+- Scope and non-goals
+- Key risks and mitigations
+- Step-by-step implementation tasks
+- Validation commands and expected outcomes
+- Rollout and rollback notes

package/prompts/init-project-docs.md

@@ -0,0 +1,32 @@
+---
+description: Run interview-first initialization for organization and project docs
+system4d:
+  container: "Prompt template for document initialization workflow."
+  compass: "Create compact, aligned org/project docs from structured intake."
+  engine: "Intent -> interview -> synthesize -> update docs -> verify."
+  fog: "Incomplete intake answers can cause ambiguous documentation."
+---
+
+Initialize organization and project docs from interactive intake.
+
+Startup intent (if provided): $@
+
+Steps:
+1. Read `docs/org/project-docs-intake.questions.json`.
+2. If startup intent is non-empty, create `docs/org/project-docs-intake.runtime.questions.json` with one prepended question:
+   - `id`: `startup_intent_confirmation`
+   - `type`: `text`
+   - `question`: `Startup intent captured: <startup intent>. Confirm or refine this intent before continuing.`
+3. Run the `interview` tool:
+   - `questions`: runtime file from step 2 if created, otherwise `docs/org/project-docs-intake.questions.json`
+   - `timeout`: `900`
+4. Use interview responses to update these files:
+   - `docs/org/operating_model.md`
+   - `docs/project/foundation.md`
+   - `docs/project/vision.md`
+   - `docs/project/strategic_goals.md`
+   - `docs/project/tactical_goals.md`
+5. Keep wording fully in English.
+6. Keep **organization purpose** separate from **project purpose**.
+7. Keep output compact.
+8. Run `bash ./scripts/validate-structure.sh`.

package/prompts/security-review.md

@@ -0,0 +1,17 @@
+---
+description: Review a change for security risks and mitigations
+system4d:
+  container: "Prompt template for security-focused review."
+  compass: "Identify practical vulnerabilities before release."
+  engine: "Threats -> impact -> mitigations -> verification."
+  fog: "Partial context can hide exploit paths."
+---
+
+Review this change for security concerns: $@
+
+Focus on:
+- Input validation and injection risk
+- Privilege boundaries and secret handling
+- Dependency and supply-chain risk
+- Safe failure modes and logging
+- Concrete remediations with priority

package/scripts/docs-list.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DEFAULT_SCRIPT="$HOME/ai-society/core/agent-scripts/scripts/docs-list.mjs"
+LOCAL_FALLBACK_SCRIPT="$ROOT_DIR/scripts/docs-list.mjs"
+
+usage() {
+  cat <<'USAGE'
+Usage: ./scripts/docs-list.sh [docs-list args]
+
+Resolves docs-list script in this order:
+1) DOCS_LIST_SCRIPT env var (absolute/relative path)
+2) Local fallback: ./scripts/docs-list.mjs
+3) Default global path: ~/ai-society/core/agent-scripts/scripts/docs-list.mjs
+
+Examples:
+  ./scripts/docs-list.sh
+  ./scripts/docs-list.sh --workspace --discover
+  ./scripts/docs-list.sh --json
+USAGE
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "Error: node is required to run docs-list." >&2
+  exit 1
+fi
+
+SCRIPT_PATH=""
+
+if [[ -n "${DOCS_LIST_SCRIPT:-}" ]]; then
+  SCRIPT_PATH="${DOCS_LIST_SCRIPT}"
+elif [[ -f "$LOCAL_FALLBACK_SCRIPT" ]]; then
+  SCRIPT_PATH="$LOCAL_FALLBACK_SCRIPT"
+else
+  SCRIPT_PATH="$DEFAULT_SCRIPT"
+fi
+
+if [[ ! -f "$SCRIPT_PATH" ]]; then
+  echo "Error: docs-list script not found: $SCRIPT_PATH" >&2
+  echo "Set DOCS_LIST_SCRIPT to your docs-list.mjs path, or install agent-scripts at: $DEFAULT_SCRIPT" >&2
+  exit 1
+fi
+
+node "$SCRIPT_PATH" "$@"

package/scripts/init-project-docs.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+QUESTIONS_FILE="$ROOT_DIR/docs/org/project-docs-intake.questions.json"
+ROUTER_FILE="$ROOT_DIR/.pi/extensions/startup-intake-router.ts"
+PROMPT_FILE="$ROOT_DIR/.pi/prompts/init-project-docs.md"
+
+INSTALL_INTERVIEW=false
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --install-interview)
+      INSTALL_INTERVIEW=true
+      ;;
+    -h|--help)
+      echo "Usage: ./scripts/init-project-docs.sh [--install-interview]"
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      echo "Usage: ./scripts/init-project-docs.sh [--install-interview]" >&2
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+for required in "$QUESTIONS_FILE" "$ROUTER_FILE" "$PROMPT_FILE"; do
+  if [[ ! -f "$required" ]]; then
+    echo "Missing required file: $required" >&2
+    exit 1
+  fi
+done
+
+if [[ "$INSTALL_INTERVIEW" == "true" ]]; then
+  if command -v pi-interview >/dev/null 2>&1; then
+    pi-interview
+  else
+    echo "pi-interview command not found. Install the interactive-interview extension first, then rerun with --install-interview." >&2
+  fi
+fi
+
+echo "Interview-first document setup"
+echo ""
+echo "0) Optional: run npm run docs:list to review docs + read_when hints."
+echo "1) Ensure the interview extension is installed and loaded in pi."
+echo "2) Open this repository in pi."
+echo "3) Send a natural-language intent as the first non-command message in a session."
+echo "4) Router will prefill: /init-project-docs \"<intent>\""
+echo "5) Review/edit and run that command."
+echo ""
+echo "Fallback: run /init-project-docs manually."
+echo "Questions source: $QUESTIONS_FILE"
+echo ""
+echo "After updates, run: bash ./scripts/validate-structure.sh"

package/scripts/install-hooks.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+git -C "$ROOT_DIR" config core.hooksPath .githooks
+echo "Configured git hooks path: .githooks"
+
+if command -v prek >/dev/null 2>&1; then
+  echo "prek detected: pre-commit hook will run prek.toml"
+else
+  echo "prek not found: pre-commit hook will fallback to scripts/validate-structure.sh"
+fi

package/scripts/sync-to-live.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+WITH_POLICY=false
+WITH_PROMPTS=false
+
+usage() {
+  cat <<'USAGE'
+Usage: ./scripts/sync-to-live.sh [--with-policy] [--with-prompts] [--all]
+
+Copies all package extension entrypoints from ./extensions into ~/.pi/agent/extensions/.
+Optional flags also sync policy and prompt templates.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --with-policy)
+      WITH_POLICY=true
+      ;;
+    --with-prompts)
+      WITH_PROMPTS=true
+      ;;
+    --all)
+      WITH_POLICY=true
+      WITH_PROMPTS=true
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SOURCE_DIR="$ROOT_DIR/extensions"
+TARGET_DIR="$HOME/.pi/agent/extensions"
+
+mkdir -p "$TARGET_DIR"
+
+shopt -s nullglob
+extension_files=("$SOURCE_DIR"/*.ts)
+if (( ${#extension_files[@]} == 0 )); then
+  echo "No extension files found in: $SOURCE_DIR" >&2
+  exit 1
+fi
+
+for source_file in "${extension_files[@]}"; do
+  target_file="$TARGET_DIR/$(basename "$source_file")"
+  cp "$source_file" "$target_file"
+  echo "Synced extension: $source_file -> $target_file"
+done
+shopt -u nullglob
+
+if [[ "$WITH_PROMPTS" == "true" ]]; then
+  PROMPT_SOURCE_DIR="$ROOT_DIR/prompts"
+  PROMPT_TARGET_DIR="$HOME/.pi/agent/prompts"
+  mkdir -p "$PROMPT_TARGET_DIR"
+
+  shopt -s nullglob
+  prompt_files=("$PROMPT_SOURCE_DIR"/*.md)
+  if (( ${#prompt_files[@]} == 0 )); then
+    echo "No prompt templates found in: $PROMPT_SOURCE_DIR"
+  else
+    for prompt_file in "${prompt_files[@]}"; do
+      cp "$prompt_file" "$PROMPT_TARGET_DIR/"
+      echo "Synced prompt: $prompt_file -> $PROMPT_TARGET_DIR/$(basename "$prompt_file")"
+    done
+  fi
+  shopt -u nullglob
+fi
+
+if [[ "$WITH_POLICY" == "true" ]]; then
+  POLICY_SOURCE="$ROOT_DIR/policy/security-policy.json"
+  POLICY_TARGET="$HOME/.pi/agent/security-policy.json"
+
+  if [[ -f "$POLICY_SOURCE" ]]; then
+    cp "$POLICY_SOURCE" "$POLICY_TARGET"
+    echo "Synced policy: $POLICY_SOURCE -> $POLICY_TARGET"
+  else
+    echo "Policy file not found: $POLICY_SOURCE (skipped)"
+  fi
+fi
+
+echo "Done. In pi, run /reload to pick up changes."

package/scripts/validate-structure.sh

@@ -0,0 +1,325 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+required_files=(
+  "README.md"
+  "CHANGELOG.md"
+  "SECURITY.md"
+  "CODE_OF_CONDUCT.md"
+  "SUPPORT.md"
+  "CONTRIBUTING.md"
+  "AGENTS.md"
+  ".copier-answers.yml"
+  "prek.toml"
+  ".github/CODEOWNERS"
+  ".github/dependabot.yml"
+  ".github/pull_request_template.md"
+  ".github/VOUCHED.td"
+  ".github/ISSUE_TEMPLATE/bug-report.yml"
+  ".github/ISSUE_TEMPLATE/feature-request.yml"
+  ".github/ISSUE_TEMPLATE/docs.yml"
+  ".github/ISSUE_TEMPLATE/config.yml"
+  ".github/workflows/ci.yml"
+  ".github/workflows/release-please.yml"
+  ".github/workflows/publish.yml"
+  ".github/workflows/vouch-check-pr.yml"
+  ".github/workflows/vouch-manage.yml"
+  ".release-please-config.json"
+  ".release-please-manifest.json"
+  "docs/org/operating_model.md"
+  "docs/org/project-docs-intake.questions.json"
+  "docs/project/foundation.md"
+  "docs/project/vision.md"
+  "docs/project/incentives.md"
+  "docs/project/resources.md"
+  "docs/project/skills.md"
+  "docs/project/strategic_goals.md"
+  "docs/project/tactical_goals.md"
+  "docs/dev/next_steps.md"
+  "docs/dev/status.md"
+  "docs/dev/CONTRIBUTING.md"
+  "docs/dev/EXTENSION_SOP.md"
+  ".pi/extensions/startup-intake-router.ts"
+  ".pi/prompts/init-project-docs.md"
+  "scripts/sync-to-live.sh"
+  "scripts/install-hooks.sh"
+  "scripts/init-project-docs.sh"
+  "scripts/docs-list.sh"
+  "scripts/validate-structure.sh"
+  ".githooks/pre-commit"
+  "prompts/implementation-planning.md"
+  "prompts/security-review.md"
+  "prompts/init-project-docs.md"
+)
+
+required_dirs=(
+  ".github"
+  ".github/workflows"
+  ".github/ISSUE_TEMPLATE"
+  "docs/org"
+  "docs/dev/plans"
+  "examples"
+  "external"
+  "ontology"
+  "policy"
+  "scripts"
+  "src"
+  "tests"
+  ".pi"
+  ".pi/extensions"
+  ".pi/prompts"
+  ".githooks"
+  "prompts"
+)
+
+required_executables=(
+  "scripts/sync-to-live.sh"
+  "scripts/install-hooks.sh"
+  "scripts/init-project-docs.sh"
+  "scripts/docs-list.sh"
+  "scripts/validate-structure.sh"
+  ".githooks/pre-commit"
+)
+
+errors=0
+
+for required_file in "${required_files[@]}"; do
+  if [[ ! -f "$required_file" ]]; then
+    echo "Missing required file: $required_file" >&2
+    ((errors+=1))
+  fi
+done
+
+for required_dir in "${required_dirs[@]}"; do
+  if [[ ! -d "$required_dir" ]]; then
+    echo "Missing required directory: $required_dir" >&2
+    ((errors+=1))
+  fi
+done
+
+for executable in "${required_executables[@]}"; do
+  if [[ ! -x "$executable" ]]; then
+    echo "Expected executable bit on: $executable" >&2
+    ((errors+=1))
+  fi
+done
+
+plan_count=$(find "docs/dev/plans" -maxdepth 1 -type f -name "*.md" | wc -l | tr -d ' ')
+if [[ "$plan_count" -lt 1 ]]; then
+  echo "docs/dev/plans must contain at least one markdown plan file" >&2
+  ((errors+=1))
+fi
+
+for copier_key in "_src_path:" "repo_name:" "command_name:"; do
+  if ! grep -q "^${copier_key}" ".copier-answers.yml"; then
+    echo "Missing copier answer key in .copier-answers.yml: ${copier_key}" >&2
+    ((errors+=1))
+  fi
+done
+
+placeholder_pattern='\{username\}|\{repo\}|\{discordInvite\}|\{@twitter\}'
+placeholder_hits="$(grep -R -nE "$placeholder_pattern" .github || true)"
+if [[ -n "$placeholder_hits" ]]; then
+  echo "Unresolved placeholders found under .github:" >&2
+  echo "$placeholder_hits" >&2
+  ((errors+=1))
+fi
+
+vouch_ref="0e11a71bba23218a284d3ecca162e75a110fd7e3"
+if ! grep -q "mitchellh/vouch/action/check-pr@${vouch_ref}" ".github/workflows/vouch-check-pr.yml"; then
+  echo "vouch-check-pr workflow must pin mitchellh/vouch/action/check-pr to ${vouch_ref}" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "mitchellh/vouch/action/manage-by-issue@${vouch_ref}" ".github/workflows/vouch-manage.yml"; then
+  echo "vouch-manage workflow must pin mitchellh/vouch/action/manage-by-issue to ${vouch_ref}" >&2
+  ((errors+=1))
+fi
+
+if grep -n "@main" .github/workflows/vouch-*.yml >/dev/null 2>&1; then
+  echo "vouch workflows must not use @main refs" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "pull_request_target" ".github/workflows/vouch-check-pr.yml"; then
+  echo "vouch-check-pr workflow must trigger on pull_request_target" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "require-vouch" ".github/workflows/vouch-check-pr.yml"; then
+  echo "vouch-check-pr workflow must set require-vouch" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "auto-close" ".github/workflows/vouch-check-pr.yml"; then
+  echo "vouch-check-pr workflow must set auto-close" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "issue_comment" ".github/workflows/vouch-manage.yml"; then
+  echo "vouch-manage workflow must trigger on issue_comment" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "concurrency:" ".github/workflows/vouch-manage.yml" || ! grep -q "group: vouch-manage" ".github/workflows/vouch-manage.yml"; then
+  echo "vouch-manage workflow must define serialized concurrency" >&2
+  ((errors+=1))
+fi
+
+if ! grep -q "vouched-file: .github/VOUCHED.td" ".github/workflows/vouch-manage.yml"; then
+  echo "vouch-manage workflow must target .github/VOUCHED.td" >&2
+  ((errors+=1))
+fi
+
+if grep -q "@your-github-handle" ".github/CODEOWNERS"; then
+  echo ".github/CODEOWNERS must not keep @your-github-handle placeholder" >&2
+  ((errors+=1))
+fi
+
+if ! grep -Eq "^github:[A-Za-z0-9][A-Za-z0-9-]*" ".github/VOUCHED.td"; then
+  echo ".github/VOUCHED.td must include at least one github maintainer entry" >&2
+  ((errors+=1))
+fi
+
+if command -v node >/dev/null 2>&1; then
+  if ! node - <<'NODE'
+const fs = require("node:fs");
+
+let failed = false;
+const fail = (msg) => {
+  console.error(msg);
+  failed = true;
+};
+
+try {
+  const qPath = "docs/org/project-docs-intake.questions.json";
+  const q = JSON.parse(fs.readFileSync(qPath, "utf8"));
+  if (!q.title || !Array.isArray(q.questions) || q.questions.length === 0) {
+    fail(`Invalid interview questions file: ${qPath}`);
+  }
+} catch (error) {
+  fail(`Failed to parse interview questions file: ${error.message}`);
+}
+
+try {
+  const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+  if (!Array.isArray(p.keywords) || !p.keywords.includes("pi-package")) {
+    fail("package.json missing keywords entry: pi-package");
+  }
+
+  const ext = p.pi?.extensions;
+  if (!Array.isArray(ext) || ext.length < 1) {
+    fail("package.json missing pi.extensions array");
+  } else {
+    for (const entry of ext) {
+      const normalized = entry.replace(/^\.\//, "");
+      if (!fs.existsSync(normalized)) {
+        fail(`pi.extensions entry does not exist: ${entry}`);
+      }
+    }
+  }
+
+  const prompts = p.pi?.prompts;
+  if (!Array.isArray(prompts) || prompts.length < 1) {
+    fail("package.json missing pi.prompts array");
+  } else {
+    for (const entry of prompts) {
+      const normalized = entry.replace(/\/$/, "").replace(/^\.\//, "");
+      if (!fs.existsSync(normalized)) {
+        fail(`pi.prompts entry does not exist: ${entry}`);
+      }
+    }
+  }
+
+  const checkScript = p.scripts?.check;
+  if (checkScript !== "bash ./scripts/validate-structure.sh") {
+    fail("package.json scripts.check must be 'bash ./scripts/validate-structure.sh'");
+  }
+
+  const testScript = p.scripts?.test;
+  if (testScript !== "bash ./scripts/validate-structure.sh") {
+    fail("package.json scripts.test must be 'bash ./scripts/validate-structure.sh'");
+  }
+
+  const docsListScript = p.scripts?.["docs:list"];
+  if (docsListScript !== "bash ./scripts/docs-list.sh") {
+    fail("package.json scripts.docs:list must be 'bash ./scripts/docs-list.sh'");
+  }
+
+  const docsListWorkspaceScript = p.scripts?.["docs:list:workspace"];
+  if (docsListWorkspaceScript !== "bash ./scripts/docs-list.sh --workspace --discover") {
+    fail("package.json scripts.docs:list:workspace must be 'bash ./scripts/docs-list.sh --workspace --discover'");
+  }
+
+  const docsListJsonScript = p.scripts?.["docs:list:json"];
+  if (docsListJsonScript !== "bash ./scripts/docs-list.sh --json") {
+    fail("package.json scripts.docs:list:json must be 'bash ./scripts/docs-list.sh --json'");
+  }
+
+  const rpConfig = JSON.parse(fs.readFileSync(".release-please-config.json", "utf8"));
+  if (rpConfig["include-v-in-tag"] !== true) {
+    fail(".release-please-config.json must set include-v-in-tag=true");
+  }
+  if (!rpConfig.packages || !rpConfig.packages["."]) {
+    fail(".release-please-config.json must include packages['.']");
+  }
+
+  const rpManifest = JSON.parse(fs.readFileSync(".release-please-manifest.json", "utf8"));
+  if (!rpManifest["."]) {
+    fail(".release-please-manifest.json must include '.' version entry");
+  }
+  const versionPattern = /^\d+\.\d+\.\d+([-.][0-9A-Za-z.]+)?$/;
+  if (!versionPattern.test(rpManifest["."])) {
+    fail(".release-please-manifest.json '.' entry must match X.Y.Z");
+  }
+  if (rpManifest["."] !== p.version) {
+    fail(".release-please-manifest.json '.' entry must match package.json version");
+  }
+} catch (error) {
+  fail(`Failed to validate package/release metadata: ${error.message}`);
+}
+
+process.exit(failed ? 1 : 0);
+NODE
+  then
+    ((errors+=1))
+  fi
+fi
+
+while IFS= read -r -d '' markdown_file; do
+  if [[ "$(head -n 1 "$markdown_file")" != "---" ]]; then
+    echo "Missing YAML frontmatter start in: $markdown_file" >&2
+    ((errors+=1))
+    continue
+  fi
+
+  if ! grep -q "^system4d:" "$markdown_file"; then
+    echo "Missing system4d section in: $markdown_file" >&2
+    ((errors+=1))
+    continue
+  fi
+
+  for key in container compass engine fog; do
+    if ! grep -q "^  $key:" "$markdown_file"; then
+      echo "Missing system4d.$key in: $markdown_file" >&2
+      ((errors+=1))
+    fi
+  done
+
+  if [[ "$markdown_file" == "./prompts/"* || "$markdown_file" == "./.pi/prompts/"* ]]; then
+    if ! grep -q "^description:" "$markdown_file"; then
+      echo "Prompt template missing frontmatter description: $markdown_file" >&2
+      ((errors+=1))
+    fi
+  fi
+done < <(find . -type f -name "*.md" ! -path "./.git/*" ! -path "./node_modules/*" -print0)
+
+if [[ "$errors" -gt 0 ]]; then
+  echo "Structure validation failed with $errors issue(s)." >&2
+  exit 1
+fi
+
+echo "Structure validation passed."