@surlymochan/evalid 0.0.0-stage → 0.3.1

package/schemas/workflow.schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openflow/schemas/workflow.schema.json",
+  "title": "XFlow Workflow Definition",
+  "type": "object",
+  "required": ["name", "version", "track", "requires", "phases"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string" },
+    "version": { "type": "integer", "minimum": 1 },
+    "description": { "type": "string" },
+    "track": { "type": "string", "enum": ["lite", "heavy"] },
+    "parallel": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max_agents": { "type": "integer", "minimum": 1, "maximum": 16 },
+        "policy": { "type": "string", "enum": ["weighted", "fixed"] }
+      }
+    },
+    "requires": {
+      "type": "object",
+      "properties": {
+        "agentos_http": { "type": "boolean" },
+        "agentos_bin": { "type": "boolean" },
+        "gh": { "type": "boolean" },
+        "pencil": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "label", "required"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" },
+          "catalog_ref": { "type": "integer", "minimum": 1, "maximum": 27 },
+          "required": { "type": "boolean" },
+          "condition": {
+            "type": "object",
+            "description": "Skip phase unless condition met",
+            "properties": {
+              "input_field": { "type": "string" },
+              "equals": {}
+            }
+          },
+          "atoms": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id"],
+              "properties": {
+                "id": { "type": "string" },
+                "with": { "type": "object" },
+                "parallel_group": { "type": "string" },
+                "parallel_weight": { "type": "integer", "minimum": 1, "maximum": 16 }
+              }
+            }
+          },
+          "preconditions": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "phase_artifact": { "type": "string" },
+                "predicate": { "type": "string", "enum": ["exists", "nonempty", "equals", "truthy"] },
+                "value": {}
+              }
+            }
+          },
+          "artifacts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["path"],
+              "properties": {
+                "path": { "type": "string" },
+                "optional": { "type": "boolean", "default": false }
+              }
+            }
+          },
+          "gate": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": { "type": "string", "enum": ["deterministic", "artifact-verify", "llm-judge", "human", "skip"] },
+              "atom": { "type": "string" },
+              "with": { "type": "object" },
+              "on_fail": { "type": "string", "enum": ["stop", "retry", "advance-with-warning"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/run-tests.mjs

@@ -0,0 +1,23 @@
+import { spawnSync } from 'node:child_process';
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const repoRoot = process.cwd();
+const requestedFiles = process.argv.slice(2);
+const testFiles = requestedFiles.length > 0
+  ? requestedFiles
+  : readdirSync(resolve(repoRoot, 'test'))
+    .filter((name) => name.endsWith('.test.js'))
+    .sort()
+    .map((name) => `test/${name}`);
+
+for (const testFile of testFiles) {
+  const result = spawnSync(process.execPath, [testFile], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}

package/scripts/takein_digest.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Generate a compact xflow takeover digest from project handoff artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+
+
+ROOT_FILES = ("HANDOFF.md", "AHA.md", "DESIGN.md")
+
+
+def run_git(project_root: Path, args: list[str]) -> str:
+    try:
+        return subprocess.run(
+            ["git", *args],
+            cwd=project_root,
+            check=True,
+            text=True,
+            capture_output=True,
+        ).stdout.strip()
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return ""
+
+
+def read_excerpt(path: Path, limit: int) -> dict[str, object]:
+    if not path.exists():
+        return {
+            "path": str(path),
+            "exists": False,
+            "excerpt": "",
+            "line_count": 0,
+            "truncated": False,
+        }
+
+    lines = path.read_text(encoding="utf-8").splitlines()
+    excerpt_lines = lines[:limit]
+    return {
+      "path": str(path),
+      "exists": True,
+      "excerpt": "\n".join(excerpt_lines),
+      "line_count": len(lines),
+      "truncated": len(lines) > limit,
+    }
+
+
+def build_digest(project_root: Path, excerpt_lines: int) -> dict[str, object]:
+    project_root = project_root.expanduser().resolve()
+    files = {name: read_excerpt(project_root / name, excerpt_lines) for name in ROOT_FILES}
+    status = run_git(project_root, ["status", "-sb"])
+    branch = run_git(project_root, ["branch", "--show-current"])
+    head = run_git(project_root, ["log", "-1", "--oneline", "--decorate"])
+    origin_head = run_git(project_root, ["rev-parse", "--verify", "origin/HEAD"])
+
+    warnings: list[str] = []
+    if not files["HANDOFF.md"]["exists"]:
+        warnings.append("HANDOFF.md is missing; intake context is incomplete.")
+    if not files["AHA.md"]["exists"]:
+        warnings.append("AHA.md is missing; durable lessons may be unavailable.")
+    if status and "\n" in status:
+        warnings.append("Working tree is dirty; stage deliberately and avoid blanket reset commands.")
+
+    return {
+        "project_root": str(project_root),
+        "git": {
+            "branch": branch or None,
+            "head": head or None,
+            "origin_head": origin_head or None,
+            "status_sb": status or None,
+        },
+        "files": files,
+        "warnings": warnings,
+        "recommended_first_action": "Compare HANDOFF/AHA claims against git status, then inspect only files directly relevant to the active objective.",
+    }
+
+
+def render_markdown(digest: dict[str, object]) -> str:
+    git = digest["git"]
+    files = digest["files"]
+    warnings = digest["warnings"]
+    lines = [
+        "# xflow Takein Digest",
+        "",
+        f"Project root: `{digest['project_root']}`",
+        f"Branch: `{git.get('branch') or 'unknown'}`",
+        f"HEAD: `{git.get('head') or 'unknown'}`",
+        "",
+        "## Git Status",
+        "",
+        "```text",
+        git.get("status_sb") or "(unavailable)",
+        "```",
+        "",
+        "## Warnings",
+        "",
+    ]
+    if warnings:
+        lines.extend(f"- {warning}" for warning in warnings)
+    else:
+        lines.append("- None")
+    lines.extend(["", "## Artifacts", ""])
+    for name, payload in files.items():
+        exists = "present" if payload["exists"] else "missing"
+        truncated = " truncated" if payload["truncated"] else ""
+        lines.extend([
+            f"### {name} ({exists}, {payload['line_count']} lines{truncated})",
+            "",
+            "```markdown",
+            payload["excerpt"] or "",
+            "```",
+            "",
+        ])
+    lines.extend([
+        "## Recommended First Action",
+        "",
+        str(digest["recommended_first_action"]),
+    ])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--project-root", default=".", help="Project root containing HANDOFF.md and AHA.md.")
+    parser.add_argument("--excerpt-lines", type=int, default=160, help="Maximum lines to include per artifact.")
+    parser.add_argument("--json", action="store_true", help="Print JSON instead of markdown.")
+    args = parser.parse_args()
+
+    digest = build_digest(Path(args.project_root), max(1, args.excerpt_lines))
+    if args.json:
+        print(json.dumps(digest, indent=2, ensure_ascii=False))
+    else:
+        print(render_markdown(digest), end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/specs/README.md

@@ -0,0 +1,118 @@
+# Specs
+
+This directory is the single Superflow-owned root directory at the project root.
+
+It has two layers:
+
+- `specs/*.md` for durable project source-of-truth specs
+- `specs/changes/<change-id>/` for per-change working artifacts
+
+## Layout
+
+```text
+specs/
+|-- README.md
+|-- product.md
+|-- architecture.md
+|-- workflow.md
+|-- ux.md                # optional (or use DESIGN.md)
+|-- DESIGN.md            # optional design system
+`-- changes/
+    `-- <change-id>/
+        |-- proposal.md
+        |-- plan.md
+        |-- findings.md         # optional research notes for long or uncertain changes
+        |-- progress.md         # optional rolling status for long-running changes
+        |-- status.json
+        |-- design.md            # if frontend/UI change
+        |-- merge-product.md     # optional
+        |-- merge-architecture.md
+        |-- merge-workflow.md
+        |-- merge-ux.md
+        `-- merge-design.md      # if design change
+```
+
+## Root specs vs change specs
+
+Use root specs for durable truth:
+
+- `product.md`
+  - product goals
+  - accepted behavior
+  - scope boundaries
+- `architecture.md`
+  - system shape
+  - module boundaries
+  - technical invariants
+- `workflow.md`
+  - delivery rules
+  - QA / review / release rules
+- `ux.md` / `DESIGN.md`
+  - visual tone
+  - color system
+  - typography
+  - layout rules
+  - component patterns
+
+Use `specs/changes/<change-id>/` for change-scoped work:
+
+- proposal
+- plan
+- design reasoning (if UI)
+- machine-readable state
+- explicit archive merge snippets
+
+`xflow:plan` only writes `plan.md`. It does not create `tasks.md`.
+
+For research-heavy or long-running changes, `findings.md` and `progress.md`
+may be added as auxiliary notes. They are optional and do not replace the plan.
+
+## DESIGN.md
+
+`DESIGN.md` is the canonical design system file.
+
+It follows the format from Google Stitch / awesome-design-md.
+
+Use it OR `specs/ux.md` — never both with overlapping content.
+
+When a change involves UI:
+
+1. Check if `DESIGN.md` exists
+2. If not, create one from template
+3. Run design-check in yolo workflow
+4. Archive design decisions to Design Decisions Log
+
+## Archive rule
+
+Do not treat `proposal.md`, `plan.md`, or `design.md` as automatic sources for root spec updates.
+
+When a change produces durable truth, write the exact durable facts into explicit merge files:
+
+- `merge-product.md`
+- `merge-architecture.md`
+- `merge-workflow.md` for workflow or capability deltas
+- `merge-ux.md`
+- `merge-design.md`
+
+Archive should prefer these explicit merge files over trying to summarize large documents.
+
+This is intentional:
+
+- it reduces accidental deletion of older truth
+- it reduces under-summary or over-summary of the current change
+- it keeps the durable root specs stable and auditable
+
+## Status rule
+
+`status.json` is the machine-readable state for the active change.
+
+Use it to track:
+
+- change type (backend | frontend | full-stack | infrastructure | docs)
+- current stage
+- verification state
+- design alignment (if frontend)
+- archival readiness
+- next action
+
+Do not use it as a replacement for the human-readable plan or proposal.

package/specs/architecture.md

@@ -0,0 +1,36 @@
+# Architecture Spec
+
+## System Shape
+
+- Major modules and boundaries.
+
+## Data Flow
+
+- Main request / event / state flow.
+
+## Technical Constraints
+
+- Durable invariants and constraints.
+
+## Notes
+
+- Long-lived architecture decisions land here after archive.
+
+
+## Change: timeline-analytics
+
+Source: `specs/changes/timeline-analytics/merge-architecture.md`
+Archived: 2026-04-16T15:52:04Z
+
+- Timeline analytics remain derived data. `src/server.js` computes analytics from `getMissionDetail(...).timeline` and does not persist a second summary model.
+- Active workflow run cleanup is centralized around the in-memory `activeWorkflowRuns` map plus `.as-xflow/active-runs.json` persistence. Orphan acknowledge deletes the matching active run entry, rewrites touched project roots, and updates the rerun record with `acknowledged_at` audit metadata.
+- Rerun history is never physically deleted as part of orphan cleanup. Audit state stays in `reruns` and `operator_actions`; only the active-run control surface is cleared.
+
+
+## Change: handoff-current-state
+
+Source: `specs/changes/handoff-current-state/merge-architecture.md`
+Archived: 2026-04-16T16:09:18Z
+
+- Root handoff current-state facts are now generated from local status and git state by `xflow/handoff/scripts/scaffold_handoff.py`.
+- The generated handoff block is intentionally narrow: it does not synthesize a full Context Pack and does not query GitHub for merge state. It reduces drift for high-risk execution metadata while preserving human-authored durable context.

package/specs/product.md

@@ -0,0 +1,33 @@
+# Product Spec
+
+## Purpose
+
+- What the product exists to do.
+
+## Core User Journeys
+
+- Primary journey:
+
+## Scope Boundaries
+
+- In scope:
+- Out of scope:
+
+## Accepted Behavior
+
+- Durable product requirements land here after archive.
+
+
+## Change: timeline-analytics
+
+Source: `specs/changes/timeline-analytics/merge-product.md`
+Archived: 2026-04-16T15:52:04Z
+
+- Control-plane mission timeline now has a derived analytics endpoint:
+  - `GET /api/missions/:missionId/timeline/analytics`
+  - returns event totals, event kind distribution, time range, rerun status/mode counts, operator action kind/status counts, phase run counts, and phase run session derived-status counts.
+- Operators can explicitly acknowledge a recovered orphan rerun:
+  - `POST /api/missions/:missionId/reruns/:rerunId` with `{"action":"acknowledge-orphan"}`
+  - only `orphaned` reruns are eligible.
+  - acknowledged orphan reruns remain auditable in mission detail as `canceled` and include a `rerun_orphan_acknowledge` operator action.
+  - acknowledged orphan runs are removed from active run summary and `.as-xflow/active-runs.json`.