@devory/core 0.1.1 → 0.3.1

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@devory/core",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "description": "Shared types, parsing utilities, and path configuration for AI Dev Factory",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devoryai/devory"
+  },
   "main": "./dist/index.js",
   "types": "./src/index.ts",
   "exports": {
@@ -9,14 +13,20 @@
   },
   "files": [
     "dist/",
-    "src/",
+    "src/index.ts",
+    "src/defaults/",
     "README.md"
   ],
   "scripts": {
     "build": "esbuild src/index.ts --bundle --outfile=dist/index.js --platform=node --format=cjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "tsx --test src/parse.test.ts src/license.test.ts src/factory-environment.test.ts src/execution-policy.test.ts src/run-ledger.test.ts src/task-draft.test.ts src/task-markdown-renderer.test.ts src/task-validation.test.ts src/planning-draft.test.ts src/review-control.test.ts src/unattended-execution.test.ts src/unattended-checkpoint.test.ts src/unattended-stall-policy.test.ts src/routing-input.test.ts src/routing-evaluation.test.ts src/human-question.test.ts src/human-question-event.test.ts src/human-interruption-policy.test.ts src/slack-notification.test.ts"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
   },
   "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
     "esbuild": "^0.20.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3"

package/src/defaults/execution-policy.json

@@ -0,0 +1,72 @@
+{
+  "commands": {
+    "allow": [
+      "git status",
+      "git diff",
+      "git add",
+      "npm run test",
+      "npm run validate:task"
+    ],
+    "require_approval": [
+      "git push",
+      "git commit",
+      "npm install",
+      "pnpm install",
+      "yarn install"
+    ],
+    "forbid": [
+      "git reset --hard",
+      "rm -rf /",
+      "sudo"
+    ]
+  },
+  "filesystem": {
+    "writable_roots": [
+      ".",
+      "tasks",
+      "runs",
+      "artifacts"
+    ],
+    "read_only_roots": [
+      ".git"
+    ],
+    "require_approval_outside_writable_roots": true
+  },
+  "network": {
+    "allow": false,
+    "allowed_hosts": [],
+    "require_approval_for_hosts": [
+      "*"
+    ]
+  },
+  "package_installs": {
+    "allow": false,
+    "allowed_managers": [],
+    "require_approval": true
+  },
+  "test_execution": {
+    "allow": true,
+    "allowed_commands": [
+      "npm run test",
+      "npm run validate:task"
+    ],
+    "require_approval_commands": []
+  },
+  "approval_required_actions": [
+    "write_outside_workspace",
+    "network_access",
+    "package_install",
+    "destructive_git",
+    "secret_access"
+  ],
+  "forbidden_actions": [
+    "destructive_delete",
+    "privilege_escalation",
+    "force_push_without_request"
+  ],
+  "escalation": {
+    "unmatched_command": "require_approval",
+    "out_of_policy_action": "halt_and_escalate",
+    "invalid_policy": "fallback_to_defaults"
+  }
+}

package/src/defaults/human-interruption-policy.json

@@ -0,0 +1,19 @@
+{
+  "version": "human-interruption-policy-v1",
+  "default_interruption_level": "level_1",
+  "default_input_mode": "local-api",
+  "allowed_input_modes": ["local-api", "cli", "digest"],
+  "default_fallback_behavior": "continue-other-work",
+  "timeout_seconds": 1800,
+  "timeout_on_expiry": "assume-default",
+  "notification_mode": "digest",
+  "digest_cadence_minutes": 30,
+  "interruption_thresholds": {
+    "ambiguity": "level_1",
+    "confirmation": "level_1",
+    "approval": "level_2",
+    "destructive_change": "level_3",
+    "credentials": "level_3",
+    "external_side_effect": "level_2"
+  }
+}

package/src/defaults/unattended-stall-policy.json

