@tea-agent/loop-agent 0.12.0 → 0.13.0-alpha.0

package/docs/templates/knowledge-sync-dag.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "./agent-dag.schema.json",
+  "version": 2,
+  "title": "Knowledge-sync DAG template",
+  "objective": "After final verification, draft and apply stable testing knowledge: acceptance verdict, cases, coverage, defects, requirement delta pointers, and run audit records under features/*/testing/**.",
+  "successCriteria": [
+    "knowledge-sync-collect-pi inventories final verification evidence, ACs, cases, and defect candidates without writing files",
+    "knowledge-sync-draft-pi writes schemaVersion 1 knowledge-sync-draft.json under features/<feature-id>/testing/sync/pending/",
+    "knowledge-sync-validate-shell fails closed on missing draft, invalid schema, or non-pass finalVerification when gated",
+    "knowledge-sync-apply-pi upserts acceptance-verdict, coverage-matrix, cases, automation-map, and defects only within writeSet",
+    "knowledge-sync-pointer-pi writes runs/latest.md and sync/applied/KS-*.json audit pointers",
+    "No writes to src/**, .harness/**, or knowledge/testing/standards/**"
+  ],
+  "globalConstraints": [
+    "Replace feature-id placeholders with the concrete Feature id before production runs.",
+    "Do not commit runtime traces under .harness/dag-runs/.",
+    "Use only existing executors: pi, shell. Pi writer nodes must set toolProfile=write.",
+    "Read-only nodes must not write repository files.",
+    "Exclusive writer nodes must stay within declared writeSet.",
+    "Final verification shell evidence remains completion authority; knowledge-sync stores stable facts and path pointers only.",
+    "High-risk requirement/acceptance body changes require human approval via requirement-delta; do not silently rewrite requirement.md.",
+    "Prefer structured YAML/Markdown L1 knowledge pack over vector-store-only writes."
+  ],
+  "defaults": {
+    "executor": "pi",
+    "contextProfile": "slim",
+    "skills": [
+      "ai-engineering-context"
+    ],
+    "writePolicy": "read-only"
+  },
+  "skillsByRole": {
+    "planner": [
+      "loop-agent"
+    ],
+    "implementer": [
+      "verification-before-completion"
+    ],
+    "reviewer": [
+      "requesting-code-review"
+    ],
+    "verifier": [
+      "verification-before-completion",
+      "systematic-debugging"
+    ],
+    "closeout": [
+      "loop-agent",
+      "verification-before-completion"
+    ]
+  },
+  "tasks": [
+    {
+      "id": "knowledge-sync-collect-pi",
+      "depends_on": [],
+      "role": "planner",
+      "executor": "pi",
+      "complexity": "MED",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "./**",
+        "docs/**",
+        "features/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Plain Markdown inventory of evidence and knowledge-sync candidates; no file writes.",
+      "subtask_prompt": "Collect final-verification evidence, AC list, cases, defects, and requirement-delta candidates. Read-only."
+    },
+    {
+      "id": "knowledge-sync-draft-pi",
+      "depends_on": [
+        "knowledge-sync-collect-pi"
+      ],
+      "role": "implementer",
+      "executor": "pi",
+      "toolProfile": "write",
+      "complexity": "HIGH",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "features/**/testing/sync/pending/**"
+      ],
+      "allowedPaths": [
+        "features/**/testing/sync/pending/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**",
+        "src/**"
+      ],
+      "outputContract": "Pending knowledge-sync-draft.json + markdown summary under features/<feature-id>/testing/sync/pending/.",
+      "subtask_prompt": "Write schemaVersion 1 draft with operations, payload, and gates. Stay within writeSet."
+    },
+    {
+      "id": "knowledge-sync-validate-shell",
+      "depends_on": [
+        "knowledge-sync-draft-pi"
+      ],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "allowedPaths": [
+        "features/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**"
+      ],
+      "outputContract": "Deterministic draft schema validation; exit non-zero on invalid draft.",
+      "subtask_prompt": "Validate pending knowledge-sync-draft.json files.",
+      "shell": {
+        "commands": [
+          "node -e \"const fs=require('fs');const path=require('path');function walk(d,a=[]){if(!fs.existsSync(d))return a;for(const e of fs.readdirSync(d,{withFileTypes:true})){const p=path.join(d,e.name);if(e.isDirectory())walk(p,a);else if(e.name==='knowledge-sync-draft.json')a.push(p);}return a;}const drafts=walk('features');if(!drafts.length){console.error('no draft');process.exit(1);}for(const f of drafts){const d=JSON.parse(fs.readFileSync(f,'utf8'));if(d.schemaVersion!==1)process.exit(1);}console.log('ok');\""
+        ],
+        "cwd": ".",
+        "timeoutMs": 120000
+      }
+    },
+    {
+      "id": "knowledge-sync-apply-pi",
+      "depends_on": [
+        "knowledge-sync-validate-shell"
+      ],
+      "role": "implementer",
+      "executor": "pi",
+      "toolProfile": "write",
+      "complexity": "HIGH",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "features/**/testing/**",
+        "features/**/requirement-delta.md",
+        "docs/test-reports/**"
+      ],
+      "allowedPaths": [
+        "features/**/testing/**",
+        "features/**/requirement-delta.md",
+        "docs/test-reports/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**",
+        "src/**",
+        "knowledge/testing/standards/**"
+      ],
+      "outputContract": "Applied L1 knowledge files: acceptance-verdict, coverage-matrix, cases, defects, optional requirement-delta.",
+      "subtask_prompt": "Apply validated draft into Feature testing knowledge paths. Do not touch standards or src."
+    },
+    {
+      "id": "knowledge-sync-pointer-pi",
+      "depends_on": [
+        "knowledge-sync-apply-pi"
+      ],
+      "role": "closeout",
+      "executor": "pi",
+      "toolProfile": "write",
+      "complexity": "MED",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "features/**/testing/runs/**",
+        "features/**/testing/sync/applied/**"
+      ],
+      "allowedPaths": [
+        "features/**/testing/runs/**",
+        "features/**/testing/sync/applied/**"
+      ],
+      "forbiddenPaths": [
+        ".harness/**",
+        "artifacts/**",
+        "src/**"
+      ],
+      "outputContract": "runs/latest.md and sync/applied/KS-*.json audit pointers.",
+      "subtask_prompt": "Write run pointers and applied audit record only."
+    }
+  ]
+}

