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

package/docs/templates/knowledge-graph-bootstrap-dag.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "./agent-dag.schema.json",
+  "version": 2,
+  "title": "Knowledge-graph bootstrap DAG template",
+  "objective": "AI-assisted business knowledge graph initialization: inventory repo signals, propose entities/edges under staging only, validate, review-gate, promote without overwrite, materialize query indexes.",
+  "successCriteria": [
+    "preflight requires knowledge/bootstrap/scope.yaml and status.yaml",
+    "inventory writes knowledge/bootstrap/inventory.json",
+    "propose-pi writes only knowledge/bootstrap/staging/** with evidence and non-asserted confidence",
+    "validate-shell fails on empty staging, missing edges.proposed/coverage-notes, or self-asserted confidence",
+    "multi-perspective review (structure/evidence/safety) each emit VERDICT; aggregate gate requires all pass before promote",
+    "promote merges new formal files only (no overwrite)",
+    "materialize writes knowledge/graph/entities-index.yaml and edges.yaml"
+  ],
+  "globalConstraints": [
+    "AI must never set confidence: asserted.",
+    "Do not modify src/** or Feature testing verdict/cases via bootstrap.",
+    "Promote must not overwrite existing formal knowledge files.",
+    "Complete B0/B1 skeleton before running this DAG."
+  ],
+  "defaults": {
+    "executor": "shell",
+    "contextProfile": "slim",
+    "writePolicy": "read-only"
+  },
+  "tasks": [
+    {
+      "id": "kg-bootstrap-preflight-shell",
+      "depends_on": [],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "subtask_prompt": "Require bootstrap skeleton."
+    },
+    {
+      "id": "kg-bootstrap-inventory-shell",
+      "depends_on": ["kg-bootstrap-preflight-shell"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "exclusive",
+      "writeSet": ["knowledge/bootstrap/inventory.json"],
+      "subtask_prompt": "B2 inventory."
+    },
+    {
+      "id": "kg-bootstrap-propose-pi",
+      "depends_on": ["kg-bootstrap-inventory-shell"],
+      "role": "implementer",
+      "executor": "pi",
+      "toolProfile": "write",
+      "complexity": "HIGH",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "knowledge/bootstrap/staging/**",
+        "knowledge/bootstrap/runs/**"
+      ],
+      "subtask_prompt": "B3 AI proposals in staging only; never asserted."
+    },
+    {
+      "id": "kg-bootstrap-validate-shell",
+      "depends_on": ["kg-bootstrap-propose-pi"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "subtask_prompt": "B4 validate staging."
+    },
+    {
+      "id": "kg-bootstrap-review-pi",
+      "depends_on": ["kg-bootstrap-validate-shell"],
+      "role": "reviewer",
+      "executor": "pi",
+      "complexity": "HIGH",
+      "writePolicy": "read-only",
+      "outputContract": "First line VERDICT: pass or VERDICT: request-revision.",
+      "subtask_prompt": "Review staging quality."
+    },
+    {
+      "id": "kg-bootstrap-review-gate-shell",
+      "depends_on": ["kg-bootstrap-review-pi"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "read-only",
+      "subtask_prompt": "Gate on VERDICT: pass."
+    },
+    {
+      "id": "kg-bootstrap-promote-shell",
+      "depends_on": ["kg-bootstrap-review-gate-shell"],
+      "role": "verifier",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "knowledge/domains/**",
+        "knowledge/services/**",
+        "knowledge/modules/**",
+        "knowledge/graph/edges.manual.yaml",
+        "features/**/knowledge-links.yaml"
+      ],
+      "subtask_prompt": "B5 promote new files only."
+    },
+    {
+      "id": "kg-bootstrap-materialize-shell",
+      "depends_on": ["kg-bootstrap-promote-shell"],
+      "role": "closeout",
+      "executor": "shell",
+      "complexity": "LOW",
+      "writePolicy": "exclusive",
+      "writeSet": [
+        "knowledge/graph/entities-index.yaml",
+        "knowledge/graph/edges.yaml"
+      ],
+      "subtask_prompt": "B6 materialize indexes."
+    }
+  ]
+}

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