@@ -0,0 +1,10 @@
+{
+  "version": "unattended-stall-policy-v1",
+  "heartbeat_stale_after_ms": 120000,
+  "heartbeat_missing_after_ms": 300000,
+  "progress_stalled_after_ms": 600000,
+  "waiting_progress_grace_ms": 1200000,
+  "looping_event_window": 6,
+  "looping_event_threshold": 4,
+  "repeated_failure_without_progress_threshold": 3
+}

package/src/index.ts

@@ -1,25 +1,23 @@
 /**
  * @devory/core — public API
  *
- * Shared types, parsing utilities, path configuration,
- * engineering standards, and license tier detection.
+ * Shared types, parsing utilities, and path configuration
+ * for the AI Dev Factory monorepo.
  */
 
 export { parseFrontmatter } from "./parse.ts";
-export type { TaskMeta, ParseResult } from "./parse.ts";
 export {
-  factoryPaths,
-  findFactoryContextDir,
-  resolveFactoryEnvironment,
-  resolveFactoryMode,
-  resolveFactoryRoot,
-} from "./factory-environment.ts";
-export type {
-  FactoryEnvironment,
-  FactoryMode,
-  FactoryPaths,
-  FactoryRootSource,
-} from "./factory-environment.ts";
+  clearLicenseCache,
+  clearLicenseToken,
+  detectTier,
+  getLicenseCacheFilePath,
+  getLicenseFilePath,
+  getLicenseStatus,
+  isFeatureEnabled,
+  tierGateMessage,
+  writeLicenseToken,
+} from "./license.ts";
+export type { Tier, ProFeature, LicenseInfo, LicenseStatus } from "./license.ts";
 export {
   loadStandards,
   loadBaseline,
@@ -39,9 +37,333 @@ export type {
   StandardsSourceType,
   LoadedStandards,
 } from "./standards.ts";
+export type { TaskMeta, ParseResult } from "./parse.ts";
 export {
-  detectTier,
-  isFeatureEnabled,
-  tierGateMessage,
-} from "./license.ts";
-export type { Tier, ProFeature, LicenseInfo } from "./license.ts";
+  factoryPaths,
+  findFactoryContextDir,
+  resolveFactoryEnvironment,
+  resolveFactoryMode,
+  resolveFactoryRoot,
+} from "./factory-environment.ts";
+export {
+  applyTaskRoutingOutcomeEvaluation,
+  normalizeRunRecord,
+  normalizeTaskRecord,
+  RESUMABLE_RUN_STATUSES,
+  RUN_LEDGER_VERSION,
+} from "./run-ledger.ts";
+export {
+  applyExecutionPolicyOverrides,
+  buildExecutionPolicyInjection,
+  EXECUTION_POLICY_FILENAME,
+  EXECUTION_POLICY_VERSION,
+  EXECUTION_POLICY_WORKSPACE_PATH,
+  loadDefaultExecutionPolicy,
+  loadWorkspaceExecutionPolicy,
+  normalizeExecutionPolicyOverrides,
+  resolveExecutionPolicy,
+  VALID_POLICY_ESCALATION_BEHAVIORS,
+} from "./execution-policy.ts";
+export {
+  buildMinimalTaskDraftFixture,
+  buildRichTaskDraftFixture,
+  buildTaskDraftRenderFixture,
+  normalizeTaskDraft,
+  renderTaskDraftMarkdown,
+  renderTaskDraftTarget,
+  TASK_DRAFT_BODY_SECTION_ORDER,
+  TASK_DRAFT_OPTIONAL_FRONTMATTER_FIELDS,
+  TASK_DRAFT_RENDER_CONTRACT_VERSION,
+  TASK_DRAFT_REQUIRED_FRONTMATTER_FIELDS,
+} from "./task-draft.ts";
+export {
+  buildTaskDraftTargetPath,
+  renderTaskDraftMarkdown as renderTaskMarkdown,
+  renderTaskDraftTarget as renderTaskMarkdownTarget,
+  TASK_MARKDOWN_FRONTMATTER_ORDER,
+  TASK_MARKDOWN_RENDERER_VERSION,
+  TASK_MARKDOWN_SECTION_ORDER,
+} from "./task-markdown-renderer.ts";
+export {
+  applyTaskDraftValidation,
+  REQUIRED_FIELDS,
+  toPlanningDraftValidationRecord,
+  validateTask,
+  validateTaskBody,
+  validateTaskDraft,
+  validateTaskMarkdown,
+} from "./task-validation.ts";
+export {
+  buildEpicPlanningDraft,
+  buildEpicPlanningDraftFixture,
+  buildPlanningDraftArtifactPath,
+  buildPlanningDraftStorageRelativePath,
+  buildTaskPlanningDraftFixture,
+  normalizePlanningDraft,
+  PLANNING_DRAFT_COMMIT_STATES,
+  PLANNING_DRAFT_CONTRACT_VERSION,
+  PLANNING_DRAFT_KINDS,
+  PLANNING_DRAFT_PERSISTENCE_MODES,
+  PLANNING_DRAFT_VALIDATION_STATUSES,
+  renderTaskPlanningDraftTarget,
+  serializePlanningDraft,
+  TASK_DRAFT_COMMIT_STAGES,
+  updateEpicPlanningDraft,
+} from "./planning-draft.ts";
+export {
+  normalizeUnattendedExecutionSnapshot,
+  ESCALATION_REASONS,
+  PROGRESS_EVENT_CATEGORIES,
+  UNATTENDED_EXECUTION_CONTRACT_VERSION,
+  UNATTENDED_RUN_STATUSES,
+  WORKER_HEALTH_STATUSES,
+} from "./unattended-execution.ts";
+export {
+  normalizeUnattendedCheckpointArtifact,
+  UNATTENDED_CHECKPOINT_TRIGGERS,
+  UNATTENDED_CHECKPOINT_VERSION,
+} from "./unattended-checkpoint.ts";
+export {
+  buildRunAttentionQueueItem,
+  buildTaskReviewQueueItem,
+  buildTaskTriageQueueItem,
+  getSupportedReviewActions,
+  normalizeReviewQueueItem,
+  REVIEW_CONTROL_ACTIONS,
+  REVIEW_CONTROL_CONTRACT_VERSION,
+  REVIEW_CONTROL_MECHANISMS,
+  REVIEW_QUEUE_ITEM_KINDS,
+  REVIEW_QUEUE_RUN_STATUSES,
+  REVIEW_QUEUE_TASK_STAGES,
+  REVIEW_QUEUE_TRIAGE_STAGES,
+  TASK_REVIEW_ACTIONS,
+  TASK_REVIEW_ACTION_STAGE_MAP,
+} from "./review-control.ts";
+export {
+  applyUnattendedStallPolicyOverrides,
+  loadDefaultUnattendedStallPolicy,
+  loadWorkspaceUnattendedStallPolicy,
+  normalizeUnattendedStallPolicyOverrides,
+  resolveUnattendedStallPolicy,
+  UNATTENDED_STALL_POLICY_FILENAME,
+  UNATTENDED_STALL_POLICY_VERSION,
+  UNATTENDED_STALL_POLICY_WORKSPACE_PATH,
+} from "./unattended-stall-policy.ts";
+export {
+  normalizeRoutingInput,
+  VALID_ROUTING_CONTEXT_INTENSITIES,
+  VALID_ROUTING_EXECUTION_PROFILES,
+  VALID_ROUTING_PRIORITY_LEVELS,
+} from "./routing-input.ts";
+export {
+  attachRoutingDecisionLinkage,
+  buildRoutingDecisionId,
+  ROUTING_DECISION_VERSION,
+} from "./routing-decision.ts";
+export { buildRoutingOutcomeEvaluation } from "./routing-evaluation.ts";
+export {
+  buildHumanQuestionFixture,
+  HUMAN_INTERRUPTION_POLICY_MAP,
+  HUMAN_QUESTION_VERSION,
+} from "./human-question.ts";
+export {
+  buildHumanQuestionArtifactRelativePath,
+  extractHumanQuestionArtifactMetadata,
+  HUMAN_QUESTION_ARTIFACT_DIR,
+  HUMAN_QUESTION_ARTIFACT_TYPE,
+  parseHumanQuestionArtifact,
+  serializeHumanQuestionArtifact,
+} from "./human-question-artifact.ts";
+export {
+  buildHumanQuestionDigest,
+  buildHumanQuestionDigestRelativePath,
+  buildHumanQuestionLifecycleEvent,
+  buildHumanQuestionLifecycleEventRelativePath,
+  HUMAN_QUESTION_DIGEST_ARTIFACT_DIR,
+  HUMAN_QUESTION_DIGEST_VERSION,
+  HUMAN_QUESTION_EVENT_ARTIFACT_DIR,
+  HUMAN_QUESTION_EVENT_VERSION,
+  parseHumanQuestionLifecycleEvent,
+  renderHumanQuestionDigestMarkdown,
+  serializeHumanQuestionDigest,
+  serializeHumanQuestionLifecycleEvent,
+} from "./human-question-event.ts";
+export {
+  applyHumanInterruptionPolicyOverrides,
+  getTaskHumanInterruptionPolicyOverrides,
+  HUMAN_INTERRUPTION_POLICY_FILENAME,
+  HUMAN_INTERRUPTION_POLICY_VERSION,
+  HUMAN_INTERRUPTION_POLICY_WORKSPACE_PATH,
+  loadDefaultHumanInterruptionPolicy,
+  loadWorkspaceHumanInterruptionPolicy,
+  normalizeHumanInterruptionPolicyOverrides,
+  resolveHumanInterruptionPolicy,
+  VALID_HUMAN_NOTIFICATION_MODES,
+  VALID_HUMAN_POLICY_THRESHOLD_KEYS,
+} from "./human-interruption-policy.ts";
+export {
+  normalizeSlackNotificationConfig,
+  SLACK_NOTIFICATION_CONFIG_VERSION,
+  VALID_SLACK_DELIVERY_MODES,
+  VALID_SLACK_DIGEST_GROUP_BY,
+  VALID_SLACK_TRANSPORT_KINDS,
+} from "./slack-notification.ts";
+export type {
+  FactoryEnvironment,
+  FactoryMode,
+  FactoryPaths,
+  FactoryRootSource,
+} from "./factory-environment.ts";
+export type {
+  CostEventRecord,
+  FailureRecord,
+  OutcomeEvidence,
+  ProgressEventRecord,
+  RunInterruptionState,
+  RoutingEvidenceRecord,
+  RoutingFallbackEvidence,
+  RoutingInputSnapshot,
+  RoutingLedger,
+  RoutingRetryEvidence,
+  RoutingSelectionEvidence,
+  RoutingTimingEvidence,
+  RoutingUsageEvidence,
+  RunLedgerSummary,
+  RunRecord,
+  TaskBlockKind,
+  TaskBlockState,
+  TaskRecord,
+} from "./run-ledger.ts";
+export type {
+  ExecutionCommandPolicy,
+  ExecutionFilesystemPolicy,
+  ExecutionNetworkPolicy,
+  ExecutionPackageInstallPolicy,
+  ExecutionPolicyEscalation,
+  ExecutionPolicyManifest,
+  ExecutionPolicyManifestOverrides,
+  ExecutionPolicyResolution,
+  ExecutionTestPolicy,
+  PolicyEscalationBehavior,
+} from "./execution-policy.ts";
+export type {
+  TaskDraft,
+} from "./task-draft.ts";
+export type {
+  TaskDraftValidationResult,
+  ValidationResult,
+} from "./task-validation.ts";
+export type {
+  CreateEpicPlanningDraftInput,
+  EpicPlanningDraft,
+  PlanningDraft,
+  PlanningDraftBase,
+  PlanningDraftCommitRecord,
+  PlanningDraftCommitState,
+  PlanningDraftKind,
+  PlanningDraftPersistenceMode,
+  PlanningDraftStorageRecord,
+  PlanningDraftValidationRecord,
+  PlanningDraftValidationStatus,
+  RenderedTaskDraftTarget,
+  TaskDraftCommitStage,
+  TaskPlanningDraft,
+  UpdateEpicPlanningDraftInput,
+} from "./planning-draft.ts";
+export type {
+  ReviewControlAction,
+  ReviewControlMechanism,
+  ReviewQueueBaseItem,
+  ReviewQueueItem,
+  ReviewQueueItemKind,
+  ReviewQueueRunSource,
+  ReviewQueueTaskSource,
+  RunAttentionQueueItem,
+  TaskReviewAction,
+  TaskReviewQueueItem,
+  TaskTriageQueueItem,
+} from "./review-control.ts";
+export type {
+  UnattendedCheckpointArtifact,
+  UnattendedCheckpointArtifactReferences,
+  UnattendedCheckpointPolicySnapshot,
+  UnattendedCheckpointTrigger,
+} from "./unattended-checkpoint.ts";
+export type {
+  CheckpointReferenceRecord,
+  EscalationReason,
+  EscalationRecord,
+  ProgressEventCategory,
+  ProgressPointerRecord,
+  RecoveryAttemptRecord,
+  UnattendedExecutionSnapshot,
+  UnattendedRunStatus,
+  WorkerHeartbeatRecord,
+  WorkerHealthStatus,
+} from "./unattended-execution.ts";
+export type {
+  UnattendedStallPolicy,
+  UnattendedStallPolicyOverrides,
+  UnattendedStallPolicyResolution,
+} from "./unattended-stall-policy.ts";
+export type {
+  RoutingDecisionFallbackPath,
+  RoutingDecisionLinkage,
+  RoutingDecisionRejectedCandidate,
+  RoutingDecisionStatus,
+  UnifiedRoutingDecision,
+} from "./routing-decision.ts";
+export type {
+  BuildRoutingOutcomeEvaluationInput,
+  RoutingEvaluationStatus,
+  RoutingEvidenceStatus,
+  RoutingManualIntervention,
+  RoutingOutcomeEvaluation,
+  RoutingReviewOutcome,
+  RoutingValidationOutcome,
+} from "./routing-evaluation.ts";
+export type {
+  HumanInterruptionLevel,
+  HumanQuestionAnswerPayload,
+  HumanQuestionAuditEvent,
+  HumanQuestionFallbackBehavior,
+  HumanQuestionInputMode,
+  HumanQuestionOption,
+  HumanQuestionRecord,
+  HumanQuestionStatus,
+  HumanQuestionTimeoutPolicy,
+  InterruptionPolicyMapping,
+} from "./human-question.ts";
+export type { HumanQuestionArtifactMetadata } from "./human-question-artifact.ts";
+export type {
+  HumanQuestionDigestArtifact,
+  HumanQuestionDigestEntry,
+  HumanQuestionLifecycleEvent,
+  HumanQuestionLifecycleEventType,
+} from "./human-question-event.ts";
+export type {
+  HumanInterruptionPolicy,
+  HumanInterruptionPolicyOverrides,
+  HumanInterruptionPolicyResolution,
+  HumanNotificationMode,
+  HumanPolicyThresholdKey,
+} from "./human-interruption-policy.ts";
+export type {
+  SlackDeliveryMode,
+  SlackDeliveryRecordLink,
+  SlackDeliveryRequest,
+  SlackDigestConfig,
+  SlackDigestGroupBy,
+  SlackDmRoutingConfig,
+  SlackNotificationConfig,
+  SlackSeverityRoutingConfig,
+  SlackTransportConfig,
+  SlackTransportKind,
+} from "./slack-notification.ts";
+export type {
+  NormalizedRoutingInput,
+  RoutingContextIntensity,
+  RoutingExecutionProfile,
+  RoutingPriorityLevel,
+  RoutingRuntimeContext,
+} from "./routing-input.ts";