package/docs/templates/knowledge-sync-draft.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://loop-agent.local/schemas/knowledge-sync-draft.schema.json",
+  "title": "Knowledge Sync Draft",
+  "description": "Pending package written by knowledge-sync-draft-pi before validate/apply.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "featureId",
+    "taskId",
+    "runId",
+    "finalVerification",
+    "operations",
+    "payload",
+    "gates"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "featureId": { "type": "string", "minLength": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "headSha": { "type": "string" },
+    "finalVerification": {
+      "type": "string",
+      "enum": ["pass", "fail", "partial", "pass-with-waivers"]
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["op", "target", "risk", "reason"],
+        "properties": {
+          "op": { "type": "string", "enum": ["upsert", "create", "append"] },
+          "target": { "type": "string", "minLength": 1 },
+          "risk": { "type": "string", "enum": ["low", "medium", "high"] },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "acceptanceVerdict": { "type": ["object", "null"] },
+        "coverageMatrix": { "type": ["object", "null"] },
+        "caseIndex": { "type": ["object", "null"] },
+        "automationMap": { "type": ["object", "null"] },
+        "defects": { "type": ["object", "null"] },
+        "requirementDelta": { "type": ["object", "string", "null"] },
+        "retrospectiveRef": { "type": ["string", "null"] },
+        "evidencePointers": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requireHumanIfHighRisk", "blockIfFinalVerificationNotPass"],
+      "properties": {
+        "requireHumanIfHighRisk": { "type": "boolean" },
+        "blockIfFinalVerificationNotPass": { "type": "boolean" },
+        "blockIfCoverageP0Missing": { "type": "boolean" }
+      }
+    }
+  }
+}

package/docs/verification-matrix.md

