@moretea-labs/forge 1.5.0-rc.1

package/assets/templates/helpers/workflow-contract.ts

@@ -0,0 +1,202 @@
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+export type WorkflowContract = {
+  version: string;
+  contractId: string;
+  compatibility: {
+    agents: string[];
+    repoLocalFirst: boolean;
+  };
+  externalTooling?: {
+    waza?: {
+      sourceRepo: string;
+      managedSkills: string[];
+      primaryHost: string;
+      codexPrimaryPath: string;
+      stagingCachePath: string;
+      syncMode: string;
+      hostDriftPolicy: string;
+    };
+    codexAutomationProfile?: {
+      requiredSkills: string[];
+      optionalSkills: string[];
+      mode: string;
+      source: string;
+      routes: {
+        workflowHealth: string;
+        reviewGate: string;
+        architectureDiagram: string;
+      };
+      vendoringPolicy: string;
+    };
+    diagramDesign?: {
+      skillName: string;
+      primaryHost: string;
+      codexPrimaryPath: string;
+      syncMode: string;
+      vendoringPolicy: string;
+    };
+  };
+  agenticDevelopment?: {
+    routing: {
+      productDiscovery: string;
+      complexEngineeringPlan: string;
+      designPlan: string;
+      smallOrMediumPlan: string;
+      bugOrRegression: string;
+      postImplementationReview: string;
+    };
+    dueDiligence: {
+      levels: string[];
+      explicitReportRequiredFor: string[];
+    };
+  };
+  documentation?: {
+    referenceConfigs?: {
+      source: string;
+      repoStubDirectory: string;
+      packageDirectory: string;
+      resolverCommand: string;
+      stubMarker: string;
+    };
+  };
+  helpers: {
+    runtimeDirectory?: string;
+    compatibilityDirectory?: string;
+    scripts: string[];
+  };
+  artifacts: {
+    runtimeManifest: string;
+    requiredDirectories: string[];
+    requiredFiles: string[];
+    runtimeFiles?: string[];
+  };
+  documents: {
+    spec: string;
+    currentStatus?: string;
+    planDirectory: string;
+    taskChecklist?: string;
+    deferredGoalLedger?: string;
+    researchReportsDirectory: string;
+    lessonsLog: string;
+  };
+  adoptionTemplates?: {
+    files?: Record<
+      string,
+      {
+        document: string;
+        reason: string;
+        lines: string[];
+      }
+    >;
+  };
+  migrations: {
+    legacyVersions: string[];
+    legacyPaths: string[];
+    upgrade?: {
+      strategyVersion: number;
+      supportedLegacyVersions: string[];
+      actionClasses: string[];
+      safety: {
+        removeOnlyOwnership: string;
+        unknownFiles: string;
+        customHooks: string;
+        ignoredReferenceMaterial: string;
+        localSecrets: string;
+      };
+      actions: Array<{
+        id: string;
+        signal: string;
+        action: "preserve" | "archive" | "reconfigure" | "remove";
+        risk: "low" | "medium" | "high";
+        ownership: "known_generated" | "managed_config" | "user_authored" | "user_local";
+        paths: string[];
+        targetPaths?: string[];
+        cleanupMode?: "always" | "generated_helper";
+        summary: string;
+      }>;
+    };
+  };
+};
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = SCRIPT_DIR.endsWith("/.ai/harness/scripts")
+  ? join(SCRIPT_DIR, "../../..")
+  : SCRIPT_DIR.endsWith("/assets/templates/helpers")
+    ? join(SCRIPT_DIR, "../../..")
+    : join(SCRIPT_DIR, "..");
+const LOCAL_ASSET_PATH = join(REPO_ROOT, "assets", "workflow-contract.v1.json");
+
+export function resolveAgenticDevRoot(_repoRoot = REPO_ROOT): string {
+  const configuredRoot =
+    process.env.AGENTIC_DEV_ROOT ||
+    process.env.AGENTIC_DEV_SKILL_ROOT;
+  if (configuredRoot && configuredRoot.length > 0) return configuredRoot;
+
+  if (existsSync(LOCAL_ASSET_PATH)) return REPO_ROOT;
+
+  const home = process.env.HOME;
+  if (home && home.length > 0) {
+    const candidates = [
+      join(home, "Projects", "forge"),
+      join(home, ".codex", "skills", "forge"),
+      join(home, ".claude", "skills", "forge"),
+      join(home, ".agents", "skills", "forge"),
+    ];
+
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return candidate;
+    }
+
+    return candidates[0];
+  }
+
+  return join(".forge", "skills", "forge");
+}
+
+export function resolveAgenticDevSkillRoot(repoRoot = REPO_ROOT): string {
+  return resolveAgenticDevRoot(repoRoot);
+}
+
+export function resolveUpstreamWorkflowContract(repoRoot = REPO_ROOT): string {
+  if (existsSync(LOCAL_ASSET_PATH)) return LOCAL_ASSET_PATH;
+  return join(resolveAgenticDevRoot(repoRoot), "assets", "workflow-contract.v1.json");
+}
+
+export function loadWorkflowContract(
+  contractPath = resolveUpstreamWorkflowContract()
+): WorkflowContract {
+  return JSON.parse(readFileSync(contractPath, "utf-8")) as WorkflowContract;
+}
+
+export function resolveInstalledWorkflowContract(repoRoot: string): string {
+  return join(repoRoot, ".ai", "harness", "workflow-contract.json");
+}
+
+export function resolveWorkflowContractForRepo(repoRoot: string): string {
+  const installedPath = resolveInstalledWorkflowContract(repoRoot);
+  return existsSync(installedPath) ? installedPath : resolveUpstreamWorkflowContract(repoRoot);
+}
+
+export function getHelperScripts(contract: WorkflowContract): string[] {
+  return [...contract.helpers.scripts];
+}
+
+export function getHelperRuntimeDir(contract: WorkflowContract): string {
+  return contract.helpers.dir ?? "scripts";
+}
+
+export function getRequiredDirectories(contract: WorkflowContract): string[] {
+  return [...contract.artifacts.requiredDirectories];
+}
+
+export function getRequiredFiles(contract: WorkflowContract): string[] {
+  return [...contract.artifacts.requiredFiles];
+}
+
+if (import.meta.main) {
+  const contract = loadWorkflowContract(process.argv[2] || resolveUpstreamWorkflowContract());
+  console.log(JSON.stringify(contract, null, 2));
+}

