coding-agent-harness 1.0.1 → 1.0.2

package/templates/dashboard/assets/app.manifest.json

@@ -0,0 +1,11 @@
+[
+  "app-src/00-state.js",
+  "app-src/10-router.js",
+  "app-src/20-overview.js",
+  "app-src/30-tasks.js",
+  "app-src/40-modules.js",
+  "app-src/45-review.js",
+  "app-src/50-migration.js",
+  "app-src/60-shared.js",
+  "app-src/90-bindings.js"
+]

package/templates/dashboard/assets/i18n.js

@@ -1,47 +1,432 @@
 window.HarnessI18n = {
-  en: {
-    overview: "Overview",
-    ledger: "Ledger",
-    tasks: "Tasks",
-    modules: "Modules",
-    evidence: "Evidence",
-    lessons: "Lessons",
-    adoption: "Adoption",
-    settings: "Settings",
-    system: "System",
-    readiness: "Readiness",
-    blockers: "Blockers",
-    warnings: "Advice",
-    nextAction: "Next action",
-    activeTasks: "Active tasks",
-    evidenceHealth: "Evidence health",
-    detail: "Detail",
-    plan: "Plan",
-    strategy: "Execution strategy",
-    roadmap: "Visual roadmap",
-    progress: "Progress",
-    review: "Review",
-    findings: "Findings",
-    references: "References",
-    artifacts: "Artifacts",
-    source: "Source",
-    rendered: "Rendered",
-    light: "Light",
-    dark: "Dark",
-    compact: "Compact",
-    comfortable: "Comfortable",
-    noSelection: "Select a row to inspect the document snapshot",
-    task: "Task",
-    state: "State",
-    completion: "Completion",
-    roadmapSource: "Roadmap",
-    category: "Category",
-    severity: "Severity",
-    title: "Title",
-    affected: "Affected",
-    requiredAction: "Required action",
-    message: "Detail",
-    graph: "Graph",
-    origin: "Source",
+  "en": {
+    "eyebrow": "Human Visibility Dashboard",
+    "projectCockpit": "Console",
+    "overview": "Overview",
+    "taskIndex": "Task Index",
+    "reviewQueue": "Review Queue",
+    "moduleView": "Modules",
+    "readiness": "Readiness",
+    "tasks": "Tasks",
+    "blockers": "Blockers",
+    "advice": "Advice",
+    "warnings": "Warnings",
+    "failures": "Failures",
+    "briefCoverage": "Brief coverage",
+    "visualMapCoverage": "Visual map coverage",
+    "fullCutover": "Full cutover",
+    "ready": "Ready",
+    "notReady": "Not ready",
+    "legacyVisualOnly": "Legacy visual only",
+    "weakBrief": "Weak brief",
+    "resolveBlockers": "Resolve release blockers before continuing.",
+    "missingBriefs": "tasks still need human visibility briefs.",
+    "reviewAdvice": "Continue, but keep adoption advice visible.",
+    "noBlockers": "No blockers in this snapshot.",
+    "firstLook": "First look",
+    "projectFlow": "Project Flow",
+    "projectProgress": "Project Progress",
+    "completed": "completed",
+    "done": "Done",
+    "active": "Active",
+    "planned": "Planned",
+    "nodes": "nodes",
+    "edges": "edges",
+    "noFlow": "No computable flow yet. Add brief.md Mermaid or module/task roadmaps.",
+    "currentWork": "Current work",
+    "activeBriefs": "Active Task Briefs",
+    "openTaskIndex": "Open task index",
+    "noActiveTasks": "No active task brief found.",
+    "visibilityBriefMissing": "Visibility brief missing",
+    "missingBriefExplain": "This task can be checked by agents, but humans still cannot understand it from the dashboard alone.",
+    "noPhaseData": "No phase data.",
+    "searchPlaceholder": "Search title, id, module, or state",
+    "searchTasks": "Search tasks",
+    "stateFilter": "Filter by state",
+    "briefReady": "brief ready",
+    "briefMissing": "brief missing",
+    "taskNotFound": "Task not found.",
+    "taskVisibility": "Task visibility",
+    "phaseTimeline": "Phase Timeline",
+    "taskPlan": "Task Plan",
+    "brief": "Brief",
+    "strategy": "Execution Strategy",
+    "visualMap": "Visual Map",
+    "legacyRoadmap": "Legacy Visual Roadmap",
+    "progress": "Progress",
+    "review": "Review",
+    "findings": "Findings",
+    "walkthrough": "Walkthrough",
+    "lessonCandidates": "Lesson Candidates",
+    "longRunningContract": "Long-running Contract",
+    "references": "References",
+    "artifacts": "Artifacts",
+    "source": "Source",
+    "rendered": "Rendered",
+    "sourceDocuments": "Source Documents",
+    "taskDocuments": "Task Documents",
+    "generatedFallback": "generated fallback",
+    "noDocuments": "No source documents.",
+    "selectedSource": "Selected Source",
+    "openFindings": "Open Findings",
+    "noOpenFindings": "No open findings.",
+    "evidence": "Evidence",
+    "noEvidence": "No evidence logged.",
+    "noModules": "No modules found.",
+    "moduleBriefMissing": "Module brief missing. Add a module-level visibility brief before treating module migration as complete.",
+    "moduleTasks": "Module Tasks",
+    "noModuleTasks": "No module tasks.",
+    "migration": "Migration",
+    "migrationSnapshot": "Migration Snapshot",
+    "taskPreset": "Task preset",
+    "targetLevel": "Target level",
+    "achievedLevel": "Achieved level",
+    "strictDeferred": "Strict deferred",
+    "evidenceBundle": "Evidence bundle",
+    "migrationSummary": "Migration Attention",
+    "migrationWorkbench": "Migration Workbench",
+    "aggregateMigrationView": "aggregate migration view",
+    "runwayBaseline": "Baseline snapshot",
+    "runwayTriage": "Warning triage",
+    "runwayContracts": "Active task contracts",
+    "runwayModules": "Module classification",
+    "runwayCutover": "Strict cutover",
+    "items": "items",
+    "groups": "groups",
+    "warningFilter": "Filter warnings",
+    "allWarnings": "All warnings",
+    "noWarnings": "No warnings in this filter.",
+    "showing": "Showing",
+    "showingGroups": "Showing groups",
+    "prevPage": "Previous",
+    "nextPage": "Next",
+    "confidence": "confidence",
+    "addVisibilityBrief": "Add a human-readable brief before this task is treated as migrated.",
+    "groupBy": "Group by",
+    "group_migration": "Migration bucket",
+    "group_module": "Module",
+    "group_month": "Month",
+    "group_state": "State",
+    "inferredModule": "Module",
+    "unclassifiedModule": "legacy-unclassified",
+    "visibilityLayer": "Visibility Layer",
+    "lessons": "Lessons",
+    "lesson": "Lesson",
+    "noLessons": "No lessons captured.",
+    "releaseHealth": "Release Health",
+    "activeCurrent": "Active / Current",
+    "briefReadyGroup": "Brief-ready Tasks",
+    "legacyMonth": "Legacy Tasks",
+    "showMore": "Show more",
+    "showingFirst": "showing first",
+    "columnTask": "Task",
+    "columnState": "State",
+    "columnCompletion": "Completion",
+    "columnBrief": "Brief",
+    "statTotal": "Total",
+    "statInProgress": "In progress",
+    "statReview": "In review",
+    "statBlocked": "Blocked",
+    "statDone": "Done",
+    "statOverall": "overall",
+    "groupCompletion": "Group completion",
+    "none": "None",
+    "dark": "Dark",
+    "light": "Light",
+    "system": "System",
+    "state_all": "all",
+    "state_pass": "pass",
+    "state_warn": "warn",
+    "state_fail": "fail",
+    "state_in_progress": "in progress",
+    "state_planned": "planned",
+    "state_review": "review",
+    "state_blocked": "blocked",
+    "state_done": "done",
+    "state_unknown": "unknown",
+    "viewDetails": "View Details",
+    "close": "Close",
+    "fullView": "Open Full Page",
+    "lessonNotFound": "Lesson record not found",
+    "lessonDocMissing": "The detail Markdown documentation for this lesson was not found or is yet to be created.",
+    "ssotLedger": "Change & Quality Ledger SSoT",
+    "ledgerInsights": "Harness Ledger Insights",
+    "taskStatusSplit": "Ledger Task Distribution",
+    "lessonsCheckRate": "Lessons Review Rate",
+    "evidenceAuditRate": "Evidence Audit Rate",
+    "tagClosed": "Closed",
+    "tagOpen": "Active",
+    "tagBlocked": "Blocked",
+    "date": "Date",
+    "target": "Target",
+    "relation": "Relation",
+    "document": "Detail Doc",
+    "badgeBrief": "Brief",
+    "badgeBriefMissing": "No Brief",
+    "badgeMap": "Map",
+    "badgeMapMissing": "No Map",
+    "mapReady": "map ready",
+    "mapMissing": "map missing",
+    "legendTitle": "Legend",
+    "legendBriefDesc": "Indicates that the task contains a complete human-readable visibility brief.",
+    "legendMapDesc": "Indicates that the task is integrated into the architectural map.",
+    "filterTitle": "Filters & Controls",
+    "layout": "View Layout",
+    "layoutList": "List View",
+    "layoutGrid": "Grid View",
+    "legacyState": "Task state",
+    "lifecycleState": "Lifecycle",
+    "reviewStatus": "Review",
+    "closeoutStatus": "Closeout",
+    "state_closing": "closing",
+    "state_closed": "closed",
+    "state_ready": "ready",
+    "state_in_review": "in review",
+    "state_review-blocked": "review blocked",
+    "state_missing": "missing",
+    "state_required": "required",
+    "state_reviewed-unconfirmed": "reviewed",
+    "state_confirmed": "confirmed",
+    "state_blocked-open-findings": "blocked findings",
+    "reviewActions": "Review Actions",
+    "reviewWorkspace": "Review Workspace",
+    "openReviewWorkspace": "Open Review Workspace",
+    "reviewOpenInWorkspace": "Confirm review from the Review Workspace.",
+    "lessonCandidateStatus": "Lesson candidate status",
+    "reviewCandidateDecisionRequired": "Complete the lesson candidate decision before confirming human review.",
+    "documentMissing": "Document missing from this snapshot.",
+    "staticReadOnly": "Static snapshot is read-only",
+    "staticReadOnlyDetail": "Use the dynamic workbench to submit review or governance actions.",
+    "reviewQueueSubtitle": "Only tasks currently in the execution Review stage appear here. Closeout is tracked separately.",
+    "reviewReady": "Ready",
+    "reviewBlockedQueue": "Blocked",
+    "reviewConfirmedQueue": "Confirmed",
+    "noReviewTasks": "No tasks are currently in review.",
+    "reviewAlreadyConfirmed": "Human review is already confirmed.",
+    "reviewBlocked": "Close P0-P2 open or release-blocking findings before confirming.",
+    "reviewWalkthroughRequired": "Add and link a walkthrough in Closeout SSoT before confirming human review.",
+    "reviewWorkbenchReady": "Confirm the human review when the evidence and findings are checked.",
+    "reviewConfirmChecklist": "I checked the walkthrough, task review evidence, and open findings.",
+    "confirmReviewComplete": "Confirm Human Review",
+    "reviewChecklistRequired": "Check the confirmation box first.",
+    "reviewConfirmTextMismatch": "Type the task id shown in the input hint.",
+    "reviewSubmitting": "Submitting review confirmation...",
+    "reviewCompleteSuccess": "Review confirmed. Reloading snapshot...",
+    "reviewCompleteFailed": "Review confirmation failed"
   },
+  "zh": {
+    "eyebrow": "Coding Agent Harness 控制台",
+    "projectCockpit": "控制台",
+    "overview": "总览",
+    "taskIndex": "任务索引",
+    "reviewQueue": "审查队列",
+    "moduleView": "模块",
+    "readiness": "发布状态",
+    "tasks": "任务",
+    "blockers": "阻塞",
+    "advice": "建议",
+    "warnings": "警告",
+    "failures": "失败",
+    "briefCoverage": "Brief 覆盖",
+    "visualMapCoverage": "图谱覆盖",
+    "fullCutover": "完整切换",
+    "ready": "就绪",
+    "notReady": "未就绪",
+    "legacyVisualOnly": "仅旧图谱",
+    "weakBrief": "弱 Brief",
+    "resolveBlockers": "先处理发布阻塞项。",
+    "missingBriefs": "个任务缺少给人看的 brief。",
+    "reviewAdvice": "可以继续，但升级建议必须保持可见。",
+    "noBlockers": "当前快照没有阻塞项。",
+    "firstLook": "第一眼",
+    "projectFlow": "项目流程图",
+    "projectProgress": "项目进度",
+    "completed": "已完成",
+    "done": "已完成",
+    "active": "进行中",
+    "planned": "待开始",
+    "nodes": "节点",
+    "edges": "边",
+    "noFlow": "还没有可计算流程图。请补 brief.md Mermaid 或任务/模块路线图。",
+    "currentWork": "当前工作",
+    "activeBriefs": "活跃任务 Brief",
+    "openTaskIndex": "打开任务索引",
+    "noActiveTasks": "没有活跃任务 brief。",
+    "visibilityBriefMissing": "缺少可见性 Brief",
+    "missingBriefExplain": "这个任务可以被 Agent 检查，但人还不能只靠 dashboard 看懂。",
+    "noPhaseData": "没有阶段数据。",
+    "searchPlaceholder": "搜索标题、ID、模块或状态",
+    "searchTasks": "搜索任务",
+    "stateFilter": "按状态过滤",
+    "briefReady": "brief 已就绪",
+    "briefMissing": "brief 缺失",
+    "taskNotFound": "找不到任务。",
+    "taskVisibility": "任务可见性",
+    "phaseTimeline": "阶段时间线",
+    "taskPlan": "任务计划",
+    "brief": "Brief",
+    "strategy": "执行策略",
+    "visualMap": "可视化图谱",
+    "legacyRoadmap": "旧版可视化路线",
+    "progress": "进度",
+    "review": "审查",
+    "findings": "发现",
+    "walkthrough": "Walkthrough",
+    "lessonCandidates": "教训候选",
+    "longRunningContract": "长程任务合同",
+    "references": "参考资料",
+    "artifacts": "证据产物",
+    "source": "来源建议",
+    "rendered": "渲染",
+    "sourceDocuments": "源文档",
+    "taskDocuments": "任务文档",
+    "generatedFallback": "生成兜底",
+    "noDocuments": "没有源文档。",
+    "selectedSource": "选中的源文档",
+    "openFindings": "开放发现",
+    "noOpenFindings": "没有开放发现。",
+    "evidence": "证据",
+    "noEvidence": "没有登记证据。",
+    "noModules": "没有模块。",
+    "moduleBriefMissing": "模块 brief 缺失。迁移完成前需要补一个模块级可见性 brief。",
+    "moduleTasks": "模块任务",
+    "noModuleTasks": "没有模块任务。",
+    "migration": "迁移",
+    "migrationSnapshot": "迁移快照",
+    "taskPreset": "任务 preset",
+    "targetLevel": "目标等级",
+    "achievedLevel": "实际完成等级",
+    "strictDeferred": "Strict deferred",
+    "evidenceBundle": "证据包",
+    "migrationSummary": "迁移关注项",
+    "migrationWorkbench": "迁移工作台",
+    "aggregateMigrationView": "聚合迁移视图",
+    "runwayBaseline": "基线快照",
+    "runwayTriage": "警告分诊",
+    "runwayContracts": "活跃任务合同",
+    "runwayModules": "模块分类",
+    "runwayCutover": "严格切换",
+    "items": "项",
+    "groups": "组",
+    "warningFilter": "筛选警告",
+    "allWarnings": "全部警告",
+    "noWarnings": "这个筛选下没有警告。",
+    "showing": "显示",
+    "showingGroups": "显示分组",
+    "prevPage": "上一页",
+    "nextPage": "下一页",
+    "confidence": "置信度",
+    "addVisibilityBrief": "补一个给人看的 brief，再把这个任务视为已迁移。",
+    "groupBy": "分组方式",
+    "group_migration": "迁移桶",
+    "group_module": "模块",
+    "group_month": "月份",
+    "group_state": "状态",
+    "inferredModule": "模块",
+    "unclassifiedModule": "未分类历史任务",
+    "visibilityLayer": "可见性层",
+    "lessons": "教训",
+    "lesson": "教训",
+    "noLessons": "没有教训记录。",
+    "releaseHealth": "发布健康度",
+    "activeCurrent": "活跃 / 当前",
+    "briefReadyGroup": "已有 Brief 的任务",
+    "legacyMonth": "历史任务",
+    "showMore": "展开更多",
+    "showingFirst": "先显示",
+    "columnTask": "任务",
+    "columnState": "状态",
+    "columnCompletion": "完成度",
+    "columnBrief": "Brief",
+    "none": "无",
+    "dark": "黑夜",
+    "light": "白天",
+    "system": "跟随系统",
+    "state_all": "全部",
+    "state_pass": "通过",
+    "state_warn": "警告",
+    "state_fail": "失败",
+    "state_in_progress": "进行中",
+    "state_planned": "计划中",
+    "state_review": "审查中",
+    "state_blocked": "阻塞",
+    "state_done": "完成",
+    "state_unknown": "未知",
+    "viewDetails": "查看详情",
+    "close": "关闭",
+    "fullView": "全屏查看",
+    "lessonNotFound": "未找到对应的教训记录",
+    "lessonDocMissing": "该沉淀教训的详情 Markdown 描述文档未在此数据快照中关联或尚未创建。",
+    "ssotLedger": "变更与质量账本 SSoT",
+    "ledgerInsights": "Harness 账本合规洞察",
+    "taskStatusSplit": "账本任务状态分布",
+    "lessonsCheckRate": "经验审查覆盖率",
+    "evidenceAuditRate": "验证证据齐备率",
+    "tagClosed": "已结案",
+    "tagOpen": "未结案",
+    "tagBlocked": "已阻塞",
+    "date": "发布日期",
+    "target": "修改目标",
+    "relation": "冲突关联",
+    "document": "详情文档",
+    "statTotal": "总计",
+    "statInProgress": "进行中",
+    "statReview": "审查中",
+    "statBlocked": "阻塞",
+    "statDone": "完成",
+    "statOverall": "整体进度",
+    "groupCompletion": "组内完成度",
+    "badgeBrief": "Brief",
+    "badgeBriefMissing": "无 Brief",
+    "badgeMap": "图谱",
+    "badgeMapMissing": "无图谱",
+    "mapReady": "图谱已就绪",
+    "mapMissing": "图谱缺失",
+    "legendTitle": "图谱图例",
+    "legendBriefDesc": "表示该任务包含完整的给人看的 visibility brief 文档",
+    "legendMapDesc": "表示该任务包含架构图谱定义",
+    "filterTitle": "过滤器与控制",
+    "layout": "展示布局",
+    "layoutList": "列表布局",
+    "layoutGrid": "网格布局",
+    "legacyState": "任务状态",
+    "lifecycleState": "生命周期",
+    "reviewStatus": "审查状态",
+    "closeoutStatus": "收口状态",
+    "state_closing": "收口中",
+    "state_closed": "已关闭",
+    "state_ready": "就绪",
+    "state_in_review": "审查中",
+    "state_review-blocked": "审查阻塞",
+    "state_missing": "缺失",
+    "state_required": "待审查",
+    "state_reviewed-unconfirmed": "已审未确认",
+    "state_confirmed": "已确认",
+    "state_blocked-open-findings": "发现阻塞",
+    "reviewActions": "审查操作",
+    "reviewWorkspace": "审查工作台",
+    "openReviewWorkspace": "打开审查工作台",
+    "reviewOpenInWorkspace": "请在审查工作台中确认审查。",
+    "lessonCandidateStatus": "教训候选状态",
+    "reviewCandidateDecisionRequired": "先完成 lesson candidate 判定，再确认人工审查。",
+    "documentMissing": "当前快照中没有这个文档。",
+    "staticReadOnly": "静态快照只读",
+    "staticReadOnlyDetail": "需要提交审查或治理动作时，请使用动态 workbench。",
+    "reviewQueueSubtitle": "这里只显示当前处在执行审查阶段的任务；收口状态单独跟踪。",
+    "reviewReady": "待确认",
+    "reviewBlockedQueue": "阻塞",
+    "reviewConfirmedQueue": "已确认",
+    "noReviewTasks": "当前没有处在审查阶段的任务。",
+    "reviewAlreadyConfirmed": "人工审查已经确认。",
+    "reviewBlocked": "先关闭 P0-P2 开放项或阻塞发布的发现，再确认审查。",
+    "reviewWalkthroughRequired": "先在 Closeout SSoT 中补充并链接 Walkthrough，再确认人工审查。",
+    "reviewWorkbenchReady": "确认前请核对审查证据与开放发现。",
+    "reviewConfirmChecklist": "我已核对 Walkthrough、任务审查证据和开放发现。",
+    "confirmReviewComplete": "确认人工审查",
+    "reviewChecklistRequired": "请先勾选确认框。",
+    "reviewConfirmTextMismatch": "请输入提示中的任务 ID。",
+    "reviewSubmitting": "正在提交审查确认...",
+    "reviewCompleteSuccess": "审查已确认，正在刷新快照...",
+    "reviewCompleteFailed": "审查确认失败"
+  }
 };

package/templates/dashboard/assets/mermaid-renderer.js

@@ -25,25 +25,35 @@ function parseFlowchart(code) {
     edges.push([from, to]);
   }
   if (nodes.size === 0) return null;
-  return { nodes: [...nodes.entries()], edges };
+  const direction = (lines[0].match(/^flowchart\s+(LR|TB|TD|RL|BT)/i)?.[1] || "LR").toUpperCase();
+  return { direction, nodes: [...nodes.entries()], edges };
 }
 