package/src/factory-environment.test.ts

@@ -1,99 +0,0 @@
-import { afterEach, beforeEach, describe, test } from "node:test";
-import assert from "node:assert/strict";
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-
-import {
-  factoryPaths,
-  findFactoryContextDir,
-  resolveFactoryEnvironment,
-  resolveFactoryMode,
-  resolveFactoryRoot,
-} from "./factory-environment.ts";
-
-let tmpDir: string;
-
-beforeEach(() => {
-  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "factory-env-test-"));
-  delete process.env.DEVORY_FACTORY_ROOT;
-  delete process.env.FACTORY_ROOT;
-  delete process.env.DEVORY_FACTORY_MODE;
-  delete process.env.FACTORY_MODE;
-  delete process.env.DEVORY_REMOTE_FACTORY_URL;
-  delete process.env.FACTORY_REMOTE_URL;
-});
-
-afterEach(() => {
-  fs.rmSync(tmpDir, { recursive: true, force: true });
-  delete process.env.DEVORY_FACTORY_ROOT;
-  delete process.env.FACTORY_ROOT;
-  delete process.env.DEVORY_FACTORY_MODE;
-  delete process.env.FACTORY_MODE;
-  delete process.env.DEVORY_REMOTE_FACTORY_URL;
-  delete process.env.FACTORY_REMOTE_URL;
-});
-
-describe("findFactoryContextDir", () => {
-  test("returns the containing directory when marker exists", () => {
-    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
-    assert.equal(findFactoryContextDir(tmpDir), tmpDir);
-  });
-
-  test("walks up parent directories to find the factory marker", () => {
-    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
-    const nested = path.join(tmpDir, "nested", "deep");
-    fs.mkdirSync(nested, { recursive: true });
-    assert.equal(findFactoryContextDir(nested), tmpDir);
-  });
-});
-
-describe("resolveFactoryRoot", () => {
-  test("uses DEVORY_FACTORY_ROOT first", () => {
-    process.env.DEVORY_FACTORY_ROOT = "/explicit/path";
-    process.env.FACTORY_ROOT = "/legacy/path";
-    assert.deepEqual(resolveFactoryRoot(tmpDir), {
-      root: "/explicit/path",
-      source: "env:DEVORY_FACTORY_ROOT",
-    });
-  });
-
-  test("walks to the factory marker when env vars are absent", () => {
-    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
-    const nested = path.join(tmpDir, "deep");
-    fs.mkdirSync(nested);
-    assert.deepEqual(resolveFactoryRoot(nested), {
-      root: tmpDir,
-      source: "git-walk",
-    });
-  });
-});
-
-describe("resolveFactoryMode", () => {
-  test("defaults to local", () => {
-    assert.equal(resolveFactoryMode(), "local");
-  });
-
-  test("honors explicit hosted mode", () => {
-    process.env.DEVORY_FACTORY_MODE = "hosted";
-    assert.equal(resolveFactoryMode(), "hosted");
-  });
-
-  test("treats remote url configuration as hosted mode", () => {
-    process.env.DEVORY_REMOTE_FACTORY_URL = "https://factory.example.com";
-    assert.equal(resolveFactoryMode(), "hosted");
-  });
-});
-
-describe("resolveFactoryEnvironment", () => {
-  test("returns root, mode, and derived paths together", () => {
-    fs.writeFileSync(path.join(tmpDir, "FACTORY_CONTEXT.md"), "# context");
-    process.env.DEVORY_FACTORY_MODE = "hosted";
-
-    const result = resolveFactoryEnvironment(tmpDir);
-    assert.equal(result.root, tmpDir);
-    assert.equal(result.source, "git-walk");
-    assert.equal(result.mode, "hosted");
-    assert.deepEqual(result.paths, factoryPaths(tmpDir));
-  });
-});