@cassiomc1/forgeloop 1.12.0 → 1.13.0

package/docs/protocol-requirements.json

@@ -0,0 +1,77 @@
+{
+  "version": 1,
+  "requirements": {
+    "FL-CONT-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A receiving harness MUST reconcile continuity against the current work state and checkout before acting on it.",
+      "tests": ["tests/continuity.test.js", "tests/documentation-conformance.test.js"],
+      "validator": "src/core/continuity.js"
+    },
+    "FL-CLAIM-001": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "Every harness MUST consume the canonical validated claim-state resolver.",
+      "tests": ["tests/task-claim-state.test.js", "tests/task-recovery-tamper.test.js"],
+      "validator": "src/core/task-claim-state.js"
+    },
+    "FL-CLAIM-002": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "Readers without task-recovery schema v1 support MUST refuse claim ownership mutation.",
+      "tests": ["tests/protocol-info.test.js", "tests/documentation-conformance.test.js"],
+      "validator": "scripts/validate_documentation_conformance.mjs"
+    },
+    "FL-CLAIM-003": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "A reader without validated claim projection MUST fail closed.",
+      "tests": ["tests/protocol-info.test.js", "tests/package.test.js"],
+      "validator": "src/core/protocol-info.js"
+    },
+    "FL-WS-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A bound task MUST validate the current workspace before a task mutation or ForgeLoop-owned verification launch.",
+      "tests": ["tests/workspace-binding.test.js", "tests/workspace-binding-run-check.test.js"],
+      "validator": "src/core/workspace-binding.js"
+    },
+    "FL-HANDOFF-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A canonical handoff MUST remain an immutable protocol-derived snapshot.",
+      "tests": ["tests/handoff-envelope.test.js"],
+      "validator": "src/core/handoff.js"
+    },
+    "FL-SCOPE-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A verification scope MUST narrow execution only from current canonical evidence.",
+      "tests": ["tests/verification-scope.test.js", "tests/verification-scope-freshness.test.js"],
+      "validator": "src/core/verification-scope.js"
+    },
+    "FL-ATTEST-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A code attestation MUST bind exact source content to a valid completion receipt and event-ledger checkpoint.",
+      "tests": ["tests/code-manifest.test.js", "tests/attestation.test.js", "tests/attestation-verifier.test.js"],
+      "validator": "src/core/attestation-verifier.js"
+    },
+    "FL-ATTEST-002": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "An integration MUST consume the canonical attestation result and preserve its trust distinctions.",
+      "tests": ["tests/generic-ci-attestation.test.js", "tests/integration-runtime.test.js"],
+      "validator": "src/core/command-runtime.js"
+    },
+    "FL-ATTEST-003": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "A signing integration MUST keep private keys, OIDC tokens, and credentials outside ForgeLoop artifacts.",
+      "tests": ["tests/signing-provider.test.js"],
+      "validator": "src/core/signing/"
+    },
+    "FL-SQ-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "Structural-quality evidence MUST remain provider-neutral, task-bound, delta-first, and separate from behavioral, security, performance, accessibility, and publication truth.",
+      "tests": ["tests/structural-quality-policy.test.js", "tests/structural-quality-lifecycle.test.js"],
+      "validator": "src/core/structural-quality/service.js"
+    },
+    "FL-SQ-002": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "A structural-quality integration MUST preserve unavailable, malformed, stale, incomparable, and blocked provider results without promoting them to PASS.",
+      "tests": ["tests/sentrux-structural-quality-provider.test.js", "tests/structural-quality-artifacts.test.js"],
+      "validator": "src/core/structural-quality/provider.js"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -51,6 +51,9 @@
     ".github/copilot-instructions.md",
     "README.md",
     "DOCS_INDEX.md",
+    "CONTRIBUTING.md",
+    "docs/documentation-manifest.json",
+    "docs/protocol-requirements.json",
     "docs/diagrams",
     "docs/assets/diagrams",
     "docs/GETTING_STARTED.md",
