@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/api-contracts/work-plan-prd.js

@@ -0,0 +1,494 @@
+'use strict';
+
+const AUDITED_NEGATIVE_TESTS = Object.freeze([{
+  strategy: 'isolated-http-invalid-input-state-snapshot',
+  expectedStatus: '400-or-409',
+  audit: 'audited',
+}]);
+
+module.exports = {
+  owner: 'work-plan-prd',
+  routes: [
+    'GET /api/work-items',
+    'GET /api/prd',
+    'GET /api/archived-prds',
+    'GET /api/verify-guides',
+    'POST /api/work-items',
+    'POST /api/work-items/update',
+    'POST /api/work-items/retry',
+    'POST /api/work-items/delete',
+    'POST /api/work-items/cancel',
+    'POST /api/work-items/archive',
+    'GET /api/work-items/archive',
+    'POST /api/work-items/reopen',
+    'POST /api/work-items/feedback',
+    'GET /api/work-items/<id>',
+    'POST /api/plan',
+    'GET /api/plans',
+    'POST /api/plans/trigger-verify',
+    'POST /api/plans/approve',
+    'POST /api/plans/pause',
+    'POST /api/plans/execute',
+    'POST /api/plans/reject',
+    'POST /api/plans/regenerate',
+    'POST /api/plans/delete',
+    'POST /api/plans/archive',
+    'POST /api/plans/unarchive',
+    'POST /api/plans/revise',
+    'POST /api/plans/discuss',
+    'GET /api/plans/archive/<file>',
+    'GET /api/plans/<file>',
+    'POST /api/prd-items',
+    'POST /api/prd-items/update',
+    'POST /api/prd-items/remove',
+    'POST /api/plans/create',
+  ],
+  overrides: {
+    // Read-side list endpoints that actively reject any query string via
+    // planPrdValidation.validateNoQuery — declared explicitly so they stay
+    // certified as audited rather than defaulting to pending-audit.
+    'GET /api/prd': {
+      query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
+    },
+    'GET /api/archived-prds': {
+      query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
+    },
+    'GET /api/verify-guides': {
+      query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
+    },
+    'GET /api/plans': {
+      query: { policy: 'none', rationale: 'Handler rejects any query string (planPrdValidation.validateNoQuery).' },
+    },
+    'POST /api/work-items': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'title', type: 'string', required: true },
+          { name: 'type', type: 'string', required: false, allowedValuesSource: 'shared.WORK_TYPE' },
+          { name: 'description', type: 'string', required: false },
+          { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'agent', type: 'string', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'agents', type: 'string|array<string>', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'scope', type: 'string', required: false, allowedValues: ['fan-out'] },
+          { name: 'references', type: 'array<object>', required: false },
+          { name: 'acceptanceCriteria', type: 'array|string', required: false },
+          { name: 'depends_on', type: 'array<string>', required: false },
+          { name: 'skipPr', type: 'boolean', required: false },
+          { name: 'oneShot', type: 'boolean', required: false },
+          { name: 'agentLock', type: 'boolean', required: false },
+          { name: 'hardAgent', type: 'boolean', required: false },
+          { name: 'meta', type: 'object', required: false },
+          { name: 'meta.pr_followup', type: 'object', required: false },
+          { name: 'meta.workdir', type: 'string', required: false },
+          { name: 'planFile', type: 'string', required: false },
+          { name: 'branch', type: 'string', required: false },
+          { name: 'branchStrategy', type: 'string', required: false },
+          { name: 'featureBranch', type: 'string', required: false },
+          { name: 'targetPr', type: 'string|integer', required: false },
+          { name: 'pr_id', type: 'string|integer', required: false },
+          { name: 'prUrl', type: 'string|integer', required: false },
+          { name: 'prNumber', type: 'integer|string', required: false },
+        ],
+      },
+      headers: {
+        policy: 'optional',
+        fields: [
+          { name: 'X-Minions-Agent', type: 'string', required: false },
+          { name: 'X-Minions-Origin-Wi', type: 'string', required: false },
+        ],
+      },
+      aliases: [
+        { name: 'agents', canonical: 'agent routing hints', location: 'body', type: 'string|array' },
+        { name: 'acceptanceCriteria', canonical: 'acceptanceCriteria[]', location: 'body', type: 'string|array' },
+        { name: 'hardAgent', canonical: 'agentLock', location: 'body', type: 'boolean' },
+      ],
+      constraints: [
+        { rule: 'worktree-requiring types require a configured project unless exactly one project exists' },
+        { rule: 'plan-to-prd requires planFile' },
+        { rule: 'follow-up dedup rejects before PR auto-enrollment' },
+        { rule: 'all validation completes before PR stamping, enrollment, branch derivation, dedup, SQL mutation, or cache invalidation' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/update': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'title', type: 'string', required: false },
+          { name: 'description', type: 'string', required: false },
+          { name: 'type', type: 'string', required: false, allowedValuesSource: 'shared.WORK_TYPE' },
+          { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'agent', type: 'string|null', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'project', type: 'string|null', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'references', type: 'array<object>', required: false },
+          { name: 'acceptanceCriteria', type: 'array|string', required: false },
+          { name: 'depends_on', type: 'array<string>', required: false },
+          { name: 'workdir', type: 'string|null', required: false },
+          { name: 'meta', type: 'object', required: false },
+        ],
+      },
+      aliases: [
+        { name: 'acceptanceCriteria', canonical: 'acceptanceCriteria[]', location: 'body', type: 'string|array' },
+        { name: 'workdir', canonical: 'meta.workdir', location: 'body', type: 'string|null' },
+      ],
+      constraints: [
+        { rule: 'only pending or failed work items are editable' },
+        { rule: 'every supplied update field is validated before SQL mutation' },
+        { rule: 'cross-scope moves and field updates commit in one SQL transaction' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/retry': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'prdFile', type: 'basename', required: false },
+          { name: 'force', type: 'boolean', required: false },
+        ],
+      },
+      constraints: [
+        { rule: 'only failed or dispatched items retry; force:true additionally permits completed items' },
+        { rule: 'source is required when the id exists in multiple scopes' },
+        { rule: 'PRD rematerialization applies the same project requirement as create' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/delete': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+        ],
+      },
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/cancel': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'reason', type: 'string', required: false },
+        ],
+      },
+      constraints: [
+        { rule: 'completed and already-cancelled items cannot be cancelled' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/archive': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+        ],
+      },
+      constraints: [
+        { rule: 'only completed or failed items can be archived' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/reopen': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'description', type: 'string', required: false },
+        ],
+      },
+      aliases: [
+        { name: 'source', canonical: 'project', location: 'body', type: 'string' },
+      ],
+      constraints: [
+        { rule: 'project and source must match when both are supplied' },
+        { rule: 'only done or failed items can be reopened' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'POST /api/work-items/feedback': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'id', type: 'identifier', required: true },
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+          { name: 'rating', type: 'string', required: true, allowedValues: ['up', 'down'] },
+          { name: 'comment', type: 'string', required: false },
+        ],
+      },
+      constraints: [
+        { rule: 'feedback is accepted only for completed items' },
+        { rule: 'source is required when the id exists in multiple scopes' },
+      ],
+      negativeTests: AUDITED_NEGATIVE_TESTS,
+    },
+    'GET /api/work-items/<id>': {
+      audit: 'audited',
+      query: {
+        policy: 'optional',
+        fields: [
+          { name: 'source', type: 'string', required: false, allowedValuesSource: 'central + config.projects[].name' },
+        ],
+      },
+    },
+    'GET /api/work-items': {
+      // Polled list endpoint: reads no query/body — returns the full slimmed
+      // work-item collection. Affirmed input-less so it is audited rather than
+      // defaulting to pending-audit by omission (review PR #966).
+      noInput: true,
+    },
+    'GET /api/work-items/archive': {
+      // Archived-item listing: reads no query/body. Affirmed input-less.
+      noInput: true,
+    },
+    'POST /api/plan': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'title', type: 'string', required: true },
+          { name: 'description', type: 'string', required: false },
+          { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'project', type: 'string|array', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'agent', type: 'string', required: false, allowedValuesSource: 'config.agents keys' },
+          { name: 'branchStrategy', type: 'string', required: false, allowedValues: ['parallel', 'shared-branch'] },
+        ],
+      },
+      aliases: [
+        { name: 'branch_strategy', canonical: 'branchStrategy', location: 'body' },
+      ],
+      constraints: [
+        'project arrays contain only configured project strings and are canonicalized through shared.resolveProjectSource',
+        'branch_strategy and branchStrategy must match when both are supplied',
+      ],
+    },
+    'POST /api/plans/trigger-verify': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .json basename' }],
+      },
+      constraints: ['PRD must exist, be live, and have shared.PLAN_STATUS.COMPLETED'],
+    },
+    'POST /api/plans/approve': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'file', type: 'string', required: true, pattern: 'safe .json basename' },
+          { name: 'approvedBy', type: 'string', required: false },
+          { name: 'forceRegen', type: 'boolean', required: false },
+          { name: 'skipRegen', type: 'boolean', required: false },
+        ],
+      },
+      constraints: [
+        'forceRegen and skipRegen are mutually exclusive',
+        'revision-requested, rejected, and archived PRDs cannot be approved',
+      ],
+    },
+    'POST /api/plans/pause': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .json basename' }],
+      },
+      constraints: ['PRD status must be active or approved'],
+    },
+    'POST /api/plans/execute': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'file', type: 'string', required: true, pattern: 'safe .md basename' },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'feedback', type: 'string', required: false },
+        ],
+      },
+      constraints: [
+        'plan must be live, not archived',
+        'Project/Projects/targetProjects declarations must be valid and mutually consistent',
+      ],
+    },
+    'POST /api/plans/reject': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'file', type: 'string', required: true, pattern: 'safe .json basename' },
+          { name: 'rejectedBy', type: 'string', required: false },
+          { name: 'reason', type: 'string', required: false },
+        ],
+      },
+      constraints: ['completed, rejected, and archived PRDs cannot be rejected'],
+    },
+    'POST /api/plans/regenerate': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'source', type: 'string', required: true, pattern: 'safe .json basename' }],
+      },
+      constraints: ['source PRD must be live and in a resumable lifecycle state'],
+    },
+    'POST /api/plans/delete': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .md or .json basename' }],
+      },
+      constraints: ['explicit delete is the only operation that may permanently remove an archived PRD'],
+    },
+    'POST /api/plans/archive': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .md or .json basename' }],
+      },
+      constraints: [
+        'artifact must be live and not already archived',
+        'SQL PRD changes are compensated if the linked Markdown move fails',
+      ],
+    },
+    'POST /api/plans/unarchive': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .md or .json basename' }],
+      },
+      constraints: [
+        'artifact must be archived',
+        'PRD state is compensated if the linked Markdown restore fails',
+      ],
+    },
+    'POST /api/plans/revise': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'file', type: 'string', required: true, pattern: 'safe .json basename' },
+          { name: 'feedback', type: 'string', required: true },
+          { name: 'requestedBy', type: 'string', required: false },
+        ],
+      },
+      constraints: ['feedback must contain non-whitespace text and PRD status must allow revision'],
+    },
+    'POST /api/plans/discuss': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .json basename' }],
+      },
+      constraints: ['PRD status must be awaiting-approval or revision-requested'],
+    },
+    'GET /api/plans/archive/<file>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .md or .json basename' }],
+      },
+      negativeTests: [{
+        strategy: 'reject-traversal-encoded-traversal-and-wrong-extension',
+        expectedStatus: '400',
+        audit: 'audited',
+      }],
+    },
+    'GET /api/plans/<file>': {
+      audit: 'audited',
+      path: {
+        policy: 'required',
+        fields: [{ name: 'file', type: 'string', required: true, pattern: 'safe .md or .json basename' }],
+      },
+      negativeTests: [{
+        strategy: 'reject-traversal-encoded-traversal-and-wrong-extension',
+        expectedStatus: '400',
+        audit: 'audited',
+      }],
+    },
+    'POST /api/prd-items': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'source', type: 'string', required: false, pattern: 'safe .json basename' },
+          { name: 'id', type: 'string', required: false, pattern: 'safe item identifier' },
+          { name: 'name', type: 'string', required: true },
+          { name: 'description', type: 'string', required: false },
+          { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'estimated_complexity', type: 'string', required: false, allowedValues: ['small', 'medium', 'large'] },
+          { name: 'type', type: 'string', required: false, allowedValuesSource: 'shared.VALID_WORK_TYPES' },
+          { name: 'status', type: 'string', required: false, allowedValuesSource: 'shared.PRD_ITEM_STATUS' },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'itemProject', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+        ],
+      },
+      aliases: [
+        { name: 'item_project', canonical: 'itemProject', location: 'body' },
+        { name: 'workType', canonical: 'type', location: 'body' },
+        { name: 'work_type', canonical: 'type', location: 'body' },
+      ],
+    },
+    'POST /api/prd-items/update': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'source', type: 'string', required: true, pattern: 'safe .json basename' },
+          { name: 'itemId', type: 'string', required: true, pattern: 'safe item identifier' },
+          { name: 'name', type: 'string', required: false },
+          { name: 'description', type: 'string', required: false },
+          { name: 'priority', type: 'string', required: false, allowedValuesSource: 'shared.WORK_ITEM_PRIORITY_VALUES' },
+          { name: 'estimated_complexity', type: 'string', required: false, allowedValues: ['small', 'medium', 'large'] },
+          { name: 'type', type: 'string', required: false, allowedValuesSource: 'shared.VALID_WORK_TYPES' },
+          { name: 'status', type: 'string', required: false, allowedValuesSource: 'shared.PRD_ITEM_STATUS' },
+          { name: 'project', type: 'string', required: false, allowedValuesSource: 'config.projects[].name' },
+        ],
+      },
+      aliases: [
+        { name: 'workType', canonical: 'type', location: 'body' },
+        { name: 'work_type', canonical: 'type', location: 'body' },
+      ],
+      constraints: ['archived and rejected PRDs cannot be edited'],
+    },
+    'POST /api/prd-items/remove': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'source', type: 'string', required: true, pattern: 'safe .json basename' },
+          { name: 'itemId', type: 'string', required: true, pattern: 'safe item identifier' },
+        ],
+      },
+      constraints: ['archived and rejected PRDs cannot have items removed'],
+    },
+    'POST /api/plans/create': {
+      audit: 'audited',
+      body: {
+        policy: 'required',
+        fields: [
+          { name: 'title', type: 'string', required: true },
+          { name: 'content', type: 'string', required: true },
+          { name: 'project', type: 'string|array', required: false, allowedValuesSource: 'config.projects[].name' },
+          { name: 'meetingId', type: 'string', required: false, pattern: 'safe identifier' },
+        ],
+      },
+      constraints: [
+        'embedded Project/Projects/targetProjects declarations must be valid and agree with project',
+      ],
+    },
+  },
+};