@@ -11,7 +11,8 @@
 | Feature run orchestration | `npx vitest run test/worker/feature test/worker/runner/run-ready.test.ts test/worker/agent-worker-cli.test.ts` | `npm test` + `node bin/agent-worker.js feature run --help` |
 | Follow-up 分类与事务 | `npx vitest run test/worker/follow-up test/worker/feature test/worker/pool test/worker/report test/worker/agent-worker-cli.test.ts` | `npm test` + `node bin/agent-worker.js task draft-followup --help` + `node bin/agent-worker.js feature approve-followup --help` |
 | Feature Git transaction | `npx vitest run test/worker/delivery test/worker/feature test/worker/runner test/worker/agent-worker-cli.test.ts` | `npm test` + `node bin/agent-worker.js feature run --help` + temporary Git repo smoke |
-| Final verification / Delivery / Closeout | `npx vitest run test/worker/delivery test/worker/closeout test/worker/feature test/worker/agent-worker-cli.test.ts` | `npm test` + verify-final/Delivery/Closeout CLI help + temporary Git repo evidence/hash/tamper/apply rollback smoke |
+| Final verification / Delivery / Closeout | `npx vitest run test/worker/delivery test/worker/feature test/worker/agent-worker-cli.test.ts` | `npm test` + verify-final/Delivery/Closeout CLI help + temporary Git repo evidence/hash/tamper/apply rollback smoke。Closeout 覆盖在 `test/worker/delivery/**` 与 CLI，不存在独立 `test/worker/closeout/` 目录 |
+| Task Pool feature-scoped identity / migration | `npx vitest run test/worker/pool test/worker/runner/run-ready.test.ts test/worker/feature test/worker/follow-up test/worker/delivery test/worker/report test/worker/observability test/worker/observe test/worker/agent-worker-cli.test.ts` + `npm run typecheck` | 平台临时目录 dual-Feature smoke（同名 `QA-EXEC-001` 不串线）+ `pool doctor` / `pool migrate-state` dry-run + Observe canonical/legacy 409 |
 | Controller identity / pinning | `npx vitest run test/worker/package-metadata.test.ts test/worker/repo-preflight.test.ts test/worker/loop-agent-client.test.ts test/worker/run-task/run-task.test.ts test/worker/runner/run-ready.test.ts test/worker/feature/run.test.ts test/worker/delivery/final-verification.test.ts test/worker/delivery/package.test.ts test/worker/agent-worker-cli.test.ts` + `npm run typecheck` | `npm test` + build + 两个 CLI `--version` + 写入型命令 help |
 | DAG resolved skill snapshot / resume | `npx vitest run test/dag-skill-snapshot.test.ts test/dag-approve-resume.test.ts` + `npm run typecheck` | `npm test` + snapshot tamper/pause-resume/dynamic profile smoke |
 | Versioned self-hosting candidate canary | `npx vitest run test/self-host-canary.test.ts test/package-surface.test.ts` + `npm run build` | `npm run self-host:canary -- --deterministic --output <evidence.json>` + `npm pack --dry-run` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.12.0",
+  "version": "0.13.0-alpha.0",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",
@@ -18,7 +18,13 @@
     "docs/exec-plans/active/README.md", "docs/exec-plans/completed/README.md",
     "docs/init-surface.manifest.json", "docs/progress/README.md", "docs/reports/README.md",
     "docs/skills/", "docs/templates/", "examples/", "harness.json", "skills/",
