gmc-openspec 1.4.1 → 1.4.3

package/dist/commands/jira.js

@@ -111,6 +111,7 @@ export function registerJiraCommand(program) {
                 issueDir: intakeResult.issueDir,
                 intakePath: intakeResult.path,
                 status,
+                documentLanguage: intakeResult.intake?.documentLanguage,
                 allowedNext: status ? getAllowedNext(status) : [],
                 nextCommands: status ? getNextCommands(status, jiraId.toUpperCase()) : [],
                 blockingStage,

package/dist/core/jira/constants.d.ts

@@ -4,6 +4,8 @@ export declare const JIRA_CONFIG_VERSION = 1;
 export declare const JIRA_INTAKE_SCHEMA_VERSION = 1;
 export declare const JIRA_DEFAULT_PROVIDER = "atlassian-rovo";
 export declare const JIRA_DEFAULT_ENDPOINT = "https://mcp.atlassian.com/v1/mcp/authv2";
+export declare const JIRA_DOCUMENT_LANGUAGES: readonly ["en", "zh-CN"];
+export type JiraDocumentLanguage = (typeof JIRA_DOCUMENT_LANGUAGES)[number];
 export declare const JIRA_WORKFLOW_IDS: readonly ["jira-import", "jira-refine", "jira-review", "jira-split", "jira-propose", "jira-sync"];
 export type JiraWorkflowId = (typeof JIRA_WORKFLOW_IDS)[number];
 export declare const JIRA_WORKFLOW_TO_SKILL_DIR: Record<JiraWorkflowId, string>;

package/dist/core/jira/constants.js

@@ -4,6 +4,7 @@ export const JIRA_CONFIG_VERSION = 1;
 export const JIRA_INTAKE_SCHEMA_VERSION = 1;
 export const JIRA_DEFAULT_PROVIDER = 'atlassian-rovo';
 export const JIRA_DEFAULT_ENDPOINT = 'https://mcp.atlassian.com/v1/mcp/authv2';
+export const JIRA_DOCUMENT_LANGUAGES = ['en', 'zh-CN'];
 export const JIRA_WORKFLOW_IDS = [
     'jira-import',
     'jira-refine',

package/dist/core/jira/intake.d.ts

@@ -13,6 +13,10 @@ export declare const JiraIntakeSchema: z.ZodObject<{
         proposed: "proposed";
         synced: "synced";
     }>>;
+    documentLanguage: z.ZodDefault<z.ZodEnum<{
+        en: "en";
+        "zh-CN": "zh-CN";
+    }>>;
     sourceHashSha256: z.ZodOptional<z.ZodString>;
     allowedNext: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         split: "split";

package/dist/core/jira/intake.js

@@ -2,13 +2,14 @@ import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { parse as parseYaml } from 'yaml';
 import { z } from 'zod';
-import { JIRA_ALLOWED_NEXT, JIRA_INTAKE_SCHEMA_VERSION, JIRA_STATUS_ORDER, } from './constants.js';
+import { JIRA_ALLOWED_NEXT, JIRA_DOCUMENT_LANGUAGES, JIRA_INTAKE_SCHEMA_VERSION, JIRA_STATUS_ORDER, } from './constants.js';
 import { getJiraIssueDir, normalizeJiraId } from './paths.js';
 export const JiraIntakeSchema = z
     .object({
     schemaVersion: z.number().int().positive().default(JIRA_INTAKE_SCHEMA_VERSION),
     jira: z.string().min(1),
     status: z.enum(JIRA_STATUS_ORDER).default('imported'),
+    documentLanguage: z.enum(JIRA_DOCUMENT_LANGUAGES).default('en'),
     sourceHashSha256: z.string().optional(),
     allowedNext: z.array(z.enum(JIRA_STATUS_ORDER)).optional(),
 })

package/dist/core/jira/templates.js

@@ -5,6 +5,8 @@ const SHARED_GUARDRAILS = `
 - Treat Jira as the business input source, not the final engineering specification.
 - Never create or modify \`openspec/changes/*\` directly from raw Jira description or comments.
 - Never modify \`source.md\`; it is a read-only Jira snapshot protected by \`sourceHashSha256\` in \`intake.yaml\`.
+- Use \`intake.yaml\` \`documentLanguage\` for generated prose documents: \`en\` means English and \`zh-CN\` means Simplified Chinese.
+- Keep structured YAML fields, status enum values, mapping keys, story IDs, requirement IDs, and traceability keys as stable English/code values regardless of \`documentLanguage\`.
 - Blocking questions must be answered before requirements can be marked reviewed.
 - Assumptions must be explicit in \`assumptions.md\` and approved before story split or OpenSpec proposal.
 - Keep \`mapping.yaml\` current so Jira AC maps to requirements, stories, and OpenSpec changes.
@@ -28,13 +30,16 @@ ${SHARED_GUARDRAILS}
    - Read summary, description, acceptance criteria, comments, linked issues, labels, components, and attachments metadata where available.
    - Use \`getJiraIssueRemoteIssueLinks\` and \`searchJiraIssuesUsingJql\` only when linked issues or related ticket lookup is needed.
    - Do not write to Jira.
-2. Create \`jira/<JIRA-ID>-<slug>/\` using a short slug from the Jira summary.
-3. Write \`source.md\` as an auditable snapshot with field names and source sections.
-4. Compute SHA-256 of \`source.md\` and write \`intake.yaml\`:
-   \`schemaVersion: 1\`, \`jira\`, \`status: imported\`, \`sourceHashSha256\`.
-5. Write \`requirement-draft.md\` as a concise product requirement draft.
-6. Write initial \`questions.md\`, \`assumptions.md\`, and \`mapping.yaml\` placeholders.
-7. Run \`openspec jira validate <JIRA-ID> --stage source\` and report the result.
+2. Ask the user which document language to use for subsequent generated documents: English or Simplified Chinese. Default to English when the user has no preference.
+   - Record English as \`documentLanguage: en\`.
+   - Record Simplified Chinese as \`documentLanguage: zh-CN\`.
+3. Create \`jira/<JIRA-ID>-<slug>/\` using a short slug from the Jira summary.
+4. Write \`source.md\` as an auditable snapshot with field names and source sections. Preserve the original Jira text and do not translate \`source.md\`.
+5. Compute SHA-256 of \`source.md\` and write \`intake.yaml\`:
+   \`schemaVersion: 1\`, \`jira\`, \`status: imported\`, \`documentLanguage\`, \`sourceHashSha256\`.
+6. Write \`requirement-draft.md\` as a concise product requirement draft using \`documentLanguage\`.
+7. Write initial \`questions.md\` and \`assumptions.md\` using \`documentLanguage\`, plus \`mapping.yaml\` placeholders with stable English/code keys.
+8. Run \`openspec jira validate <JIRA-ID> --stage source\` and report the result.
 
 ## Output
 
@@ -52,14 +57,14 @@ ${SHARED_GUARDRAILS}
 
 ## Steps
 
-1. Run \`openspec jira status <JIRA-ID> --json\` and read the intake folder.
+1. Run \`openspec jira status <JIRA-ID> --json\` and read the intake folder, including \`intake.yaml\` \`documentLanguage\`.
 2. Read \`source.md\`, \`requirement-draft.md\`, \`questions.md\`, \`assumptions.md\`, and \`mapping.yaml\`.
 3. Identify ambiguity as either:
    - **Blocking**: affects scope, AC, permissions, data contract, external behavior, or story boundaries.
    - **Non-Blocking**: can be captured as an explicit assumption.
-4. Ask the user all blocking questions before proceeding. Update \`questions.md\` with statuses.
-5. Record non-blocking assumptions in \`assumptions.md\`; do not hide assumptions in requirement prose.
-6. When blocking questions are resolved, write \`requirement.md\` and set \`intake.yaml\` status to \`ready-for-review\`.
+4. Ask the user all blocking questions before proceeding. Update \`questions.md\` with statuses using \`documentLanguage\`.
+5. Record non-blocking assumptions in \`assumptions.md\` using \`documentLanguage\`; do not hide assumptions in requirement prose.
+6. When blocking questions are resolved, write \`requirement.md\` using \`documentLanguage\` and set \`intake.yaml\` status to \`ready-for-review\`.
 7. Run \`openspec jira validate <JIRA-ID> --stage requirement\`.
 
 ## Output
@@ -78,7 +83,7 @@ ${SHARED_GUARDRAILS}
 
 ## Steps
 
-1. Read \`requirement.md\`, \`questions.md\`, and \`assumptions.md\`.
+1. Read \`intake.yaml\` to get \`documentLanguage\`, then read \`requirement.md\`, \`questions.md\`, and \`assumptions.md\`.
 2. Run \`openspec jira validate <JIRA-ID> --stage requirement --json\`.
 3. If validation fails, explain the blockers and return to \`/opsx:jira-refine\`.
 4. Ask the user to approve or request edits to the requirement and assumptions.
@@ -105,8 +110,8 @@ Each story must have independent review value, clear AC, scope, non-goals, depen
 ## Steps
 
 1. Run \`openspec jira validate <JIRA-ID> --stage requirement --json\`.
-2. Read \`requirement.md\`, \`mapping.yaml\`, and existing OpenSpec specs if capability choices are unclear.
-3. Write \`stories.md\` with story ids, titles, scope, non-goals, AC, dependencies, risks, and suggested OpenSpec change names.
+2. Read \`intake.yaml\` to get \`documentLanguage\`, plus \`requirement.md\`, \`mapping.yaml\`, and existing OpenSpec specs if capability choices are unclear.
+3. Write \`stories.md\` using \`documentLanguage\`, with stable English/code story ids, titles, scope, non-goals, AC, dependencies, risks, and suggested OpenSpec change names.
 4. Update \`mapping.yaml\` so every Jira AC maps to at least one story.
 5. Set \`intake.yaml\` status to \`split\` and ask the user to review the story split.
 6. After explicit user approval, set status to \`stories-reviewed\` and run \`openspec jira validate <JIRA-ID> --stage stories\`.
@@ -128,13 +133,13 @@ ${SHARED_GUARDRAILS}
 ## Steps
 
 1. Run \`openspec jira validate <JIRA-ID> --stage stories --json\`. Stop if it fails.
-2. Read \`stories.md\`, \`mapping.yaml\`, and \`requirement.md\`.
+2. Read \`intake.yaml\` to get \`documentLanguage\`, plus \`stories.md\`, \`mapping.yaml\`, and \`requirement.md\`.
 3. For each non-deferred reviewed story, create exactly one OpenSpec change:
    \`openspec new change <jira-id>-<story-slug>\`.
 4. Generate artifacts through the existing OpenSpec flow:
    - Run \`openspec status --change <change> --json\`.
    - For each ready artifact, run \`openspec instructions <artifact> --change <change> --json\`.
-   - Create \`proposal.md\`, delta specs, \`design.md\`, and \`tasks.md\` from the reviewed story and requirement, not raw Jira text.
+   - Create \`proposal.md\`, delta specs, \`design.md\`, and \`tasks.md\` using \`documentLanguage\` from the reviewed story and requirement, not raw Jira text.
 5. Update \`mapping.yaml\` so every story records its OpenSpec change and spec files.
 6. Set \`intake.yaml\` status to \`proposed\` and run \`openspec jira validate <JIRA-ID> --stage propose\`.
 
@@ -155,7 +160,11 @@ ${SHARED_GUARDRAILS}
 ## Writeback Rules
 
 - This is the only Jira intake workflow allowed to write to Jira.
-- Before any Jira comment, child issue creation, link update, or status change, show a concrete diff of the write.
+- Child issue writeback is the default strategy for reviewed stories.
+- For every non-deferred story missing \`stories.<storyId>.jiraIssueKey\` in \`mapping.yaml\`, the writeback plan MUST include a \`createJiraIssue\` operation.
+- Do not create duplicate Jira child issues for stories that already have \`jiraIssueKey\`; plan only needed link, update, or status changes for those stories.
+- Summary comment sync is optional. Do not include a Jira comment by default unless the user explicitly requests one, or there are no child issues to create.
+- Before any child issue creation, link update, status change, field edit, or optional comment, show a concrete diff of the write.
 - Ask for explicit confirmation before each batch of writes.
 - If \`openspec/jira.yaml\` has \`writeback.enabled: false\`, ask the user to confirm this one-time sync before writing.
 - Use only the official Atlassian MCP Jira write tools needed for the confirmed diff: \`addCommentToJiraIssue\`, \`editJiraIssue\`, \`getTransitionsForJiraIssue\`, \`transitionJiraIssue\`, and \`createJiraIssue\`.
@@ -164,10 +173,15 @@ ${SHARED_GUARDRAILS}
 
 1. Run \`openspec jira validate <JIRA-ID> --stage propose --json\` when syncing proposed OpenSpec changes.
 2. Read \`mapping.yaml\`, \`stories.md\`, and current OpenSpec change status.
-3. Prepare a writeback plan: comments, links, child issues, or status moves.
-4. Show the diff and wait for explicit user approval.
-5. Use the named Atlassian MCP write tools only after approval.
-6. Update \`intake.yaml\` status to \`synced\` only after successful writeback.
+3. Identify all non-deferred reviewed stories and split them into:
+   - stories missing \`jiraIssueKey\`, which must be planned as Jira child issues;
+   - stories with \`jiraIssueKey\`, which must not be recreated.
+4. Prepare a child-issue-first writeback plan. For each \`createJiraIssue\`, show the Jira summary, issue type, parent/source issue, description or acceptance criteria, trace links, and corresponding OpenSpec change.
+5. Include an optional summary comment only when the user requested comment sync, or when there are no child issues to create.
+6. Show the full diff and wait for explicit user approval.
+7. Use the named Atlassian MCP write tools only after approval.
+8. After each successful \`createJiraIssue\`, update the matching \`stories.<storyId>.jiraIssueKey\` in \`mapping.yaml\`.
+9. Update \`intake.yaml\` status to \`synced\` only after successful writeback and local mapping updates.
 
 ## Output
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gmc-openspec",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",