-function renderSvg({ nodes, edges }) {
-  const width = Math.max(360, nodes.length * 150);
-  const height = 150;
-  const positions = new Map(nodes.map(([id], index) => [id, { x: 70 + index * 140, y: 70 }]));
+function renderSvg({ direction, nodes, edges }) {
+  const layout = layoutNodes(nodes, direction);
+  const { positions, width, height } = layout;
   const nodeSvg = nodes.map(([id, label]) => {
     const pos = positions.get(id);
+    const displayLabel = truncateLabel(label);
     return `<g class="mermaid-node">
-      <rect x="${pos.x - 54}" y="${pos.y - 24}" width="108" height="48" rx="8"></rect>
-      <text x="${pos.x}" y="${pos.y + 4}" text-anchor="middle">${escapeMermaid(label).replaceAll("\\n", " ")}</text>
+      <title>${escapeMermaid(label).replaceAll("\\n", " ")}</title>
+      <rect x="${pos.x - pos.width / 2}" y="${pos.y - 24}" width="${pos.width}" height="48" rx="8"></rect>
+      <text x="${pos.x}" y="${pos.y + 4}" text-anchor="middle">${escapeMermaid(displayLabel)}</text>
     </g>`;
   }).join("");
   const edgeSvg = edges.map(([from, to]) => {
     const a = positions.get(from);
     const b = positions.get(to);
     if (!a || !b) return "";
-    return `<path class="mermaid-edge" d="M ${a.x + 54} ${a.y} L ${b.x - 62} ${b.y}"></path><path class="mermaid-arrow" d="M ${b.x - 62} ${b.y} l -7 -5 v 10 z"></path>`;
+    const horizontal = Math.abs(a.x - b.x) > Math.abs(a.y - b.y);
+    const startX = horizontal ? a.x + Math.sign(b.x - a.x) * (a.width / 2) : a.x;
+    const startY = horizontal ? a.y : a.y + Math.sign(b.y - a.y) * 24;
+    const endX = horizontal ? b.x - Math.sign(b.x - a.x) * (b.width / 2 + 8) : b.x;
+    const endY = horizontal ? b.y : b.y - Math.sign(b.y - a.y) * 32;
+    const arrow = horizontal
+      ? `M ${endX} ${endY} l ${b.x > a.x ? -7 : 7} -5 v 10 z`
+      : `M ${endX} ${endY} l -5 ${b.y > a.y ? -7 : 7} h 10 z`;
+    return `<path class="mermaid-edge" d="M ${startX} ${startY} L ${endX} ${endY}"></path><path class="mermaid-arrow" d="${arrow}"></path>`;
   }).join("");
   return `<figure class="mermaid-rendered">
     <figcaption>Mermaid</figcaption>
@@ -51,6 +61,46 @@ function renderSvg({ nodes, edges }) {
   </figure>`;
 }
 
+function layoutNodes(nodes, direction) {
+  const vertical = ["TD", "TB", "BT"].includes(direction);
+  const nodeSizes = nodes.map(([id, label]) => [id, nodeWidth(label)]);
+  const positions = new Map();
+  const margin = 48;
+  const rowGap = 104;
+  const colGap = 34;
+  if (vertical) {
+    const maxWidth = Math.max(220, ...nodeSizes.map(([, width]) => width));
+    nodeSizes.forEach(([id, width], index) => {
+      positions.set(id, { x: margin + maxWidth / 2, y: margin + 24 + index * rowGap, width });
+    });
+    return { positions, width: maxWidth + margin * 2, height: Math.max(150, margin * 2 + nodeSizes.length * rowGap) };
+  }
+
+  const maxPerRow = nodes.length > 5 ? Math.ceil(Math.sqrt(nodes.length * 1.4)) : nodes.length;
+  let y = margin + 24;
+  let width = 360;
+  for (let index = 0; index < nodeSizes.length; index += maxPerRow) {
+    const row = nodeSizes.slice(index, index + maxPerRow);
+    let x = margin;
+    for (const [id, nodeW] of row) {
+      positions.set(id, { x: x + nodeW / 2, y, width: nodeW });
+      x += nodeW + colGap;
+    }
+    width = Math.max(width, x + margin - colGap);
+    y += rowGap;
+  }
+  return { positions, width, height: Math.max(150, y + margin - rowGap) };
+}
+
+function nodeWidth(label) {
+  return Math.max(112, Math.min(240, String(label || "").replaceAll("\\n", " ").length * 7 + 34));
+}
+
+function truncateLabel(label) {
+  const text = String(label || "").replaceAll("\\n", " ");
+  return text.length > 28 ? `${text.slice(0, 25)}...` : text;
+}
+
 function escapeMermaid(value) {
   return String(value ?? "")
     .replaceAll("&", "&amp;")

package/templates/development/README.md

@@ -0,0 +1,52 @@
+# Development Context
+
+Context Doc Type: development-index
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Purpose
+
+This folder is the development input pack. It tells agents how to work in this repository, how to face external services during development, and what not to assume when the external repositories are unavailable.
+
+## Boundary
+
+- Put local setup, codebase map, external service development summaries, mocks, stubs, and cross-repo debugging here.
+- Put long-lived system structure in `docs/03-ARCHITECTURE/`.
+- Put concrete API/event/webhook contracts in `docs/06-INTEGRATIONS/`.
+
+## Structure Contract
+
+| File / Path | Facts to maintain | Write rule |
+| --- | --- | --- |
+| `local-setup.md` | Local startup, dependencies, environment variables, common failures | Development startup facts only; not production architecture |
+| `codebase-map.md` | Local code entry points, directory responsibilities, read order | Agents read this before editing code |
+| `external-context/<service-key>.md` | External service impact on local development, mocks/stubs, debug entry points | One external service per file |
+| `external-source-packs/` | Large external source sets, indexes, digests, and projection status | Intake layer only; not the final fact layer |
+| `stubs-and-mocks.md` | Available mock/stub strategies in this repository | Include executable paths or commands |
+| `cross-repo-debugging.md` | Cross-repo debugging sequence and evidence | Debug workflow only; not a service responsibility overview |
+
+## External Service Rule
+
+If this repository depends on multiple microservices, do not write all external knowledge into one large document. For any external service that affects local development or testing, create:
+
+- `docs/03-ARCHITECTURE/services/<service-key>.md`: what the service is and what it owns.
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`: how this repository mocks, stubs, or debugs it.
+- `docs/06-INTEGRATIONS/<contract>.md`: concrete API/event/webhook contracts.
+
+`04-DEVELOPMENT` only answers how to work with the external service during development. Do not maintain full system topology here, and do not put payload schemas here.
+
+## External Source Pack Rule
+
+If an external team provides many documents, screenshots, exported packets, meeting notes, or links, do not place them directly into `03/04/06`. Read `docs/11-REFERENCE/external-source-intake-standard.md` first, then decide whether `external-source-packs/<source-key>/` is needed.
+
+`external-source-packs/` owns source indexes, digests, and projection status only. Stable conclusions must be written back to:
+
+- `docs/03-ARCHITECTURE/services/<service-key>.md`
+- `docs/04-DEVELOPMENT/external-context/<service-key>.md`
+- `docs/06-INTEGRATIONS/<contract>.md`
+
+## External Context Index
+
+| Service Key | Why It Matters To This Repo | Local Stub / Mock | Debug Entry | Architecture Link | Contract Link | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- | --- |

package/templates/development/codebase-map.md

@@ -0,0 +1,11 @@
+# Codebase Map
+
+Context Doc Type: codebase-map
+Owner: project coordinator
+Last Verified: unknown
+Confidence: low
+
+## Entry Points
+
+| Area | Path | Responsibility | Read When | Source Evidence | Last Verified | Confidence |
+| --- | --- | --- | --- | --- | --- | --- |