-    "scripts/check-product-line-docs.sh", "scripts/check-task-pool-root.sh", "README.md", "CHANGELOG.md"
+    "scripts/check-product-line-docs.sh", "scripts/check-task-pool-root.sh",
+    "scripts/kb-bootstrap-init-skeleton.sh",
+    "scripts/kb-query.sh", "scripts/kb-query.mjs",
+    "scripts/kb-graph-materialize.sh", "scripts/kb-graph-materialize.mjs",
+    "scripts/kb-graph-promote.sh", "scripts/kb-graph-promote.mjs",
+    "scripts/kb-graph-incremental-prepare.sh", "scripts/kb-graph-incremental-prepare.mjs",
+    "README.md", "CHANGELOG.md"
   ],
   "publishConfig": { "access": "public" },
   "scripts": {

package/scripts/kb-bootstrap-init-skeleton.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# B1 skeleton for business knowledge-graph bootstrap (no model calls).
+# Creates knowledge/bootstrap/{scope,status}.yaml, staging dirs, and graph placeholders.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: bash scripts/kb-bootstrap-init-skeleton.sh [--root <dir>] [--force] [--product-name <name>]
+
+Idempotent B1 bootstrap skeleton for knowledge-graph-bootstrap-dag preflight.
+
+  --root DIR         Target repository root (default: cwd)
+  --force            Overwrite scope.yaml / status.yaml if they already exist
+  --product-name N   Product name written into scope.yaml (default: basename of root)
+
+Does not call any LLM. Safe for greenfield and brownfield (default: never overwrite).
+EOF
+}
+
+ROOT="$(pwd)"
+FORCE=0
+PRODUCT_NAME=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --root)
+      ROOT="${2:-}"
+      shift 2
+      ;;
+    --force)
+      FORCE=1
+      shift
+      ;;
+    --product-name)
+      PRODUCT_NAME="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown argument: $1" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "${ROOT}" ]]; then
+  echo "--root requires a directory" >&2
+  exit 2
+fi
+
+ROOT="$(cd "${ROOT}" && pwd)"
+if [[ -z "${PRODUCT_NAME}" ]]; then
+  PRODUCT_NAME="$(basename "${ROOT}")"
+fi
+
+TS="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")"
+BOOTSTRAP_ID="BR-$(date -u +"%Y%m%d-%H%M%S" 2>/dev/null || echo "init")"
+
+mkdir -p \
+  "${ROOT}/knowledge/bootstrap/runs" \
+  "${ROOT}/knowledge/bootstrap/staging/domains" \
+  "${ROOT}/knowledge/bootstrap/staging/services" \
+  "${ROOT}/knowledge/bootstrap/staging/modules" \
+  "${ROOT}/knowledge/bootstrap/staging/features-links.proposed" \
+  "${ROOT}/knowledge/graph" \
+  "${ROOT}/knowledge/domains" \
+  "${ROOT}/knowledge/services" \
+  "${ROOT}/knowledge/modules" \
+  "${ROOT}/knowledge/testing"
+
+write_if_missing() {
+  local path="$1"
+  local content="$2"
+  if [[ -e "${path}" && "${FORCE}" -ne 1 ]]; then
+    echo "keep existing: ${path#"${ROOT}"/}"
+    return 0
+  fi
+  mkdir -p "$(dirname "${path}")"
+  printf '%s' "${content}" > "${path}"
+  echo "wrote ${path#"${ROOT}"/}"
+}
+
+SCOPE_CONTENT=$(cat <<EOF
+# B0/B1 scope for knowledge-graph bootstrap (edit before propose).
+schema_version: 1
+product_name: ${PRODUCT_NAME}
+primary_language: zh-CN
+repo_kind: single-service
+include_paths:
+  - src/**
+  - services/**
+  - apps/**
+  - packages/**
+  - features/**
+  - docs/**
+  - README.md
+exclude_paths:
+  - node_modules/**
+  - dist/**
+  - .harness/**
+  - "**/*.min.js"
+id_namespace:
+  domain_prefix: DOM
+  service_prefix: SVC
+  api_prefix: API
+seed_domains: []
+seed_services: []
+seed_features: []
+assumptions: []
+out_of_scope: []
+human_owners:
+  architect: ""
+  qa: ""
+EOF
+)
+
+STATUS_CONTENT=$(cat <<EOF
+# Bootstrap status machine (see docs/design/knowledge-graph-ai-bootstrap.md §4)
+schema_version: 1
+bootstrap_id: ${BOOTSTRAP_ID}
+repo_root: .
+phase: B2
+updated_at: ${TS}
+scope_ref: knowledge/bootstrap/scope.yaml
+inventory_ref: knowledge/bootstrap/inventory.json
+last_run_dir: ""
+stats:
+  entities_proposed: 0
+  entities_asserted: 0
+  edges_proposed: 0
+  edges_asserted: 0
+  features_linked: 0
+blockers: []
+next_actions:
+  - "Edit knowledge/bootstrap/scope.yaml (include/exclude, seeds)"
+  - "Run knowledge-graph-bootstrap DAG or inventory step (B2+)"
+EOF
+)
+
+README_KB=$(cat <<'EOF'
+# Knowledge base
+
+Structured project knowledge (Git is authority).
+
+- `bootstrap/` — AI graph init workspace (staging only until promote)
+- `graph/` — materialize indexes (`entities-index.yaml`, `edges.yaml`)
+- `domains|services|modules/` — formal asserted entities after promote
+- `testing/` — shared testing standards (L0), Feature packs live under `features/<F>/testing/`
+
+## Bootstrap (B1+)
+
+```bash
+bash scripts/kb-bootstrap-init-skeleton.sh --root .
+# edit knowledge/bootstrap/scope.yaml
+loop-agent dag run-task <id> --profile knowledge-graph-bootstrap
+```
+
+## Query (Phase A design)
+
+```bash
+# when available:
+# bash scripts/kb-query.sh --mode by_feature --feature F-2026-004 --json
+```
+
+See `docs/design/knowledge-graph-and-query-spec.md` and `docs/design/knowledge-graph-ai-bootstrap.md`.
+EOF
+)
+
+README_BOOTSTRAP=$(cat <<'EOF'
+# Knowledge-graph bootstrap workspace
+
+- `scope.yaml` — human scope (required for preflight)
+- `status.yaml` — phase machine B0–B6
+- `inventory.json` — B2 deterministic scan output
+- `staging/**` — **only** AI write area before promote
+- `runs/**` — per-run reports
+
+AI must never set `confidence: asserted`. Promote merges new files into formal trees.
+EOF
+)
+
+README_GRAPH=$(cat <<'EOF'
+# Graph indexes
+
+Generated by materialize (B6):
+
+- `entities-index.yaml`
+- `edges.yaml`
+- `edges.manual.yaml` — human/AI-promoted edges source (optional)
+
+Do not hand-edit generated indexes without re-running materialize.
+EOF
+)
+
+STAGING_NOTES=$(cat <<'EOF'
+# Staging notes
+
+AI proposals only. Promote copies new files into `knowledge/domains|services|modules` and feature knowledge-links.
+EOF
+)
+
+EDGES_PROPOSED=$(cat <<'EOF'
+schema_version: 1
+updated_at: null
+edges: []
+EOF
+)
+
+write_if_missing "${ROOT}/knowledge/bootstrap/scope.yaml" "${SCOPE_CONTENT}"$'\n'
+write_if_missing "${ROOT}/knowledge/bootstrap/status.yaml" "${STATUS_CONTENT}"$'\n'
+write_if_missing "${ROOT}/knowledge/README.md" "${README_KB}"$'\n'
+write_if_missing "${ROOT}/knowledge/bootstrap/README.md" "${README_BOOTSTRAP}"$'\n'
+write_if_missing "${ROOT}/knowledge/graph/README.md" "${README_GRAPH}"$'\n'
+write_if_missing "${ROOT}/knowledge/bootstrap/staging/coverage-notes.md" "${STAGING_NOTES}"$'\n'
+write_if_missing "${ROOT}/knowledge/bootstrap/staging/edges.proposed.yaml" "${EDGES_PROPOSED}"$'\n'
+write_if_missing "${ROOT}/knowledge/bootstrap/staging/notes.md" "# bootstrap staging"$'\n'
+
+# Placeholders so empty trees are visible in git if desired (optional .gitkeep)
+for d in \
+  "${ROOT}/knowledge/bootstrap/runs" \
+  "${ROOT}/knowledge/bootstrap/staging/domains" \
+  "${ROOT}/knowledge/bootstrap/staging/services" \
+  "${ROOT}/knowledge/bootstrap/staging/modules" \
+  "${ROOT}/knowledge/domains" \
+  "${ROOT}/knowledge/services" \
+  "${ROOT}/knowledge/modules"
+do
+  write_if_missing "${d}/.gitkeep" ""
+done
+
+echo
+echo "B1 skeleton ready under ${ROOT}/knowledge/"
+echo "  scope:   knowledge/bootstrap/scope.yaml"
+echo "  status:  knowledge/bootstrap/status.yaml (phase: B2)"
+echo "Next: edit scope.yaml, then run knowledge-graph-bootstrap DAG."