@@ -0,0 +1,178 @@
+{
+  "$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",
+    "multi-perspective review (qa/domain/evidence) each emit VERDICT; aggregate gate requires all pass before apply",
+    "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/templates/product-line/AGENTS.md

@@ -1,8 +1,8 @@
-# Product-line execution rules
-
-- Read requirement, acceptance, design, test plan, task graph, and the selected TaskSpec before writing.
-- Treat `constraints.allowed_paths` and `constraints.forbidden_paths` as machine-enforced write boundaries; review DAG writer `writeSet` before execution.
-- Advance only tasks whose dependencies are complete. Preserve failed run records; retries receive new worker run IDs.
-- A Ready task must have acceptance references, non-empty allowed/forbidden paths, and deterministic verification commands.
-- QA records an independent verdict and evidence. Do not write `status: success` closeout until `qa_verdict: pass` and non-empty `qa_evidence` exist.
-- Human gates remain human decisions. Record owner, time, reason, evidence, and follow-up without rewriting failed history.
+# Product-line execution rules
+
+- Read requirement, acceptance, design, test plan, task graph, and the selected TaskSpec before writing.
+- Treat `constraints.allowed_paths` and `constraints.forbidden_paths` as machine-enforced write boundaries; review DAG writer `writeSet` before execution.
+- Advance only tasks whose dependencies are complete. Preserve failed run records; retries receive new worker run IDs.
+- A Ready task must have acceptance references, non-empty allowed/forbidden paths, and deterministic verification commands.
+- QA records an independent verdict and evidence. Do not write `status: success` closeout until `qa_verdict: pass` and non-empty `qa_evidence` exist.
+- Human gates remain human decisions. Record owner, time, reason, evidence, and follow-up without rewriting failed history.

package/docs/templates/product-line/README.md

@@ -1,9 +1,9 @@
-# Product-line feature packet
-
-Copy this directory for each product feature. Replace angle-bracket placeholders, keep IDs stable, and run:
-
-```bash
-agent-worker task validate-feature <feature-dir>
-```
-
-The validator checks acceptance ID uniqueness, task references and dependencies, cycles, TaskSpec/path/verification completeness, and QA evidence before a successful closeout.
+# Product-line feature packet
+
+Copy this directory for each product feature. Replace angle-bracket placeholders, keep IDs stable, and run:
+
+```bash
+agent-worker task validate-feature <feature-dir>
+```
+
+The validator checks acceptance ID uniqueness, task references and dependencies, cycles, TaskSpec/path/verification completeness, and QA evidence before a successful closeout.

package/docs/templates/product-line/acceptance.yaml

@@ -1,14 +1,14 @@
-schema_version: 1
-feature_id: F-YYYY-NNN
-acceptance:
-  - id: AC-FEATURE-001
-    title: Observable outcome is delivered
-    priority: must
-    type: behavior
-    given: the documented precondition
-    when: the user or system performs the action
-    then: the observable result occurs
-    verification:
-      expected_task_refs:
-        - BE-001
-        - QA-001
+schema_version: 1
+feature_id: F-YYYY-NNN
+acceptance:
+  - id: AC-FEATURE-001
+    title: Observable outcome is delivered
+    priority: must
+    type: behavior
+    given: the documented precondition
+    when: the user or system performs the action
+    then: the observable result occurs
+    verification:
+      expected_task_refs:
+        - BE-001
+        - QA-001

package/docs/templates/product-line/closeout.yaml

@@ -1,9 +1,9 @@
-schema_version: 1
-feature_id: F-YYYY-NNN
-status: success
-qa_verdict: pass
-qa_evidence:
-  - <run-or-report-path>
-owner: <human owner>
-decided_at: <ISO-8601 timestamp>
-summary: <what shipped and why evidence is sufficient>
+schema_version: 1
+feature_id: F-YYYY-NNN
+status: success
+qa_verdict: pass
+qa_evidence:
+  - <run-or-report-path>
+owner: <human owner>
+decided_at: <ISO-8601 timestamp>
+summary: <what shipped and why evidence is sufficient>

package/docs/templates/product-line/design.md

@@ -1,13 +1,13 @@
-# Design — <Feature title>
-
-## Context and boundaries
-
-Describe existing components, public contracts, trust boundaries, and protected areas.
-
-## Proposed change
-
-Describe the smallest end-to-end path and its failure behavior.
-
-## Decisions and alternatives
-
-Record material trade-offs and link ADRs where needed.
+# Design — <Feature title>
+
+## Context and boundaries
+
+Describe existing components, public contracts, trust boundaries, and protected areas.
+
+## Proposed change
+
+Describe the smallest end-to-end path and its failure behavior.
+
+## Decisions and alternatives
+
+Record material trade-offs and link ADRs where needed.

package/docs/templates/product-line/links.md

@@ -1,10 +1,10 @@
-# Traceability links
-
-| Relationship | Link or ID |
-|---|---|
-| Feature | `F-YYYY-NNN` |
-| Acceptance → tests | `AC-FEATURE-001` → `TC-001` |
-| Acceptance → tasks | `AC-FEATURE-001` → `BE-001`, `QA-001` |
-| Task → worker/DAG run | `<workerRunId>` / `<dagRunId>` |
-| Change/MR/PR | `<link>` |
-| QA evidence | `<artifact path or link>` |
+# Traceability links
+
+| Relationship | Link or ID |
+|---|---|
+| Feature | `F-YYYY-NNN` |
+| Acceptance → tests | `AC-FEATURE-001` → `TC-001` |
+| Acceptance → tasks | `AC-FEATURE-001` → `BE-001`, `QA-001` |
+| Task → worker/DAG run | `<workerRunId>` / `<dagRunId>` |
+| Change/MR/PR | `<link>` |
+| QA evidence | `<artifact path or link>` |

package/docs/templates/product-line/requirement.md

@@ -1,17 +1,17 @@
-# <Feature title>
-
-- Feature ID: `<F-YYYY-NNN>`
-- Owner: `<human owner>`
-- Outcome: `<user or business outcome>`
-
-## In scope
-
-- `<observable capability>`
-
-## Out of scope
-
-- `<explicit non-goal>`
-
-## Constraints
-
-- `<security, compatibility, cost, or operational boundary>`
+# <Feature title>
+
+- Feature ID: `<F-YYYY-NNN>`
+- Owner: `<human owner>`
+- Outcome: `<user or business outcome>`
+
+## In scope
+
+- `<observable capability>`
+
+## Out of scope
+
+- `<explicit non-goal>`
+
+## Constraints
+
+- `<security, compatibility, cost, or operational boundary>`

package/docs/templates/product-line/task-graph.yaml

@@ -1,15 +1,15 @@
-schema_version: 1
-feature_id: F-YYYY-NNN
-nodes:
-  - id: BE-001
-    task: BE-001.yaml
-    type: backend-feature
-    depends_on: []
-  - id: QA-001
-    task: QA-001.yaml
-    type: qa-execute
-    depends_on:
-      - BE-001
-parallel_policy:
-  max_parallel_tasks: 2
-  disallow_same_file_parallel_writes: true
+schema_version: 1
+feature_id: F-YYYY-NNN
+nodes:
+  - id: BE-001
+    task: BE-001.yaml
+    type: backend-feature
+    depends_on: []
+  - id: QA-001
+    task: QA-001.yaml
+    type: qa-execute
+    depends_on:
+      - BE-001
+parallel_policy:
+  max_parallel_tasks: 2
+  disallow_same_file_parallel_writes: true