@mytegroupinc/myte-core 0.0.52 → 0.0.54

package/README.md

@@ -44,7 +44,7 @@ This package exists so the public wrapper can stay small and versioned cleanly.
   `MyteCommandCenter/feedback-sync/comment-attachments`; binary formats remain
   visible as metadata-only context. Raw S3/object-storage URLs are not written
   into local sync artifacts.
-- `feedback status|edit|assign|archive|refine` writes reviewable local YAML artifacts.
+- `feedback status|edit|document-add|assign|archive|refine` writes reviewable local YAML artifacts.
 - `feedback submit|revise|comment` are live writes that require `--confirm-write --approval-artifact <path>`.
 - `feedback review|move|undo|apply` are governed writes with backend permission checks but no approval artifact flags.
 - `feedback-sync|get|history|reviews|prd-versions|prd-diff|validate` are read/sync/validation commands with no approval artifact flags.
@@ -90,6 +90,8 @@ Only selected project-key writes require a server-validated approval envelope. T
   with ordered PRD documents. List every file/title/client ref and the matching
   count in the approval artifact.
 - Feedback submit/revise/comment artifacts are usually the same YAML or markdown file being submitted. For inline text or stdin, use a separate approval memo with the feedback id or request id and exact content.
+- `feedback document-add --feedback-id <id> --prd-file ./document.md` creates a governed proposal to append one linked PRD document to the existing Feedback context. The addition is not live until the normal `feedback submit` -> owner/delegate `feedback review` flow applies it.
+- Governed document additions preserve existing document IDs, append a new stable document, create a new immutable PRD version, and emit `feedback_prd_document_added` so the Feedback context bubble/notification feed can link users back to the updated PRD context. Existing PRD sets may grow to twelve documents; new `create-prd --document-set` uploads remain capped at three.
 - Team, owner, and client update artifacts should name the audience and include the exact message body or a complete summary. Client updates should include target contact ids when used.
 - `feedback review --request-ids`, `feedback move --feedback-ids`, `mission status --mission-ids`, `mission archive --mission-ids`, and `run-qaqc --mission-ids` are batched governed writes, but they are marked `Not required` and should not receive approval artifact flags.
 - The package does not bundle the large MyteCody engine binary or the async
@@ -106,6 +108,7 @@ Coding agents should treat `MYTE_API_KEY` as a project-scoped Project Assistant
 - Use `suggestions sync` only when you need to refresh mission review-thread state without refreshing the full board.
 - Use `query --with-diff` for project-scoped code review, planning, and implementation questions.
 - Use `create-prd` only with reviewed markdown files and `--confirm-write --approval-artifact <path>`. The markdown file body is the PRD document; `description` is only the short board/card summary.
+- New PRDs are unassigned by default. Add `--assigned-user-id <id>` or `--assigned-user-email <exact-email>` to validate and assign an eligible project user in the same create request.
 - Use `create-prd --document-set` only when the explicit intent is one parent
   Feedback with one to three ordered documents; omitting it preserves
   independent multi-file creation.
@@ -248,7 +251,8 @@ Agent rule: never guess `suggestion_id`. If `mission-ops.yml` is missing or stal
 | `feedback-sync` | Pulls non-archived feedback metadata, comments, and PRD context into `MyteCommandCenter`. | Read-only project-key API call; archived Feedback is intentionally excluded. |
 | `feedback get` | Reads one feedback item's current server snapshot and `snapshot_hash`. | Read-only; backend checks project access. |
 | `feedback status` | Creates a local YAML proposal to change canonical lifecycle state. | No live mutation until `submit` and owner/delegate review, except owner-direct `apply`. |