@@ -103,6 +106,10 @@
   ],
   "scripts": {
     "test": "node scripts/run-tests.js",
+    "test:ci": "node scripts/run-tests.js --test-concurrency=2",
+    "test:watch": "node scripts/run-tests.js --watch",
+    "coverage:shard": "c8 --all --include=src/**/*.js --temp-directory=coverage-data npm run test:ci",
+    "coverage:report": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --reporter=json-summary --temp-directory=coverage-data --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 report",
     "pack:check": "node --test tests/package.test.js",
     "pack:smoke": "node scripts/package_smoke.mjs",
     "release:identity": "node scripts/verify_release_identity.mjs",
@@ -116,12 +123,12 @@
     "docs:report": "node scripts/report_documentation_health.mjs",
     "docs:check": "node scripts/run-docs-check.js",
     "lint": "eslint .",
-    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --reporter=json-summary --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 node scripts/run-tests.js",
+    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --reporter=json-summary --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 npm run test:ci",
     "dependency:policy": "node scripts/check-dependency-policy.mjs",
     "mcp:test": "node scripts/run-mcp-tests.mjs",
     "completions:generate": "node scripts/generate-shell-completions.mjs --write",
     "completions:check": "node scripts/generate-shell-completions.mjs --check",
-    "test:quick": "node --test tests/cli.test.js tests/schema-health.test.js tests/schema-golden.test.js tests/protocol-info.test.js tests/integration-capabilities.test.js",
+    "test:quick": "node --test tests/cli.test.js tests/schema-health.test.js tests/schema-golden.test.js tests/protocol-info.test.js tests/integration-capabilities.test.js tests/ci-classify.test.js tests/validation-tiers.test.js",
     "performance:check": "node scripts/benchmark-cli-startup.mjs",
     "critical-coverage:check": "node scripts/check-critical-coverage.mjs",
     "changelog:check": "node scripts/check-changelog-freshness.mjs",
@@ -140,7 +147,12 @@
     "benchmark:profiles:regression": "node scripts/check-efficiency-regression.mjs",
     "transactions:compact": "node scripts/compact-transactions.mjs",
     "complexity:check": "node scripts/check-complexity.mjs",
-    "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs"
+    "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs",
+    "task-discovery:benchmark": "node scripts/benchmark-task-discovery.mjs",
+    "verify:fast": "node scripts/run-validation.mjs --tier fast",
+    "verify:local": "node scripts/run-validation.mjs --tier local",
+    "verify:prepush": "node scripts/run-validation.mjs --tier prepush",
+    "verify:release": "node scripts/run-validation.mjs --tier release"
   },
   "devDependencies": {
     "c8": "^12.0.0",
@@ -148,6 +160,9 @@
     "typescript": "7.0.2",
     "yaml": "2.9.0"
   },