package/assets/templates/helpers/workstream-sync.sh

@@ -0,0 +1,263 @@
+#!/bin/bash
+set -euo pipefail
+
+# Contract invariant: durable capability ledgers live under tasks/workstreams.
+
+usage() {
+  cat <<'USAGE_EOF'
+Usage:
+  scripts/workstream-sync.sh ensure --block <capability-prefix> [--slug <slug>] [--title <title>] [--plan <plan-file>] [--slice <todo-id>] [--request <architecture-request>]
+USAGE_EOF
+}
+
+repo="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+repo="$(cd "$repo" && pwd)"
+cd "$repo"
+
+command_name="${1:-ensure}"
+shift || true
+
+functional_block=""
+slug=""
+title=""
+source_plan="(none)"
+current_slice="todo-01"
+request_file="(none)"
+
+json_escape() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  value="${value//$'\n'/\\n}"
+  value="${value//$'\r'/\\r}"
+  value="${value//$'\t'/\\t}"
+  printf '%s' "$value"
+}
+
+json_get() {
+  local json_input="$1"
+  local key="$2"
+  local parsed=""
+
+  if [[ -z "$json_input" ]]; then
+    return 1
+  fi
+
+  if command -v jq >/dev/null 2>&1; then
+    parsed="$(printf '%s' "$json_input" | jq -r ".$key // empty" 2>/dev/null || true)"
+  fi
+
+  if [[ -z "$parsed" ]] && command -v node >/dev/null 2>&1; then
+    parsed="$(JSON_INPUT="$json_input" JSON_KEY="$key" node -e '
+const raw = process.env.JSON_INPUT || "";
+const key = process.env.JSON_KEY || "";
+try {
+  const value = JSON.parse(raw)[key];
+  if (value === undefined || value === null) process.exit(1);
+  process.stdout.write(String(value));
+} catch {
+  process.exit(1);
+}
+' 2>/dev/null || true)"
+  fi
+
+  [[ -n "$parsed" ]] || return 1
+  printf '%s' "$parsed"
+}
+
+safe_token() {
+  local value="$1"
+  value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]')"
+  value="$(printf '%s' "$value" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  printf '%s' "${value:-workstream}"
+}
+
+validate_block() {
+  local block="$1"
+  case "$block" in
+    ""|.|..|../*|*/../*|/*|*$'\n'*|*$'\r'*)
+      return 1
+      ;;
+  esac
+  [[ -e "$block" ]]
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --block)
+      [[ -n "${2:-}" ]] || { echo "workstream-sync: --block requires a value" >&2; exit 2; }
+      functional_block="${2#./}"
+      functional_block="${functional_block%/}"
+      shift 2
+      ;;
+    --slug)
+      [[ -n "${2:-}" ]] || { echo "workstream-sync: --slug requires a value" >&2; exit 2; }
+      slug="$(safe_token "$2")"
+      shift 2
+      ;;
+    --title)
+      [[ -n "${2:-}" ]] || { echo "workstream-sync: --title requires a value" >&2; exit 2; }
+      title="$2"
+      shift 2
+      ;;
+    --plan)
+      [[ -n "${2:-}" ]] || { echo "workstream-sync: --plan requires a value" >&2; exit 2; }
+      source_plan="$2"
+      shift 2
+      ;;
+    --slice)
+      [[ -n "${2:-}" ]] || { echo "workstream-sync: --slice requires a value" >&2; exit 2; }
+      current_slice="$2"
+      shift 2
+      ;;
+    --request)
+      [[ -n "${2:-}" ]] || { echo "workstream-sync: --request requires a value" >&2; exit 2; }
+      request_file="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "workstream-sync: unknown argument: $1" >&2
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+if [[ "$command_name" != "ensure" ]]; then
+  echo "workstream-sync: unknown command: $command_name" >&2
+  usage
+  exit 2
+fi
+
+if ! validate_block "$functional_block"; then
+  echo "workstream-sync: --block must be an existing repo-relative capability prefix" >&2
+  exit 2
+fi
+
+if [[ ! -f "scripts/capability-resolver.ts" ]] || ! command -v bun >/dev/null 2>&1; then
+  echo "workstream-sync: scripts/capability-resolver.ts and bun are required" >&2
+  exit 2
+fi
+
+if ! resolver_json="$(bun scripts/capability-resolver.ts match --path "$functional_block" --format json 2>&1)"; then
+  echo "$resolver_json" >&2
+  exit 1
+fi
+
+if [[ "$(json_get "$resolver_json" "matched" || true)" != "true" ]]; then
+  echo "workstream-sync: --block must match a declared capability prefix in .ai/context/capabilities.json" >&2
+  exit 2
+fi
+
+capability_id="$(json_get "$resolver_json" "capability_id")"
+matched_prefix="$(json_get "$resolver_json" "matched_prefix")"
+architecture_domain="$(json_get "$resolver_json" "architecture_domain")"
+architecture_capability="$(json_get "$resolver_json" "architecture_capability")"
+architecture_module="$(json_get "$resolver_json" "architecture_module")"
+workstream_dir="$(json_get "$resolver_json" "workstream_dir")"
+contract_agents="$(json_get "$resolver_json" "contract_agents" || true)"
+contract_claude="$(json_get "$resolver_json" "contract_claude" || true)"
+
+if [[ -z "$slug" ]]; then
+  if [[ -n "$title" ]]; then
+    slug="$(safe_token "$title")"
+  else
+    slug="$(date '+%Y%m%d')-${architecture_capability}"
+  fi
+fi
+title="${title:-$slug}"
+workstream_file="${workstream_dir}/${slug}.md"
+event_file=".ai/harness/events.jsonl"
+iso_timestamp="$(date '+%Y-%m-%dT%H:%M:%S%z')"
+architecture_domain_file="docs/architecture/domains/${architecture_domain}.md"
+
+mkdir -p "$workstream_dir" "$(dirname "$architecture_module")" "$(dirname "$architecture_domain_file")" ".ai/harness"
+
+if [[ ! -f "$architecture_domain_file" ]]; then
+  cat > "$architecture_domain_file" <<EOF_DOMAIN
+# Architecture Domain: ${architecture_domain}
+
+> **Source**: \`.ai/context/capabilities.json\`
+
+## Capabilities
+
+- \`${capability_id}\` -> \`${architecture_module}\`
+EOF_DOMAIN
+elif ! grep -Fq "$architecture_module" "$architecture_domain_file"; then
+  {
+    echo ""
+    echo "- \`${capability_id}\` -> \`${architecture_module}\`"
+  } >> "$architecture_domain_file"
+fi
+
+if [[ ! -f "$architecture_module" ]]; then
+  cat > "$architecture_module" <<EOF_MODULE
+# Architecture Module: ${architecture_domain}/${architecture_capability}
+
+> **Capability ID**: \`${capability_id}\`
+> **Functional Block**: \`${functional_block}\`
+> **Matched Prefix**: \`${matched_prefix}\`
+> **Domain**: \`${architecture_domain}\`
+> **Capability**: \`${architecture_capability}\`
+
+## Boundary
+
+- Responsibility: Keep the capability boundary, entrypoints, runtime path, dependency rules, and local verification pointers for \`${capability_id}\`.
+- Entrypoints: \`${matched_prefix}\`
+- Runtime path: \`${matched_prefix}\`
+- Local contracts: \`${contract_agents:-none}\`, \`${contract_claude:-none}\`
+
+## Active Workstreams
+
+- \`${workstream_file}\`
+EOF_MODULE
+elif ! grep -Fq "$workstream_file" "$architecture_module"; then
+  {
+    echo ""
+    echo "- \`${workstream_file}\`"
+  } >> "$architecture_module"
+fi
+
+if [[ ! -f "$workstream_file" ]]; then
+  cat > "$workstream_file" <<EOF_WORKSTREAM
+# Workstream: ${title}
+
+> **Status**: active
+> **Capability ID**: \`${capability_id}\`
+> **Functional Block**: \`${functional_block}\`
+> **Matched Prefix**: \`${matched_prefix}\`
+> **Architecture Domain**: \`${architecture_domain}\`
+> **Architecture Capability**: \`${architecture_capability}\`
+> **Architecture Module**: \`${architecture_module}\`
+> **Source Plan**: ${source_plan}
+> **Current Slice**: ${current_slice}
+> **Last Handoff**: \`.ai/harness/handoff/current.md\`
+> **Architecture Request**: ${request_file}
+
+## Purpose
+
+Track durable multi-session progress for \`${capability_id}\` without inflating local agent instructions.
+
+## TODOs
+
+- [ ] ${current_slice}: Complete the current executable slice for \`${capability_id}\`.
+
+## Notes
+
+- Project the current slice into \`tasks/todos.md\` for a single session.
+- Keep architecture facts in \`${architecture_module}\`; keep execution progress here.
+EOF_WORKSTREAM
+fi
+
+event_json="{\"ts\":\"$(json_escape "$iso_timestamp")\",\"file_path\":\"$(json_escape "$workstream_file")\",\"severity\":\"medium\",\"functional_block\":\"$(json_escape "$functional_block")\",\"capability_id\":\"$(json_escape "$capability_id")\",\"matched_prefix\":\"$(json_escape "$matched_prefix")\",\"architecture_domain\":\"$(json_escape "$architecture_domain")\",\"architecture_capability\":\"$(json_escape "$architecture_capability")\",\"architecture_module\":\"$(json_escape "$architecture_module")\",\"workstream_dir\":\"$(json_escape "$workstream_dir")\",\"contract_agents\":\"$(json_escape "$contract_agents")\",\"contract_claude\":\"$(json_escape "$contract_claude")\",\"active_workstream\":\"$(json_escape "$workstream_file")\",\"change_type\":\"workstream-sync\",\"spawn_recommended\":false,\"contract_sync_required\":true,\"request_file\":\"$(json_escape "$request_file")\"}"
+printf '%s\n' "$event_json" >> "$event_file"
+
+if [[ -x "scripts/context-contract-sync.sh" ]]; then
+  bash "scripts/context-contract-sync.sh" sync-event --json "$event_json"
+fi
+
+echo "[WorkstreamSync] Ensured $workstream_file for $capability_id."

package/assets/templates/implementation-notes.template.md

@@ -0,0 +1,37 @@
+# Implementation Notes: {{TASK_SLUG}}
+
+> **Status**: Active
+> **Plan**: {{PLAN_FILE}}
+> **Contract**: {{CONTRACT_FILE}}
+> **Review**: {{REVIEW_FILE}}
+> **Last Updated**: {{TIMESTAMP}}
+> **Lifecycle**: notes
+
+## Design Decisions
+
+- ...
+
+## Deviations From Plan Or Spec
+
+- None recorded.
+
+## Tradeoffs Considered
+
+| Option | Decision | Reason |
+|--------|----------|--------|
+| ... | ... | ... |
+
+## Open Questions
+
+- None.
+
+## Evidence Links
+
+- Checks: `.ai/harness/checks/latest.json`
+- Run snapshots: `.ai/harness/runs/`
+
+## Promotion Candidates
+
+- Promote to `tasks/lessons.md` only after a repeated correction or failure pattern.
+- Promote to `docs/researches/` only when it is durable repo knowledge with evidence.
+- Promote to harness asset files only after verification across more than one task or fixture.

package/assets/templates/packages.template.md

@@ -0,0 +1,45 @@
+<!-- Generation: Only for monorepo (Plan D) or multi-package setups. Read packages/*/package.json -->
+# {{PROJECT_NAME}} — Package 参考
+
+> **Version**: {{CALVER_VERSION}}
+> **Last Updated**: {{DATE}}
+
+---
+
+## 总览
+
+| Package | 用途 | React 依赖 | 外部依赖 |
+|---------|------|-----------|----------|
+{{PACKAGE_OVERVIEW_TABLE}}
+
+---
+
+{{#EACH PACKAGE}}
+## {{PACKAGE_SCOPE}}/{{PACKAGE_NAME}}
+
+{{PACKAGE_DESCRIPTION}}
+
+### Exports
+
+| Export Path | 内容 |
+|-------------|------|
+{{PACKAGE_EXPORTS_TABLE}}
+
+### Source Tree
+
+```
+{{PACKAGE_SOURCE_TREE}}
+```
+
+{{#IF PACKAGE_KEY_API}}
+**关键 API**:
+{{PACKAGE_KEY_API}}
+{{/IF}}
+
+{{#IF PACKAGE_KNOWN_ISSUES}}
+**已知问题**: {{PACKAGE_KNOWN_ISSUES}}
+{{/IF}}
+
+---
+
+{{/EACH}}

package/assets/templates/plan.template.md

@@ -0,0 +1,77 @@
+# Plan: {{TITLE}}
+
+> **Status**: Draft
+> **Created**: {{TIMESTAMP}}
+> **Slug**: {{SLUG}}
+> **Spec**: `docs/spec.md`
+> **Research**: See `docs/researches/`
+> **Task Contract**: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md`
+> **Task Review**: `tasks/reviews/{{ARTIFACT_STEM}}.review.md`
+> **Implementation Notes**: `tasks/notes/{{ARTIFACT_STEM}}.notes.md`
+
+## Agentic Routing
+- Selected route:
+- Routing reason:
+- Due diligence:
+  - P1 map:
+  - P2 trace:
+  - P3 decision rationale:
+
+## Workflow Inventory
+Complete this inventory before implementation. If any line is unknown, keep the plan in Draft and fill it before projection.
+
+- Active plan: `{{PLAN_FILE}}`
+- Sprint contract: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md`
+- Sprint review: `tasks/reviews/{{ARTIFACT_STEM}}.review.md`
+- Implementation notes: `tasks/notes/{{ARTIFACT_STEM}}.notes.md`
+- Deferred-goal ledger: `tasks/todos.md`
+- Current checks: `.ai/harness/checks/latest.json`
+- Run snapshots: `.ai/harness/runs/`
+- Scope authority: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md` `allowed_paths`
+- Concurrency rule: `.ai/harness/active-plan` selects the active plan for this worktree when present; `.ai/harness/active-worktree` records the owning worktree; `.claude/.active-plan` is a legacy fallback during transition. If another worktree already owns active work, open or switch to the matching worktree instead of serializing unrelated plans.
+- Execution isolation: approved contract-level work projects through `.ai/harness/scripts/plan-to-todo.sh --plan {{PLAN_FILE}}` and may start `.ai/harness/scripts/contract-worktree.sh start --plan {{PLAN_FILE}}`.
+
+## Approach
+### Strategy
+### Trade-offs
+| Option | Pros | Cons | Decision |
+|--------|------|------|----------|
+
+## Detailed Design
+### File Changes
+| File | Action | Description |
+|------|--------|-------------|
+
+### Code Snippets
+### Data Flow
+
+## Risk Assessment
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+
+## Task Contracts
+- Contract file: `tasks/contracts/{{ARTIFACT_STEM}}.contract.md`
+- Review file: `tasks/reviews/{{ARTIFACT_STEM}}.review.md`
+- Implementation notes file: `tasks/notes/{{ARTIFACT_STEM}}.notes.md`
+- Template: `.claude/templates/contract.template.md`
+- Verification command: `bash .ai/harness/scripts/verify-contract.sh --contract tasks/contracts/{{ARTIFACT_STEM}}.contract.md --strict`
+- Active plan rule: `.ai/harness/active-plan` is authoritative for this worktree when present; `.ai/harness/active-worktree` records the owning worktree; `.claude/.active-plan` is a legacy fallback during transition. Do not infer active execution from the latest non-archived plan.
+
+## Handoff
+
+- Checks file: `.ai/harness/checks/latest.json`
+- Session handoff: `.ai/harness/handoff/current.md`
+
+## Evidence Contract
+
+- **State/progress path**:
+- **Verification evidence**:
+- **Evaluator rubric**:
+- **Stop condition**:
+- **Rollback surface**:
+
+## Annotations
+<!-- [NOTE]: prefixed inline. Claude processes all and revises. -->
+
+## Task Breakdown
+- [ ] ...