-| `feedback edit` / `feedback refine` | Creates a local YAML proposal for title, description/body, priority, due date, tags, or notes. | Content changes go through owner-review membrane. |
+| `feedback edit` / `feedback refine` | Creates a local YAML proposal for title, description/body, priority, due date, tags, or notes. | Content changes go through owner-review membrane. |
+| `feedback document-add` | Creates a local YAML proposal to append one linked Markdown PRD document to an existing Feedback item. | Owner-only field; normal submit/review/apply flow, stale protection, idempotency, version history, and notification apply. |
 | `feedback assign` | Creates a local YAML proposal to change assignee. | Goes through review unless applied through owner-direct path. |
 | `feedback archive` | Creates a local YAML proposal to archive. | Archive is governed by backend owner/delegate capability. |
 | `feedback submit` | Sends a local proposal artifact to the backend as a review request. | Requires `--confirm-write --approval-artifact <path>`; does not mutate live feedback before approval. |

package/cli.js

@@ -220,6 +220,7 @@ function printHelp() {
     "  myte feedback history --feedback-id <id> [--limit 50] [--json]",
     "  myte feedback status --feedback-id <id> --status frozen|todo|in_progress|in_review|completed|deployed|rejected|archived --reason \"...\"",
     "  myte feedback edit --feedback-id <id> [--title \"...\"] [--feedback-text \"...\"] [--prd-file ./document.md] [--document-id <id>] [--priority High] [--reason \"...\"]",
+    "  myte feedback document-add --feedback-id <id> --prd-file ./document.md [--title \"...\"] [--filename name.md] [--client-ref ref] [--reason \"...\"]",
     "  myte feedback assign --feedback-id <id> --user-id <id> [--reason \"...\"]",
     "  myte feedback archive --feedback-id <id> --reason \"...\"",
     "  myte feedback submit --file ./MyteCommandCenter/reviews/feedback/<id>-edit.yml --confirm-write --approval-artifact <path> [--json]",
@@ -235,8 +236,8 @@ function printHelp() {
     "  myte feedback prd-diff --feedback-id <id> --version-id <id> [--compare-to <id>] [--document-id <id>] [--json]",
     "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
     "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/<id>-status.yml [--json]",
-    "  myte create-prd <file.md> [more.md ...] [--document-set] --confirm-write --approval-artifact <path> [--json] [--title \"...\"] [--description \"...\"]",
-    "  cat file.md | myte create-prd --stdin --confirm-write --approval-artifact <path> [--title \"...\"] [--description \"...\"]",
+    "  myte create-prd <file.md> [more.md ...] [--document-set] [--assigned-user-id <id> | --assigned-user-email <email>] --confirm-write --approval-artifact <path> [--json] [--title \"...\"] [--description \"...\"]",
+    "  cat file.md | myte create-prd --stdin [--assigned-user-id <id> | --assigned-user-email <email>] --confirm-write --approval-artifact <path> [--title \"...\"] [--description \"...\"]",
     "  cat update.md | myte update-owner --stdin --subject \"Owner update\" --confirm-write --approval-artifact ./update.md",
     "  cat update.md | myte update-client --stdin --subject \"Weekly client update\" --confirm-write --approval-artifact ./update.md",
     "",
@@ -305,7 +306,9 @@ function printHelp() {
     "  - Add --document-set to create one feedback item containing up to three ordered markdown documents",
     "  - Document-set source markdown is preserved exactly; canonical markdown is generated server-side for reading and DOCX rendering",
     "  - Title source: myte-kanban.title, first # heading, or --title",
-    "  - Description source: myte-kanban.description or --description; this is a short feedback/card summary only",
+    "  - Description source: myte-kanban.description or --description; this is a short feedback/card summary only",
+    "  - New PRDs are unassigned unless --assigned-user-id or --assigned-user-email is provided",
+    "  - Explicit assignees must be the project owner or an active assigned project collaborator",
     "  - Never put the full PRD in description. The complete PRD must live in the markdown file body",
     "  - Each item carries the full PRD markdown blob as prd_markdown/ticket_markdown",
     "  - Backend stores that blob as the renderable PRD document source, mirrors it for PRD text search/sync, and generates a DOCX attachment",
@@ -352,6 +355,7 @@ function printHelp() {
     "  - get/history read current feedback snapshots and audited event history through the project-key API",
     "  - prd-versions/prd-diff expose retained PRD versions and backend-generated per-document text diffs",
     "  - edit/refine with --prd-file updates a review artifact only; --document-id targets one document in a PRD document set",
+    "  - document-add creates a governed review artifact that appends one linked PRD document; approval applies it through the same stale-safe PRD version flow",
     "  - validate/apply send artifacts to /api/project-assistant/feedback/<id>/refinement/* for validation or owner-direct apply",
     "  - The backend owns authorization, stale snapshot checks, allowed field/transition rules, and history",
     "  - apply is idempotent and does not rewrite local feedback.yml; run feedback-sync after apply to refresh local state",
@@ -377,7 +381,8 @@ function printHelp() {
     "  - reviews: list open/terminal/all requests or inspect one request",
     "  - review: approve, reject, request_changes, or cancel; backend restricts this to owner/delegate capability",
     "  - move: direct audited board movement for allowed states; governed transitions remain backend-authorized",
-    "  - comment: create a text-only comment on one Feedback item",
+    "  - document-add: create a governed proposal to append one linked PRD document to an existing Feedback item",
+    "  - comment: create a text-only comment on one Feedback item",
     "  - undo: reverse an audited board event when conflict checks allow it",
     "  - prd-versions: list retained PRD baselines/revisions for a feedback item",
     "  - prd-diff: fetch backend-generated text diff between PRD versions",
@@ -402,6 +407,8 @@ function printHelp() {
     "  --title <text>        Override PRD title for raw markdown uploads",
     "  --description <text>  Set feedback description/card summary for raw markdown uploads",
     "  --document-set        Create one PRD feedback item containing one to three ordered markdown files",
+    "  --assigned-user-id    Assign a newly created PRD to an eligible project user ObjectId",
+    "  --assigned-user-email Assign a newly created PRD to an eligible project user by exact email",
     "  --content <text>      Team update content for update-team",
     "  --body <text>         Feedback comment body for feedback comment",
     "  --subject <text>      Subject for update-owner or update-client",
@@ -424,10 +431,9 @@ function printHelp() {
     "  --reason <text>       Human review reason included in feedback refinement artifacts",
     "  --status <value>      Mission status target, feedback-sync filter, or feedback review state depending on command",
     "  --source <value>      Feedback source filter for feedback-sync",
-    "  --priority <value>    Feedback review priority target: Low, Medium, or High",
-    "  --user-id <id>        Feedback assignee user id for `myte feedback assign`",
-    "  --assigned-user-id    Alias for --user-id in feedback assign",
-    "  --due-date <date>     Feedback due date target for edit artifacts",
+    "  --priority <value>    Feedback review priority target: Low, Medium, or High",
+    "  --user-id <id>        Feedback assignee user id for `myte feedback assign`",
+    "  --due-date <date>     Feedback due date target for edit artifacts",
     "  --review-note <text>  Review note stored in feedback refinement history",
     "  --with-prd-text       Include extracted PRD text so local PRD files are materialized during feedback-sync (default: on)",
     "  --no-with-prd-text    Skip PRD and readable comment-attachment extraction; keep feedback/comment/attachment metadata",
@@ -471,13 +477,14 @@ function printHelp() {
     "  myte feedback review --request-id 507f1f77bcf86cd799439022 --action approve --reason \"Looks correct\" --json",
     "  myte feedback move --feedback-id 507f1f77bcf86cd799439011 --to-state in_progress --reason \"Started\" --json",
     "  myte feedback comment --feedback-id 507f1f77bcf86cd799439011 --body-file ./comments/implementation.md --confirm-write --approval-artifact ./comments/implementation.md --json",
+    "  myte feedback document-add --feedback-id 507f1f77bcf86cd799439011 --prd-file ./drafts/sidebar-branding.md --title \"Individual Use Sidebar Branding\" --reason \"Link governed UX addendum to the Feedback context.\"",
     "  myte feedback validate --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --json",
     "  myte feedback apply --file ./MyteCommandCenter/reviews/feedback/507f1f77bcf86cd799439011-status.yml --json",
     "  myte suggestions create --file ./suggestions/create.yml --confirm-write --approval-artifact ./suggestions/create.yml",
     "  myte suggestions revise --file ./suggestions/revise.yml --confirm-write --approval-artifact ./suggestions/revise.yml",
     "  myte suggestions review",
     "  myte update-client --subject \"Weekly client update\" --body-markdown \"## Progress\\n- Login complete\" --target-contact-ids 507f1f77bcf86cd799439011,507f1f77bcf86cd799439012 --confirm-write --approval-artifact ./updates/week-12.md",
-    "  myte create-prd ./drafts/auth-prd.md --description \"Short card summary\" --confirm-write --approval-artifact ./drafts/auth-prd.md",
+    "  myte create-prd ./drafts/auth-prd.md --description \"Short card summary\" --assigned-user-email dev@example.com --confirm-write --approval-artifact ./drafts/auth-prd.md",
     "  myte create-prd ./drafts/auth-prd.md ./drafts/billing-prd.md --confirm-write --approval-artifact ./drafts/prd-batch.md",
     "  myte create-prd ./drafts/overview.md ./drafts/api.md ./drafts/web.md --document-set --title \"Platform PRD\" --confirm-write --approval-artifact ./drafts/platform-prd-approval.md",
     "  cat ./drafts/auth-prd.md | myte create-prd --stdin --confirm-write --approval-artifact ./drafts/auth-prd.md",
@@ -5479,6 +5486,27 @@ async function runCreatePrd(args) {
   const documentSetMode = Boolean(
     args["document-set"] || args.documentSet || args.document_set
   );
+  const assignedUserId = firstNonEmptyString(
+    args["assigned-user-id"],
+    args.assignedUserId,
+    args.assigned_user_id
+  );
+  const assignedUserEmail = firstNonEmptyString(
+    args["assigned-user-email"],
+    args.assignedUserEmail,
+    args.assigned_user_email
+  );
+
+  if (assignedUserId && assignedUserEmail) {
+    console.error("Use either --assigned-user-id or --assigned-user-email, not both.");
+    process.exit(1);
+  }
+
+  const applyCreatePrdAssignment = (payload) => {
+    if (assignedUserId) payload.assigned_user_id = assignedUserId;
+    if (assignedUserEmail) payload.assigned_user_email = assignedUserEmail;
+    return payload;
+  };
 
   if (useStdin && providedPaths.length) {
     console.error("Use either file paths or --stdin for create-prd, not both.");
@@ -5520,7 +5548,7 @@ async function runCreatePrd(args) {
     if (includeClientRef && filePath) {
       payload.client_ref = path.relative(process.cwd(), filePath) || path.basename(filePath);
     }
-    return payload;
+    return applyCreatePrdAssignment(payload);
   };
 
   let payloads = [];
@@ -5596,7 +5624,7 @@ async function runCreatePrd(args) {
         if (priority) documentSetPayload.priority = priority;
         if (status) documentSetPayload.status = status;
         if (tags) documentSetPayload.tags = tags;
-        payloads = [documentSetPayload];
+        payloads = [applyCreatePrdAssignment(documentSetPayload)];
       } else {
         payloads = resolvedFiles.map(({ absPath, sourceText }) =>
           buildCreatePrdPayload({
@@ -6629,7 +6657,50 @@ async function buildFeedbackDraftForCommand(args, subcommand) {
       process.exit(1);
     }
     changes.assigned_user_id = feedbackChange(firstNonEmptyString(item.assigned_user_id), assignee);
-  } else if (action === "edit" || action === "refine") {
+  } else if (action === "document-add") {
+    const prdFile = firstNonEmptyString(
+      args["prd-file"],
+      args.prdFile,
+      args.prd_file,
+      args["document-file"],
+      args.documentFile,
+      args.document_file,
+      args._?.[2],
+    );
+    if (!prdFile) {
+      console.error("Missing --prd-file for feedback document-add.");
+      process.exit(1);
+    }
+    const proposedPath = resolveInputFile(prdFile, "PRD document addition");
+    const proposedMarkdown = fs.readFileSync(proposedPath, "utf8");
+    if (!proposedMarkdown.trim()) {
+      console.error("PRD document markdown cannot be empty.");
+      process.exit(1);
+    }
+    if (proposedMarkdown.length > 250000) {
+      console.error("PRD document markdown must be at most 250000 characters.");
+      process.exit(1);
+    }
+    const filename = firstNonEmptyString(
+      args.filename,
+      args["file-name"],
+      args.fileName,
+      path.basename(proposedPath),
+    );
+    const derivedTitle = firstNonEmptyString(
+      args.title,
+      String(proposedMarkdown.match(/^#\s+(.+)$/m)?.[1] || "").trim(),
+      path.basename(proposedPath, path.extname(proposedPath)),
+      "Linked PRD document",
+    );
+    const clientRef = firstNonEmptyString(args["client-ref"], args.clientRef, args.client_ref, filename);
+    changes.prd_document_addition = feedbackChange(null, {
+      source_markdown: proposedMarkdown,
+      title: derivedTitle,
+      filename,
+      client_ref: clientRef,
+    });
+  } else if (action === "edit" || action === "refine") {
     const title = firstNonEmptyString(args.title);
     if (title) changes.title = feedbackChange(firstNonEmptyString(item.title), title);
 
@@ -6706,7 +6777,7 @@ async function buildFeedbackDraftForCommand(args, subcommand) {
       }
     }
   } else {
-    console.error("Unknown feedback draft command. Use status, edit, assign, archive, or refine.");
+    console.error("Unknown feedback draft command. Use status, edit, document-add, assign, archive, or refine.");
     process.exit(1);
   }
 
@@ -7616,7 +7687,7 @@ async function runFeedback(args) {
     printHelp();
     return;
   }
-  if (["status", "edit", "assign", "archive", "refine"].includes(subcommand)) {
+  if (["status", "edit", "document-add", "assign", "archive", "refine"].includes(subcommand)) {
     await buildFeedbackDraftForCommand(args, subcommand);
     return;
   }
@@ -7664,7 +7735,7 @@ async function runFeedback(args) {
     await runFeedbackGetOrHistory(args, subcommand);
     return;
   }
-  console.error("Unknown feedback command. Use status, edit, assign, archive, submit, revise, reviews, review, move, comment, undo, prd-versions, prd-diff, get, history, validate, or apply.");
+  console.error("Unknown feedback command. Use status, edit, document-add, assign, archive, submit, revise, reviews, review, move, comment, undo, prd-versions, prd-diff, get, history, validate, or apply.");
   process.exit(1);
 }
 

package/mytecody-cli.js

@@ -634,12 +634,12 @@ function manifestWithoutSignature(manifest) {
   return clone;
 }
 
-function verifyManifestSignature(manifest) {
+function verifyManifestSignature(manifest, { publicKeyPem } = {}) {
   const signature = manifest && manifest.signature;
   if (!signature || !signature.value) {
     return { status: "missing", verified: false };
   }
-  const publicKey = builtInPublicKeyPem();
+  const publicKey = publicKeyPem || builtInPublicKeyPem();
   if (!publicKey) {
     return {
       status: "public-key-missing",
@@ -772,8 +772,8 @@ function artifactBytesForInstall(bytes, artifact) {
   throw new Error(`Unsupported MyteCody release artifact format: ${format}`);
 }
 
-function signatureAccepted(manifest, args = {}) {
-  const signature = verifyManifestSignature(manifest);
+function signatureAccepted(manifest, args = {}, { publicKeyPem } = {}) {
+  const signature = verifyManifestSignature(manifest, { publicKeyPem });
   if (signature.verified) return { ok: true, signature, trusted_unsigned: false };
   return { ok: false, signature, trusted_unsigned: false };
 }
@@ -1776,7 +1776,11 @@ async function runDoctor(args, envPath) {
   return 0;
 }
 
-async function buildUpdatePayload(args, envPath, { dryRun = false, progress = null } = {}) {
+async function buildUpdatePayload(
+  args,
+  envPath,
+  { dryRun = false, progress = null, publicKeyPem } = {},
+) {
   const isDryRun = Boolean(dryRun);
   const source = manifestUrl(args);
   const manifestResult = await readManifest(source, {
@@ -1785,7 +1789,9 @@ async function buildUpdatePayload(args, envPath, { dryRun = false, progress = nu
   });
   const manifest = manifestResult.manifest;
   const artifact = manifest ? artifactForPlatform(manifest) : null;
-  const signature = manifest ? signatureAccepted(manifest, args) : { ok: false, signature: { status: "not-checked", verified: false } };
+  const signature = manifest
+    ? signatureAccepted(manifest, args, { publicKeyPem })
+    : { ok: false, signature: { status: "not-checked", verified: false } };
   const artifactMetadata = manifest ? validateArtifactMetadata(artifact) : { status: "not-checked", ok: false };
   const releaseAssets = manifest ? releaseAssetsForPlatform(manifest, artifact) : [];
   const payload = {
@@ -1870,7 +1876,11 @@ function autoInstallEnabled(args = {}) {
   return true;
 }
 
-async function ensureBrandedEngineInstalled(args = {}, envPath = null, { progress = null } = {}) {
+async function ensureBrandedEngineInstalled(
+  args = {},
+  envPath = null,
+  { progress = null, publicKeyPem } = {},
+) {
   const updateArgs = {
     ...args,
     "fetch-manifest": true,
@@ -1906,7 +1916,7 @@ async function ensureBrandedEngineInstalled(args = {}, envPath = null, { progres
     }
     return { ok: false, installed: false, reason: "manifest-unavailable", manifest_status: manifestResult.status };
   }
-  const signature = signatureAccepted(manifest, updateArgs);
+  const signature = signatureAccepted(manifest, updateArgs, { publicKeyPem });
   if (!signature.ok) {
     return { ok: false, installed: false, reason: "manifest-untrusted", signature: signature.signature };
   }
@@ -1923,7 +1933,11 @@ async function ensureBrandedEngineInstalled(args = {}, envPath = null, { progres
     return { ok: false, installed: false, reason: "update-required-auto-install-disabled" };
   }
 
-  const payload = await buildUpdatePayload(updateArgs, envPath, { dryRun: false, progress });
+  const payload = await buildUpdatePayload(updateArgs, envPath, {
+    dryRun: false,
+    progress,
+    publicKeyPem,
+  });
   return {
     ok: Boolean(payload.installed && payload.installed.ok),
     installed: Boolean(payload.installed && payload.installed.ok),
@@ -1932,11 +1946,12 @@ async function ensureBrandedEngineInstalled(args = {}, envPath = null, { progres
   };
 }
 
-async function runUpdate(args, envPath) {
+async function runUpdate(args, envPath, { publicKeyPem } = {}) {
   const dryRun = Boolean(args["dry-run"]);
   const payload = await buildUpdatePayload(args, envPath, {
     dryRun,
     progress: args.json ? null : statusLine,
+    publicKeyPem,
   });
 
   if (args.json) {
@@ -1964,7 +1979,7 @@ async function runUpdate(args, envPath) {
   return 0;
 }
 
-async function run(argv = process.argv.slice(2)) {
+async function run(argv = process.argv.slice(2), { publicKeyPem } = {}) {
   const envPath = loadEnv();
   const parsed = parseArgs(argv);
   const command = argv[0] || "codex";
@@ -1975,7 +1990,7 @@ async function run(argv = process.argv.slice(2)) {
     return 0;
   }
   if (command === "doctor") return runDoctor(restArgs, envPath);
-  if (command === "update") return runUpdate(restArgs, envPath);
+  if (command === "update") return runUpdate(restArgs, envPath, { publicKeyPem });
   if (command === "controller-sidecar") return runControllerSidecar();
   if (command === "version" || command === "--version" || command === "-v") {
     console.log(PACKAGE_VERSION);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mytegroupinc/myte-core",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "Myte CLI core implementation.",
   "type": "commonjs",
   "main": "cli.js",