+  "dependencies": {
+    "smol-toml": "1.8.0"
+  },
   "exports": {
     ".": "./src/cli.js",
     "./integration": {

package/schemas/routing-input.schema.json

@@ -18,7 +18,7 @@
       "properties": {
         "schemaVersion": { "const": 1 },
         "scope": { "enum": ["MATCH", "UNSCOPED", "NO_MATCH", "NONE"] },
-        "frameworks": { "type": "array", "items": { "enum": ["flutter"] } },
+        "frameworks": { "type": "array", "items": { "enum": ["flutter", "dotnet", "aspnetcore", "abp", "nodejs", "rust", "c", "cpp", "java", "sql", "go", "typescript", "php", "swift"] } },
         "projectRoots": { "type": "array", "items": { "type": "string", "minLength": 1 } },
         "primarySignals": { "type": "array", "items": { "type": "string", "minLength": 1 } },
         "supportingSignals": { "type": "array", "items": { "type": "string", "minLength": 1 } }

package/scripts/CI_VALIDATORS.md

@@ -41,26 +41,99 @@ Maintainers should distinguish between actual documentation link failures and ex
 - **Link-content failure (`Lychee`)**: The link checking step runs with `--verbose` and outputs the exact failing URL along with the HTTP status code (e.g. 404, 403). If a documentation URL is broken, update the link in the source Markdown. If a legitimate external host blocks shared CI runners or aggressively rate-limits CI automation, add a minimal, targeted exclusion in `.lychee.toml` with an explanatory comment.
 - **Action-download / Runner infrastructure failure (GitHub 429/502/503)**: When GitHub Actions fails during action checkout or tool download before running the test steps, this is a transient infrastructure issue rather than a project defect. Rerun the workflow without modifying project files.
 
-## Node verification and receipt availability
+## Validation tiers
 
-The documentation workflow runs the documentation/tooling gates once on
-Linux with Node 24. Full suites cover Linux 20/22/24 and macOS/Windows 20/24,
-with no repeated platform/version pair in that workflow. Node 24 Linux also
-collects coverage. Package-content tests share one pack listing within their
-process. The dedicated Windows main-branch workflow remains separate.
+The local runner makes the validation boundary explicit and never installs a
+missing tool implicitly:
 
-The historical required status `validate (22)` is retained as an aggregate
-gate over validation, the full portability matrix, and diagram checks. It
-fails if any prerequisite fails, is cancelled, or is skipped. This preserves
-the existing branch ruleset without running another duplicate test suite.
+| Tier | Command | Intended use |
+| --- | --- | --- |
+| Fast | `npm run verify:fast` | feedback while editing; quick Node, lint, dependency-policy, and generated-doc checks |
+| Local | `npm run verify:local` | full deterministic source, documentation, manifest, and frozen Python checks |
+| Pre-push | `npm run verify:prepush` | coverage, critical coverage, package/MCP checks, PoC checks, and the local suite expected before a PR |
+| Release | `npm run verify:release` | pre-push checks plus package smoke, benchmark/profile checks, performance, release-identity prerequisites, and `npm pack --dry-run --json` |
+
+Run `npm run mcp:setup` explicitly when the MCP package is not installed and
+the MCP checks are in scope. If Python or another external validator is
+unavailable, report `NOT_VERIFIED`; do not turn an unavailable check into a
+pass by installing an unapproved tool.
+
+The release tier reports `NOT_VERIFIED` until both
+`FORGELOOP_RELEASE_VERSION` and `FORGELOOP_RELEASE_COMMIT` are supplied. When
+present, those values are passed to the canonical `release:identity` command;
+the runner never invents a release SHA or treats a pre-publication identity as
+valid.
+
+`npm run verify:prepush` deliberately runs coverage once and does not repeat
+the full suite as a second `npm test`. `npm run lint`,
+`npm run complexity:check`, and `npm run critical-coverage:check` retain
+independent purposes: syntax and usage correctness, hotspot growth, and
+coverage of critical modules. Packed TypeScript consumers validate the public
+declarations; YAML-based tests validate workflow semantics. The core runtime
+remains dependency-free.
+
+## GitHub Actions boundary
+
+Ordinary pull requests use `.github/workflows/pr-core.yml`. It preserves the
+ruleset's exact required contexts:
+
+- `audit`
+- `CodeQL`
+- `Verify generated Archify diagram`
+- `validate (22)`
+- `tarball smoke (ubuntu-latest)`
+- `dependency-review`
+
+`validate (22)` is an always-present, fail-closed aggregator over the core
+matrix and the path-applicable documentation, audit, package, and native
+Repository Index jobs. An optional Repository Index job may be skipped only
+when the classifier says that the change cannot affect it; the aggregator
+rejects every unexpected skip, failure, or cancellation. The aggregator is
+the status required by the branch ruleset, not a second copy of the Node
+suite.
+
+The path classifier is deterministic and testable locally:
+
+```bash
+node scripts/ci-scenario-check.mjs
+node scripts/ci-classify.mjs --paths README.md --json
+node scripts/ci-classify.mjs --all --json
+```
+
+Documentation-only pull requests use quick core validation plus the
+documentation/diagram path; the Node 20 matrix steps do not install or run for
+docs-only changes. Runtime and package changes use Node 20 compatibility checks
+and four Node 24 unit shards wrapped by the coverage gate, followed by a
+coverage-only aggregation. Repository Index changes retain the native reusable
+workflow and its platform matrix. Package
+smoke is Ubuntu-only on ordinary PRs and expands to macOS/Windows through the
+explicit release matrix. The main branch retains dedicated documentation,
+Node compatibility, package smoke, audit, and Windows full-suite workflows;
+those workflows are the place for broader post-merge or release validation.
+
+CodeQL and dependency review remain independent GitHub security gates. The
+repository's GitHub secret scanning and push protection remain enabled; the
+custom `scan_secrets.py` check is a local/pre-push compatibility validator and
+is not duplicated in every ordinary PR job.
+
+## Receipts and infrastructure failures
 
 `npm run lint`, `npm run complexity:check`, and
 `npm run critical-coverage:check` retain independent purposes: syntax and
 usage correctness, hotspot growth, and coverage of critical modules. Packed
 TypeScript consumers validate the public declarations; YAML-based tests
-validate workflow semantics. The core runtime remains dependency-free.
+validate workflow semantics. The core runtime has the approved exact
+`smol-toml` dependency for bounded Cargo manifest parsing; dependency policy
+keeps all other runtime dependencies out.
 
 `scripts/audit-receipts.mjs` runs after checkout. It audits supplied scoped
 receipts with explicit task IDs, fails on an invalid audit, and reports
 `NOT_VERIFIED` when none are supplied. This repository job does not create
 lifecycle evidence from CI test results.
+
+Maintainers should distinguish actual validation failures from external
+CI/action infrastructure errors. A Lychee link failure identifies the exact
+URL and status; update Markdown or add only a targeted, explained exclusion
+for a legitimate shared-runner restriction. An action-download or runner
+failure before project steps begin (for example GitHub 429/502/503) is
+infrastructure and should be retried without changing project files.

package/scripts/generate-agent-protocol-summary.mjs

@@ -7,6 +7,8 @@ import { fileURLToPath } from "node:url";
 import { ARTIFACT_REGISTRY } from "../src/core/artifact-registry.js";
 import { CLI_COMMAND_DEFINITIONS } from "../src/core/cli-command-definitions.js";
 import { PUBLIC_ERROR_REGISTRY } from "../src/core/error-codes.js";
+import { PROJECT_DETECTION_LIMITS, PROJECT_EVIDENCE_SCHEMA_VERSION } from "../src/core/project-detection.js";
+import { GUIDE_REGISTRY } from "../src/core/guide-registry.js";
 import { protocolInfo } from "../src/core/protocol-info.js";
 
 const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -43,6 +45,12 @@ function commandCatalog() {
     .join("\n\n");
 }
 
+function guideCatalog() {
+  const rows = Object.entries(GUIDE_REGISTRY)
+    .map(([id, definition]) => [id, definition.path, definition.install ? "yes" : "no"]);
+  return `## Guide registry\n\n${table(["Guide", "Path", "Installable"], rows)}`;
+}
+
 async function render() {
   const packageJson = JSON.parse(await readFile(path.join(repositoryRoot, "package.json"), "utf8"));
   const info = protocolInfo({ packageVersion: packageJson.version });
@@ -95,6 +103,32 @@ Package version: ${packageJson.version}
 6. Run forgeloop complete; accept completion only when the validator returns VALID.
 7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
 
+## Project evidence and guide routing
+
+- The canonical guide registry is \`src/config/guides.json\`; the .NET
+  specialist has guide ID \`dotnet\` and resolves to
+  \`ENG/dotnet-aspnetcore-development-eng.md\`.
+- Project evidence schema v${PROJECT_EVIDENCE_SCHEMA_VERSION} recognizes
+  structurally parsed Flutter, SDK-style .NET, Node.js, Rust, C, C++, Java,
+  SQL, Go, TypeScript, PHP, and Swift project evidence. SQL remains a bounded
+  owned-file overlay, while same-root language identities compose. ASP.NET Core
+  and ABP are conditional overlays recorded as reasons on \`dotnet\`; they
+  are not standalone guide IDs, and route validation requires each overlay to
+  include \`dotnet\`.
+- Project detection is bounded by ${PROJECT_DETECTION_LIMITS.maxManifests}
+  manifests, ${PROJECT_DETECTION_LIMITS.maxSolutionFiles} solution files,
+  ${PROJECT_DETECTION_LIMITS.maxManifestBytes} bytes per manifest,
+  ${PROJECT_DETECTION_LIMITS.maxSourceFiles} supporting source files,
+  ${PROJECT_DETECTION_LIMITS.maxSourceBytes} bytes per source file,
+  ${PROJECT_DETECTION_LIMITS.maxVisitedDirectories} visited directories, and
+  ${PROJECT_DETECTION_LIMITS.maxVisitedEntries} visited entries. It skips
+  symlinks and configured generated/vendor directories; exhausted budgets fail
+  closed rather than producing unbounded discovery.
+- Task ownership discovery is a separate exhaustive operation. Task-list
+  filters and pagination project the validated discovery result and do not
+  remove ledger or recovery evidence. See \`GUIDE_ROUTER.md\` and
+  \`docs/CLI_REFERENCE.md\` for the operator-facing contracts.
+
 ## Adaptive execution profiles
 
 \`complianceMode\` controls how strongly project policy is enforced. The
@@ -151,6 +185,8 @@ ${table(["Feature", "Version", "Supported"], features)}
 
 ${capabilityContracts}
 
+${guideCatalog()}
+
 ## Public artifact registry
 
 ${table(["Key", "Scope", "Path", "Schema", "Trust role"], artifacts)}

package/src/commands/next.js

@@ -2,8 +2,9 @@ import { getNextAction } from "../core/next-action.js";
 import { withResolvedTask } from "../core/task-command.js";
 import { readPersistedRoute } from "../core/route-artifact.js";
 import { projectExecutionProfile } from "../core/execution-profile.js";
+import { explainNextAction } from "../core/next-explanation.js";
 
-export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false }) {
+export async function runNext({ target, packageRoot, taskId, task, authorityContext, runtimeContext, compact = false, explain = false }) {
   return withResolvedTask(target, { taskId: taskId ?? task, packageRoot }, async (ctx) => {
     const result = await getNextAction({
       target,
@@ -12,7 +13,8 @@ export async function runNext({ target, packageRoot, taskId, task, authorityCont
       authorityContext,
       runtimeContext,
     });
-    if (!compact) return result;
+    const explained = explain ? { ...result, explanation: explainNextAction(result) } : result;
+    if (!compact) return explained;
     const compactTaskId = ctx?.taskId ?? (result.taskId && result.taskId !== "unknown" ? result.taskId : null);
     let profile = null;
     try {
@@ -23,12 +25,13 @@ export async function runNext({ target, packageRoot, taskId, task, authorityCont
     }
     return {
       taskId: compactTaskId ?? result.taskId,
-      phase: result.currentPhase,
+      phase: explained.currentPhase,
       profile,
-      nextAction: result.nextAction,
-      command: result.commandSpecs?.[0]?.argv ?? [],
-      terminal: result.terminal,
-      errors: result.reasonCodes ?? result.reasons?.map((reason) => reason.code) ?? [],
+      nextAction: explained.nextAction,
+      command: explained.commandSpecs?.[0]?.argv ?? [],
+      terminal: explained.terminal,
+      errors: explained.reasonCodes ?? explained.reasons?.map((reason) => reason.code) ?? [],
+      ...(explained.explanation ? { explanation: explained.explanation } : {}),
     };
   });
 }
@@ -68,6 +71,15 @@ export function formatNextActionResult(result) {
     lines.push(...result.missingArtifacts.map((artifact) => `- ${artifact}`));
   }
   if (result.terminal) lines.push("STATE: TERMINAL");
+  if (result.explanation) {
+    lines.push("EXPLANATION (BOUNDED, READ-ONLY):");
+    lines.push(`- ${result.explanation.summary}`);
+    for (const item of result.explanation.reasons) {
+      lines.push(`- ${item.code}: ${item.requiredChange}`);
+      if (item.safeArtifacts.length > 0) lines.push(`  ARTIFACTS: ${item.safeArtifacts.join(", ")}`);
+    }
+    lines.push(`- ACTION KIND: ${result.explanation.actionKind}`);
+  }
   return `${lines.join("\n")}\n`;
 }
 

package/src/commands/task-create.js

@@ -9,6 +9,7 @@ import { withTaskTransaction } from "../core/transaction.js";
 import { taskDirectory } from "../core/task-paths.js";
 import { ensureWithin, fileExists } from "../core/filesystem.js";
 import { validateContract, writeContract } from "../core/contract.js";
+import { createPresetContract, CONTRACT_PRESET_IDS } from "../core/contract-presets.js";
 import { appendProtocolEvent } from "../core/events.js";
 import { E_TASK_REQUIRED, E_TASK_ALREADY_EXISTS, E_TASK_DESCRIPTOR_INVALID } from "../core/error-codes.js";
 import { recoveryGuidanceForClassification } from "../core/next-action-model.js";
@@ -56,12 +57,45 @@ export async function assertNoScopeConflictsWithInspection(claims, existingTasks
   }
 }
 
-export async function runTaskCreate({ target, packageRoot, taskId, claims = [], contractFile = null } = {}) {
+async function validateTaskCreateScope({ target, packageRoot, claims, taskId }) {
+  const allTasks = await discoverTasks(target, packageRoot);
+  await assertNoScopeConflictsWithInspection(claims, allTasks, taskId, { target, packageRoot });
+  if (claims.length > 0) await assertScopeClean(target, claims);
+}
+
+function previewResult({ taskId, normalizedClaims, preset, proposedContract }) {
+  return {
+    preview: true,
+    taskId,
+    writeClaims: normalizedClaims,
+    preset,
+    contract: proposedContract,
+    createsLifecycleState: false,
+  };
+}
+
+export async function runTaskCreate({
+  target,
+  packageRoot,
+  taskId,
+  claims = [],
+  contractFile = null,
+  preset = null,
+  preview = false,
+} = {}) {
   if (!taskId) {
     throw taskError(E_TASK_REQUIRED, "--task is required for task-create");
   }
   assertTaskId(taskId);
 
+  if (preset && !CONTRACT_PRESET_IDS.includes(preset)) {
+    const error = new Error(`Unknown contract preset: ${preset}. Expected one of ${CONTRACT_PRESET_IDS.join(", ")}`);
+    error.code = "E_CONTRACT_PRESET_UNKNOWN";
+    throw error;
+  }
+  if (preset && contractFile) {
+    throw taskError("E_CONTRACT_INPUT_CONFLICT", "Use either --preset or --contract-file, not both");
+  }
   const existing = await findTaskById(target, taskId, packageRoot);
   if (existing) {
     throw taskError(E_TASK_ALREADY_EXISTS, `Task already exists: ${taskId}`);
@@ -69,13 +103,45 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
 
   const normalizedClaims = normalizeWriteClaims(claims ?? []);
 
-  return withProjectClaimsLock(target, async () => {
-    const allTasks = await discoverTasks(target, packageRoot);
-    await assertNoScopeConflictsWithInspection(normalizedClaims, allTasks, taskId, { target, packageRoot });
-    if (normalizedClaims.length > 0) {
-      await assertScopeClean(target, normalizedClaims);
+  let proposedContract = null;
+  if (preset) proposedContract = createPresetContract({ taskId, preset, claims: normalizedClaims });
+  if (contractFile) {
+    const sourcePath = ensureWithin(target, contractFile);
+    if (!(await fileExists(sourcePath))) {
+      throw taskError("E_CONTRACT_MISSING", `Specified contract file not found: ${contractFile}`);
+    }
+    const raw = await readFile(sourcePath, "utf8");
+    try {
+      proposedContract = JSON.parse(raw);
+    } catch {
+      throw taskError("E_CONTRACT_INVALID", `Specified contract file is not valid JSON: ${contractFile}`);
     }
+    await validateContract(proposedContract, packageRoot);
+    if (proposedContract.taskId && proposedContract.taskId !== taskId) {
+      throw taskError(
+        E_TASK_DESCRIPTOR_INVALID,
+        `Contract taskId "${proposedContract.taskId}" does not match requested taskId "${taskId}"`,
+      );
+    }
+    proposedContract = { ...proposedContract, taskId };
+  }
+
+  if (proposedContract) await validateContract({ ...proposedContract, taskId }, packageRoot);
+
+  // Preview is advisory: it must never create the claims-lock directory, remove
+  // a stale lock, or fail because another process currently owns the lock.
+  if (preview) {
+    await validateTaskCreateScope({ target, packageRoot, claims: normalizedClaims, taskId });
+    return previewResult({ taskId, normalizedClaims, preset, proposedContract });
+  }
 
+  return withProjectClaimsLock(target, async () => {
+    // Re-check after acquiring the reservation. Preview results are not a
+    // reservation and the repository may have changed since they were built.
+    if (await findTaskById(target, taskId, packageRoot)) {
+      throw taskError(E_TASK_ALREADY_EXISTS, `Task already exists: ${taskId}`);
+    }
+    await validateTaskCreateScope({ target, packageRoot, claims: normalizedClaims, taskId });
     return withTaskTransaction({ target, taskId, operation: "task-create", packageRoot, recordCommitEvent: true }, async () => {
       const descriptor = createTaskDescriptor({
         taskId,
@@ -84,26 +150,9 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
       const written = await writeTaskDescriptor(target, descriptor, packageRoot);
 
       let contractCopied = false;
-      if (contractFile) {
-        const sourcePath = ensureWithin(target, contractFile);
-        if (!(await fileExists(sourcePath))) {
-          throw taskError("E_CONTRACT_MISSING", `Specified contract file not found: ${contractFile}`);
-        }
-        const raw = await readFile(sourcePath, "utf8");
-        let parsed;
-        try {
-          parsed = JSON.parse(raw);
-        } catch {
-          throw taskError("E_CONTRACT_INVALID", `Specified contract file is not valid JSON: ${contractFile}`);
-        }
+      if (proposedContract) {
+        const parsed = { ...proposedContract, taskId };
         await validateContract(parsed, packageRoot);
-        if (parsed.taskId && parsed.taskId !== taskId) {
-          throw taskError(
-            E_TASK_DESCRIPTOR_INVALID,
-            `Contract taskId "${parsed.taskId}" does not match requested taskId "${taskId}"`,
-          );
-        }
-        parsed.taskId = taskId;
         await writeContract(target, parsed, packageRoot, { taskId });
         contractCopied = true;
       }
@@ -128,6 +177,16 @@ export async function runTaskCreate({ target, packageRoot, taskId, claims = [],
 }
 
 export function formatTaskCreateResult(result) {
+  if (result.preview) {
+    return `${JSON.stringify({
+      preview: true,
+      taskId: result.taskId,
+      preset: result.preset,
+      writeClaims: result.writeClaims,
+      contract: result.contract,
+      createsLifecycleState: false,
+    }, null, 2)}\n`;
+  }
   const claims = result.writeClaims.length === 0 ? "none" : result.writeClaims.join(", ");
   return `created task: ${result.taskId}\nkey: ${result.taskKey}\ndirectory: ${result.directory}\nclaims: ${claims}\n`;
 }

package/src/commands/task-list.js

@@ -1,9 +1,23 @@
 import { discoverTasks } from "../core/task-discovery.js";
+import { WORK_PHASES } from "../core/protocol.js";
 
-export async function runTaskList({ target, packageRoot } = {}) {
+export async function runTaskList({ target, packageRoot, phase = null, active = false, limit = null, offset = 0 } = {}) {
   const tasks = await discoverTasks(target, packageRoot);
+  const normalizedPhase = typeof phase === "string" && phase.trim() !== "" ? phase.trim().toUpperCase() : null;
+  if (normalizedPhase && !WORK_PHASES.includes(normalizedPhase)) {
+    const error = new Error(`Unknown task phase filter: ${phase}`);
+    error.code = "E_TASK_PHASE_INVALID";
+    throw error;
+  }
+  const phaseFiltered = normalizedPhase ? tasks.filter((task) => task.phase === normalizedPhase) : tasks;
+  const filtered = active
+    ? phaseFiltered.filter((task) => task.claimState === "ACTIVE" && task.mutationAllowed === true)
+    : phaseFiltered;
+  const start = Number.isInteger(offset) && offset >= 0 ? offset : 0;
+  const end = Number.isInteger(limit) && limit >= 0 ? start + limit : undefined;
+  const projected = filtered.slice(start, end);
   return {
-    tasks: tasks.map((task) => {
+    tasks: projected.map((task) => {
       if (task.healthy === false) {
         return {
           taskId: task.taskId ?? null,
@@ -35,6 +49,12 @@ export async function runTaskList({ target, packageRoot } = {}) {
         updatedAt: task.updatedAt,
       };
     }),
+    ...(normalizedPhase ? { phase: normalizedPhase } : {}),
+    ...(active ? { active: true } : {}),
+    offset: start,
+    ...(Number.isInteger(limit) && limit >= 0 ? { limit } : {}),
+    total: filtered.length,
+    hasMore: end !== undefined ? end < filtered.length : false,
   };
 }
 

package/src/config/guides.json

@@ -42,5 +42,49 @@
   "flutter": {
     "path": "ENG/flutter-development-eng.md",
     "install": true
+  },
+  "dotnet": {
+    "path": "ENG/dotnet-aspnetcore-development-eng.md",
+    "install": true
+  },
+  "nodejs": {
+    "path": "ENG/nodejs-backend-development-eng.md",
+    "install": true
+  },
+  "rust": {
+    "path": "ENG/rust-development-eng.md",
+    "install": true
+  },
+  "c": {
+    "path": "ENG/c-development-eng.md",
+    "install": true
+  },
+  "cpp": {
+    "path": "ENG/cpp-development-eng.md",
+    "install": true
+  },
+  "java": {
+    "path": "ENG/java-development-eng.md",
+    "install": true
+  },
+  "sql": {
+    "path": "ENG/sql-development-eng.md",
+    "install": true
+  },
+  "go": {
+    "path": "ENG/go-development-eng.md",
+    "install": true
+  },
+  "typescript": {
+    "path": "ENG/typescript-development-eng.md",
+    "install": true
+  },
+  "php": {
+    "path": "ENG/php-development-eng.md",
+    "install": true
+  },
+  "swift": {
+    "path": "ENG/swift-development-eng.md",
+    "install": true
   }
 }