okstra 0.232.0 → 0.234.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/README.md +19 -283
  2. package/dist/cli-registry.mjs +14 -1
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/execute/render-bundle.d.mts +6 -1
  5. package/dist/commands/execute/render-bundle.mjs +139 -32
  6. package/dist/commands/execute/render-bundle.mjs.map +1 -1
  7. package/dist/commands/lifecycle/config.mjs +6 -74
  8. package/dist/commands/lifecycle/config.mjs.map +1 -1
  9. package/dist/commands/trace/capacity.d.mts +12 -0
  10. package/dist/commands/trace/capacity.mjs +21 -0
  11. package/dist/commands/trace/capacity.mjs.map +1 -0
  12. package/dist/commands/trace/model.d.mts +89 -0
  13. package/dist/commands/trace/model.mjs +251 -0
  14. package/dist/commands/trace/model.mjs.map +1 -0
  15. package/dist/commands/trace/progression.d.mts +11 -0
  16. package/dist/commands/trace/progression.mjs +194 -0
  17. package/dist/commands/trace/progression.mjs.map +1 -0
  18. package/dist/commands/trace/review.d.mts +7 -0
  19. package/dist/commands/trace/review.mjs +51 -0
  20. package/dist/commands/trace/review.mjs.map +1 -0
  21. package/dist/commands/trace/task-link.d.mts +18 -0
  22. package/dist/commands/trace/task-link.mjs +72 -0
  23. package/dist/commands/trace/task-link.mjs.map +1 -0
  24. package/dist/commands/trace/trace.d.mts +1 -0
  25. package/dist/commands/trace/trace.mjs +293 -0
  26. package/dist/commands/trace/trace.mjs.map +1 -0
  27. package/dist/lib/bounded-file.d.mts +1 -0
  28. package/dist/lib/bounded-file.mjs +36 -0
  29. package/dist/lib/bounded-file.mjs.map +1 -0
  30. package/dist/lib/config-store.d.mts +34 -0
  31. package/dist/lib/config-store.mjs +70 -0
  32. package/dist/lib/config-store.mjs.map +1 -0
  33. package/dist/lib/file-lock.mjs +4 -5
  34. package/dist/lib/file-lock.mjs.map +1 -1
  35. package/dist/lib/input-limit.d.mts +4 -0
  36. package/dist/lib/input-limit.mjs +8 -0
  37. package/dist/lib/input-limit.mjs.map +1 -0
  38. package/dist/lib/memory-auto-register.mjs +2 -17
  39. package/dist/lib/memory-auto-register.mjs.map +1 -1
  40. package/dist/lib/report-language-tag.d.mts +1 -0
  41. package/dist/lib/report-language-tag.mjs +4 -0
  42. package/dist/lib/report-language-tag.mjs.map +1 -0
  43. package/dist/lib/report-language.d.mts +1 -0
  44. package/dist/lib/report-language.mjs +50 -0
  45. package/dist/lib/report-language.mjs.map +1 -0
  46. package/dist/lib/skill-catalog.mjs +3 -0
  47. package/dist/lib/skill-catalog.mjs.map +1 -1
  48. package/docs/architecture/storage-model.md +55 -5
  49. package/docs/architecture.md +10 -4
  50. package/docs/cli.md +320 -3
  51. package/docs/contributor-change-matrix.md +1 -2
  52. package/docs/project-structure-overview.md +34 -43
  53. package/package.json +1 -1
  54. package/runtime/BUILD.json +2 -2
  55. package/runtime/agents/operations/trace-interface-review.json +6 -0
  56. package/runtime/agents/operations/trace-scope-review.json +6 -0
  57. package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
  58. package/runtime/prompts/coding-preflight/clean-code.md +18 -20
  59. package/runtime/prompts/coding-preflight/overview.md +1 -1
  60. package/runtime/prompts/duties/code-reviewer.json +1 -1
  61. package/runtime/prompts/duties/interface-reviewer.json +32 -0
  62. package/runtime/prompts/host-orchestration/README.md +18 -9
  63. package/runtime/prompts/launch.template.md +3 -2
  64. package/runtime/prompts/lead/context-loader.md +2 -0
  65. package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
  66. package/runtime/prompts/lead/report-writer.md +6 -6
  67. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
  68. package/runtime/prompts/profiles/_common-contract.md +1 -1
  69. package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
  70. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
  71. package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
  72. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
  73. package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
  74. package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
  75. package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
  76. package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
  77. package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
  78. package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
  79. package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
  80. package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
  81. package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
  82. package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
  83. package/runtime/python/okstra_ctl/code_review_census.py +93 -2
  84. package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
  85. package/runtime/python/okstra_ctl/code_review_run.py +384 -0
  86. package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
  87. package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
  88. package/runtime/python/okstra_ctl/code_review_target.py +140 -15
  89. package/runtime/python/okstra_ctl/coverage_census.py +11 -2
  90. package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
  91. package/runtime/python/okstra_ctl/direct_work.py +45 -3
  92. package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
  93. package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
  94. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  95. package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
  96. package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
  97. package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
  98. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
  99. package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
  100. package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
  101. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
  102. package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
  103. package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
  104. package/runtime/python/okstra_ctl/fixed_text.py +10 -0
  105. package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
  106. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
  107. package/runtime/python/okstra_ctl/json_boundary.py +33 -6
  108. package/runtime/python/okstra_ctl/manager_cli.py +122 -1
  109. package/runtime/python/okstra_ctl/manager_journal.py +126 -0
  110. package/runtime/python/okstra_ctl/manager_launch.py +3 -3
  111. package/runtime/python/okstra_ctl/manager_log.py +221 -0
  112. package/runtime/python/okstra_ctl/manager_paths.py +8 -0
  113. package/runtime/python/okstra_ctl/manager_resume.py +59 -0
  114. package/runtime/python/okstra_ctl/manager_split.py +2 -2
  115. package/runtime/python/okstra_ctl/manager_store.py +116 -17
  116. package/runtime/python/okstra_ctl/manager_sync.py +42 -3
  117. package/runtime/python/okstra_ctl/manager_view.py +35 -2
  118. package/runtime/python/okstra_ctl/material.py +2 -0
  119. package/runtime/python/okstra_ctl/model_cli.py +64 -14
  120. package/runtime/python/okstra_ctl/model_defaults.py +22 -0
  121. package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
  122. package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
  123. package/runtime/python/okstra_ctl/path_hints.py +14 -3
  124. package/runtime/python/okstra_ctl/paths.py +6 -1
  125. package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
  126. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
  127. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
  128. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
  129. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  130. package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
  131. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
  132. package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
  133. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
  134. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
  135. package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
  136. package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
  137. package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
  138. package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
  139. package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
  140. package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
  141. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
  142. package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
  143. package/runtime/python/okstra_ctl/project_group.py +175 -0
  144. package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
  145. package/runtime/python/okstra_ctl/render.py +28 -2
  146. package/runtime/python/okstra_ctl/report_assembly.py +38 -11
  147. package/runtime/python/okstra_ctl/report_contract.py +26 -0
  148. package/runtime/python/okstra_ctl/report_corrections.py +36 -20
  149. package/runtime/python/okstra_ctl/report_inputs.py +1 -0
  150. package/runtime/python/okstra_ctl/report_language.py +4 -1
  151. package/runtime/python/okstra_ctl/report_narrative.py +179 -7
  152. package/runtime/python/okstra_ctl/report_projections.py +64 -18
  153. package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
  154. package/runtime/python/okstra_ctl/run.py +43 -35
  155. package/runtime/python/okstra_ctl/run_context.py +10 -1
  156. package/runtime/python/okstra_ctl/set_work_status.py +4 -15
  157. package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
  158. package/runtime/python/okstra_ctl/task_query.py +239 -0
  159. package/runtime/python/okstra_ctl/trace_review.py +264 -0
  160. package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
  161. package/runtime/python/okstra_ctl/user_authorization.py +14 -0
  162. package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
  163. package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
  164. package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
  165. package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
  166. package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
  167. package/runtime/python/okstra_ctl/wizard/render.py +8 -0
  168. package/runtime/python/okstra_ctl/wizard/state.py +2 -1
  169. package/runtime/python/okstra_project/state.py +20 -0
  170. package/runtime/python/okstra_token_usage/blocks.py +74 -0
  171. package/runtime/python/okstra_token_usage/cli.py +23 -10
  172. package/runtime/python/okstra_token_usage/collect.py +25 -22
  173. package/runtime/python/okstra_token_usage/policy.py +193 -0
  174. package/runtime/schemas/business-flow-v1.schema.json +3 -0
  175. package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
  176. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
  177. package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
  178. package/runtime/skills/_fragments/wizard-preflight.md +1 -1
  179. package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
  180. package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
  181. package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
  182. package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
  183. package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
  184. package/runtime/skills/okstra-code-review/SKILL.md +58 -50
  185. package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
  186. package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
  187. package/runtime/skills/okstra-discussion/SKILL.md +22 -38
  188. package/runtime/skills/okstra-explain-flow/SKILL.md +33 -4
  189. package/runtime/skills/okstra-manager/SKILL.md +24 -0
  190. package/runtime/skills/okstra-memory/SKILL.md +1 -1
  191. package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
  192. package/runtime/skills/okstra-run/SKILL.md +55 -183
  193. package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
  194. package/runtime/skills/okstra-setup/SKILL.md +3 -2
  195. package/runtime/skills/okstra-setup/references/project-config.md +2 -4
  196. package/runtime/skills/okstra-tdd/SKILL.md +187 -0
  197. package/runtime/skills/okstra-user-response/SKILL.md +4 -2
  198. package/runtime/templates/doyouknow/group-view.css +103 -0
  199. package/runtime/templates/doyouknow/group-view.js +317 -0
  200. package/runtime/templates/doyouknow/group-view.template.html +72 -0
  201. package/runtime/templates/manager/view.template.html +4 -0
  202. package/runtime/templates/report-writer-prompt-preamble.md +15 -3
  203. package/runtime/templates/trace/trace.template.md +42 -0
  204. package/runtime/validators/checks/fixtures-02.py +25 -33
  205. package/runtime/validators/validate-run.py +93 -36
@@ -0,0 +1,317 @@
1
+ "use strict";
2
+
3
+ // Inlined into the group view page by okstra_ctl.doyouknow.group_view. The selection and
4
+ // layout functions take plain data so tests-js can run them without a browser.
5
+ (function (root) {
6
+ const EDGE_KINDS = ["call", "event", "queue", "shared-data", "file", "batch"];
7
+ const STEP_FIELDS = [
8
+ ["inputs", "Inputs"], ["outputs", "Outputs"], ["rules", "Rules"], ["states", "States"],
9
+ ["failures", "Failures"], ["retries", "Retries"], ["recovery", "Recovery"],
10
+ ["before", "Before"], ["after", "After"], ["risks", "Risks"], ["sideEffects", "Side effects"],
11
+ ];
12
+
13
+ function searchText(flow) {
14
+ const parts = [flow.title, flow.question, flow.summary, ...flow.gaps, ...flow.questions];
15
+ flow.terms.forEach((row) => parts.push(row.term, row.meaning));
16
+ flow.steps.forEach((step) => {
17
+ parts.push(step.title, step.purpose);
18
+ STEP_FIELDS.forEach(([key]) => parts.push(...[].concat(step[key])));
19
+ });
20
+ flow.facts.forEach((fact) => parts.push(fact.key, fact.business, fact.value, ...fact.evidence));
21
+ flow.relationships.forEach((row) => parts.push(row.data));
22
+ return parts.join("\n").toLowerCase();
23
+ }
24
+
25
+ // Every whitespace-separated word of the query must appear; an empty projectId means any project.
26
+ // `flow.projects` is the set the collector stored for the flow, so the page never re-derives it.
27
+ function matchFlows(flows, query, projectId) {
28
+ const words = query.toLowerCase().split(/\s+/).filter(Boolean);
29
+ return flows.filter((flow) => {
30
+ if (projectId && !flow.projects.includes(projectId)) return false;
31
+ const text = searchText(flow);
32
+ return words.every((word) => text.includes(word));
33
+ });
34
+ }
35
+
36
+ function graphProjects(data) {
37
+ const ids = data.projects.map((row) => row.projectId);
38
+ data.edges.forEach((edge) => [edge.from, edge.to].forEach((id) => ids.includes(id) || ids.push(id)));
39
+ return ids;
40
+ }
41
+
42
+ function circleLayout(ids, width, height) {
43
+ const radius = Math.min(width, height) / 2 - 70;
44
+ const positions = {};
45
+ ids.forEach((id, index) => {
46
+ const angle = (2 * Math.PI * index) / Math.max(ids.length, 1) - Math.PI / 2;
47
+ positions[id] = {
48
+ x: Math.round(width / 2 + (ids.length === 1 ? 0 : radius) * Math.cos(angle)),
49
+ y: Math.round(height / 2 + (ids.length === 1 ? 0 : radius) * Math.sin(angle)),
50
+ };
51
+ });
52
+ return positions;
53
+ }
54
+
55
+ const NODE_RADIUS = 26;
56
+
57
+ function edgePath(from, to, index) {
58
+ if (from.x === to.x && from.y === to.y) {
59
+ // A relationship of a project with itself: a loop above the node, taller for each further one.
60
+ const top = from.y - NODE_RADIUS;
61
+ const rise = 46 + index * 18;
62
+ return `M ${from.x - 10} ${top} C ${from.x - 42} ${top - rise} ${from.x + 42} ${top - rise} ${from.x + 10} ${top - 6}`;
63
+ }
64
+ const dx = to.x - from.x;
65
+ const dy = to.y - from.y;
66
+ const length = Math.hypot(dx, dy);
67
+ const ux = dx / length;
68
+ const uy = dy / length;
69
+ // Parallel relationships between the same two projects bend by a different amount each.
70
+ const bend = 24 + index * 22;
71
+ const cx = (from.x + to.x) / 2 - uy * bend;
72
+ const cy = (from.y + to.y) / 2 + ux * bend;
73
+ const sx = from.x + ux * NODE_RADIUS;
74
+ const sy = from.y + uy * NODE_RADIUS;
75
+ const ex = to.x - ux * (NODE_RADIUS + 8);
76
+ const ey = to.y - uy * (NODE_RADIUS + 8);
77
+ return `M ${sx} ${sy} Q ${cx} ${cy} ${ex} ${ey}`;
78
+ }
79
+
80
+ root.GroupView = { matchFlows, graphProjects, circleLayout, edgePath };
81
+ if (typeof document === "undefined") return;
82
+
83
+ const SVG = "http://www.w3.org/2000/svg";
84
+ const data = JSON.parse(document.getElementById("group-view-data").textContent);
85
+ const members = new Map(data.projects.map((row) => [row.projectId, row]));
86
+ const flowsById = new Map(data.flows.map((flow) => [flow.id, flow]));
87
+ const state = { query: "", project: "" };
88
+
89
+ function el(tag, attributes, children) {
90
+ const node = document.createElement(tag);
91
+ Object.entries(attributes || {}).forEach(([key, value]) => {
92
+ if (key === "text") node.textContent = value;
93
+ else node.setAttribute(key, value);
94
+ });
95
+ (children || []).forEach((child) => node.appendChild(child));
96
+ return node;
97
+ }
98
+
99
+ function svg(tag, attributes) {
100
+ const node = document.createElementNS(SVG, tag);
101
+ Object.entries(attributes || {}).forEach(([key, value]) => node.setAttribute(key, value));
102
+ return node;
103
+ }
104
+
105
+ function setVisible(id, visible) {
106
+ document.getElementById(id).hidden = !visible;
107
+ }
108
+
109
+ function selectProject(projectId) {
110
+ state.project = state.project === projectId ? "" : projectId;
111
+ document.getElementById("project-filter").value = state.project;
112
+ renderGraphSelection();
113
+ renderFlows();
114
+ }
115
+
116
+ function openFlow(flowId) {
117
+ state.query = "";
118
+ state.project = "";
119
+ document.getElementById("search").value = "";
120
+ document.getElementById("project-filter").value = "";
121
+ renderGraphSelection();
122
+ renderFlows();
123
+ const target = document.getElementById("flow-" + flowId);
124
+ target.open = true;
125
+ target.scrollIntoView({ block: "start" });
126
+ }
127
+
128
+ function renderHeader() {
129
+ document.getElementById("title").textContent = "Project group · " + data.projectGroup;
130
+ document.getElementById("meta").textContent =
131
+ `Generated ${data.generatedAt} · ${data.projects.length} projects · ${data.flows.length} flows · ${data.edges.length} relationships`;
132
+ const problems = document.getElementById("problems");
133
+ data.problems.forEach((text) => problems.appendChild(el("li", { text })));
134
+ setVisible("problems-section", data.problems.length > 0);
135
+ }
136
+
137
+ function renderGraph() {
138
+ const ids = graphProjects(data);
139
+ const width = 960;
140
+ const height = Math.max(360, Math.min(720, 200 + ids.length * 40));
141
+ const positions = circleLayout(ids, width, height);
142
+ const graph = document.getElementById("graph");
143
+ graph.setAttribute("viewBox", `0 0 ${width} ${height}`);
144
+ const defs = svg("defs");
145
+ const marker = svg("marker", { id: "arrow", viewBox: "0 0 10 10", refX: "9", refY: "5", markerWidth: "7", markerHeight: "7", orient: "auto-start-reverse" });
146
+ marker.appendChild(svg("path", { d: "M 0 0 L 10 5 L 0 10 z", fill: "context-stroke" }));
147
+ defs.appendChild(marker);
148
+ graph.appendChild(defs);
149
+
150
+ const drawn = {};
151
+ data.edges.forEach((edge) => {
152
+ const pair = [edge.from, edge.to].sort().join("\n");
153
+ drawn[pair] = (drawn[pair] || 0) + 1;
154
+ const path = svg("path", {
155
+ class: `edge ${edge.kind} ${edge.standing}`,
156
+ d: edgePath(positions[edge.from], positions[edge.to], drawn[pair] - 1),
157
+ "marker-end": "url(#arrow)",
158
+ "data-from": edge.from,
159
+ "data-to": edge.to,
160
+ });
161
+ const title = svg("title");
162
+ title.textContent = `${edge.from} → ${edge.to} · ${edge.kind} · ${edge.reason} · ${flowsById.get(edge.flowId).title}`;
163
+ path.appendChild(title);
164
+ path.addEventListener("click", () => openFlow(edge.flowId));
165
+ graph.appendChild(path);
166
+ });
167
+
168
+ ids.forEach((id) => {
169
+ const member = members.get(id);
170
+ const group = svg("g", {
171
+ class: "node" + (member ? (member.investigated ? "" : " uninvestigated") : " outside"),
172
+ "data-project": id,
173
+ transform: `translate(${positions[id].x} ${positions[id].y})`,
174
+ });
175
+ group.appendChild(svg("circle", { r: String(NODE_RADIUS) }));
176
+ const label = svg("text", { y: String(NODE_RADIUS + 16) });
177
+ label.textContent = id;
178
+ group.appendChild(label);
179
+ group.addEventListener("click", () => selectProject(id));
180
+ graph.appendChild(group);
181
+ });
182
+
183
+ const legend = document.getElementById("legend");
184
+ EDGE_KINDS.filter((kind) => data.edges.some((edge) => edge.kind === kind))
185
+ .forEach((kind) => legend.appendChild(el("li", { class: kind, text: kind })));
186
+ setVisible("graph-empty", data.edges.length === 0);
187
+ }
188
+
189
+ function renderGraphSelection() {
190
+ document.querySelectorAll("#graph .node").forEach((node) => {
191
+ node.classList.toggle("selected", node.getAttribute("data-project") === state.project);
192
+ });
193
+ document.querySelectorAll("#graph .edge").forEach((edge) => {
194
+ const touches = [edge.getAttribute("data-from"), edge.getAttribute("data-to")].includes(state.project);
195
+ edge.classList.toggle("dimmed", Boolean(state.project) && !touches);
196
+ });
197
+ }
198
+
199
+ function fieldList(step) {
200
+ const list = el("dl", { class: "fields" });
201
+ STEP_FIELDS.forEach(([key, label]) => {
202
+ const values = [].concat(step[key]).filter(Boolean);
203
+ if (values.length === 0) return;
204
+ list.appendChild(el("dt", { text: label }));
205
+ list.appendChild(el("dd", { text: values.join(" · ") }));
206
+ });
207
+ return list;
208
+ }
209
+
210
+ function flowBody(flow) {
211
+ const body = el("div", { class: "body" });
212
+ body.appendChild(el("p", { text: flow.summary }));
213
+ body.appendChild(el("p", { class: "meta", text: `Question: ${flow.question} · stored by ${flow.owner} · ${flow.updatedAt}` }));
214
+ body.appendChild(el("p", { class: "meta" }, [el("code", { text: flow.locator })]));
215
+
216
+ body.appendChild(el("h3", { text: "Steps" }));
217
+ body.appendChild(el("ol", { class: "steps" }, flow.steps.map((step) => el("li", {}, [
218
+ el("div", { class: "step-title", text: step.title }),
219
+ el("div", { text: step.purpose }),
220
+ el("div", { class: "meta", text: "Projects: " + step.projectIds.join(", ") }),
221
+ fieldList(step),
222
+ ]))));
223
+
224
+ if (flow.relationships.length) {
225
+ body.appendChild(el("h3", { text: "Relationships between projects" }));
226
+ body.appendChild(el("ul", { class: "plain" }, flow.relationships.map((row) => el("li", {
227
+ text: `${row.from} → ${row.to} · ${row.kind} · ${row.data}`,
228
+ }))));
229
+ }
230
+
231
+ if (flow.terms.length) {
232
+ body.appendChild(el("h3", { text: "Terms" }));
233
+ const terms = el("dl", { class: "terms" });
234
+ flow.terms.forEach((row) => {
235
+ terms.appendChild(el("dt", { text: row.term }));
236
+ terms.appendChild(el("dd", { text: row.meaning }));
237
+ });
238
+ body.appendChild(terms);
239
+ }
240
+
241
+ if (flow.facts.length) {
242
+ body.appendChild(el("h3", { text: "Facts and where they were read" }));
243
+ body.appendChild(el("ul", { class: "facts" }, flow.facts.map((fact) => el("li", {}, [
244
+ el("span", { text: `${fact.value} ` }),
245
+ el("span", { class: "meta", text: `(${fact.level}) ` }),
246
+ el("code", { text: fact.key }),
247
+ el("div", {}, fact.evidence.map((ref) => el("code", { text: ref + " " }))),
248
+ ]))));
249
+ }
250
+
251
+ [["Unverified segments", flow.gaps], ["Open questions", flow.questions]].forEach(([heading, rows]) => {
252
+ if (rows.length === 0) return;
253
+ body.appendChild(el("h3", { text: heading }));
254
+ body.appendChild(el("ul", { class: "plain" }, rows.map((text) => el("li", { text }))));
255
+ });
256
+ return body;
257
+ }
258
+
259
+ function renderFlows() {
260
+ const matched = matchFlows(data.flows, state.query, state.project);
261
+ const container = document.getElementById("flows");
262
+ container.replaceChildren(...matched.map((flow) => el("details", { class: "flow", id: "flow-" + flow.id }, [
263
+ el("summary", {}, [
264
+ el("span", { class: "name", text: flow.title }),
265
+ el("span", { class: "chip " + flow.freshness, text: flow.freshness }),
266
+ el("span", { class: "chip " + flow.status, text: flow.status }),
267
+ el("span", { class: "meta", text: flow.projects.join(", ") }),
268
+ ]),
269
+ flowBody(flow),
270
+ ])));
271
+ document.getElementById("flow-count").textContent = `${matched.length} of ${data.flows.length}`;
272
+ setVisible("flows-empty", matched.length === 0);
273
+ }
274
+
275
+ function renderFilters() {
276
+ const select = document.getElementById("project-filter");
277
+ select.appendChild(el("option", { value: "", text: "All projects" }));
278
+ graphProjects(data).forEach((id) => select.appendChild(el("option", { value: id, text: id })));
279
+ select.addEventListener("change", () => {
280
+ state.project = select.value;
281
+ renderGraphSelection();
282
+ renderFlows();
283
+ });
284
+ document.getElementById("search").addEventListener("input", (event) => {
285
+ state.query = event.target.value;
286
+ renderFlows();
287
+ });
288
+ }
289
+
290
+ function renderCoverage() {
291
+ const body = document.getElementById("coverage");
292
+ data.projects.forEach((row) => body.appendChild(el("tr", {}, [
293
+ el("td", {}, [el("code", { text: row.projectId })]),
294
+ el("td", { text: row.investigated ? "yes" : "no" }),
295
+ el("td", { text: String(row.flowCount) }),
296
+ el("td", {}, [el("code", { text: row.projectRoot + (row.rootExists ? "" : " (missing)") })]),
297
+ ])));
298
+ }
299
+
300
+ function renderRecords() {
301
+ const body = document.getElementById("records");
302
+ data.records.forEach((row) => body.appendChild(el("tr", {}, [
303
+ el("td", { text: row.kind }),
304
+ el("td", {}, [el("div", { text: row.title }), el("code", { text: row.locator })]),
305
+ el("td", { text: row.projects.join(", ") }),
306
+ el("td", { text: row.updatedAt || "-" }),
307
+ ])));
308
+ setVisible("records-empty", data.records.length === 0);
309
+ }
310
+
311
+ renderHeader();
312
+ renderGraph();
313
+ renderFilters();
314
+ renderFlows();
315
+ renderCoverage();
316
+ renderRecords();
317
+ })(typeof globalThis !== "undefined" ? globalThis : this);
@@ -0,0 +1,72 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <title>{{TITLE}}</title>
7
+ <style>
8
+ {{STYLE}}
9
+ </style>
10
+ </head>
11
+ <body>
12
+ <main>
13
+ <header>
14
+ <h1 id="title"></h1>
15
+ <p class="meta" id="meta"></p>
16
+ </header>
17
+
18
+ <section id="problems-section" hidden>
19
+ <h2>Collection problems</h2>
20
+ <ul id="problems" class="plain"></ul>
21
+ </section>
22
+
23
+ <section>
24
+ <h2>Project relationships</h2>
25
+ <p class="hint">Select a project to list the flows that cover it. A dashed line is a relationship whose facts are not all confirmed from source.</p>
26
+ <div class="panel graph">
27
+ <svg id="graph" role="img" aria-label="Relationships between the projects of this group"></svg>
28
+ <ul id="legend" class="legend"></ul>
29
+ </div>
30
+ <p class="empty" id="graph-empty" hidden>No project relationship has been explained yet.</p>
31
+ </section>
32
+
33
+ <section>
34
+ <h2>Business flows</h2>
35
+ <div class="filters">
36
+ <label>Search <input id="search" type="search" placeholder="term, rule, state, fact, file" autocomplete="off"></label>
37
+ <label>Project <select id="project-filter"></select></label>
38
+ <span class="meta" id="flow-count"></span>
39
+ </div>
40
+ <div id="flows"></div>
41
+ <p class="empty" id="flows-empty" hidden>No flow matches.</p>
42
+ </section>
43
+
44
+ <section>
45
+ <h2>Coverage</h2>
46
+ <p class="hint">A project is investigated when at least one flow of this group inspected it. An uninvestigated project is not known to be unrelated.</p>
47
+ <div class="panel scroll">
48
+ <table>
49
+ <thead><tr><th>Project</th><th>Investigated</th><th>Own flows</th><th>Root</th></tr></thead>
50
+ <tbody id="coverage"></tbody>
51
+ </table>
52
+ </div>
53
+ </section>
54
+
55
+ <section>
56
+ <h2>Linked records</h2>
57
+ <p class="hint">Memory entries, manager tasks and project tasks that name a project of this group.</p>
58
+ <div class="panel scroll">
59
+ <table>
60
+ <thead><tr><th>Kind</th><th>Record</th><th>Projects</th><th>Updated</th></tr></thead>
61
+ <tbody id="records"></tbody>
62
+ </table>
63
+ </div>
64
+ <p class="empty" id="records-empty" hidden>No linked record.</p>
65
+ </section>
66
+ </main>
67
+ <script id="group-view-data" type="application/json">{{DATA}}</script>
68
+ <script>
69
+ {{SCRIPT}}
70
+ </script>
71
+ </body>
72
+ </html>
@@ -120,6 +120,10 @@ a { color: var(--running); }
120
120
  {{SUMMARY}}
121
121
  </section>
122
122
  <section>
123
+ <h2>Manager activity</h2>
124
+ {{ACTIVITY}}
125
+ </section>
126
+ <section>
123
127
  <h2>Projects</h2>
124
128
  {{PROJECTS}}
125
129
  </section>
@@ -4,11 +4,11 @@ This file is the audience-specific contract for `report-writer`. Read it and the
4
4
 
5
5
  ## Output ownership
6
6
 
7
- Write only the report narrative Markdown at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`.
7
+ Write only the report authoring input at `**Result Path:**`, the pointer record at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`.
8
8
 
9
9
  A correction-only prompt may additionally name a replacements JSON output. In that mode, the supplied `apply-corrections` command owns the narrative update.
10
10
 
11
- The report narrative Markdown contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
11
+ The report authoring input contains the task judgment, plan, summaries, and user explanation. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
12
12
 
13
13
  The following fields belong to other owners and must not appear in the narrative: `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, and `planBodyVerification`.
14
14
 
@@ -22,6 +22,16 @@ Write the audit sidecar before synthesis with one `- PROGRESS: <stage> <ISO-8601
22
22
 
23
23
  ## Narrative format
24
24
 
25
+ Use the format declared by the synthesis packet's Authoring Contract, selected from this run's `reportAuthoringFormat`. `json-v1` uses standard JSON; a manifest without the field retains `markdown-v1` and the packet's legacy `report-narrative-v3.0` format. Do not infer the format from the filename or convert an existing run to a different format. `reportNarrativePath` retains its name and means the writer's authoring input path; assembly derives the reader's Markdown and HTML from the final record.
26
+
27
+ ### JSON authoring (`json-v1`)
28
+
29
+ Write one standard JSON object with exact schema keys, native arrays, objects, numbers, booleans and `null`. Do not add a heading, preamble, Markdown fence, duplicate keys, or non-standard numeric values. Description strings may contain ordinary Markdown, including newlines, tables and code blocks. Use the packet's exact required and allowed top-level JSON keys and its writer-owned schema excerpt for nested fields. Do not translate keys into Title Case, use `- Item N` or `> value` lines, or encode empty values as `_none_`.
30
+
31
+ Write prose strings directly in the language named by `**Report Language:**`. A host, project or global instruction file (`CLAUDE.md`, `AGENTS.md`) does not change that language for report artifacts. Schema keys, enum and status values, finding and requirement ids, paths, symbols, commands, and model names keep their schema and source spelling. Only writer-owned fields belong in this object; standard JSON does not grant ownership of the assembled report or another role's input.
32
+
33
+ ### Legacy Markdown authoring (`markdown-v1`)
34
+
25
35
  The narrative is not free-form Markdown. A narrative file is the line `# OKSTRA Report Narrative`, then lines of exactly three shapes and nothing else:
26
36
 
27
37
  - `- **Humanised Field Name**` — one field. Nest a child field by indenting two more spaces.
@@ -32,7 +42,7 @@ Blank lines are ignored. **Every other line is rejected**, including Markdown he
32
42
 
33
43
  Follow the task-specific schema order. Write every `> ` prose value directly in the language named by `**Report Language:**`; do not draft in English first, because no translation step follows. A host, project or global instruction file (`CLAUDE.md`, `AGENTS.md`) does not change that language for report artifacts. Field names, `Verdict Token` and other enum or status values, finding and requirement ids, paths, symbols, commands, and model names stay exactly as the schema and sources spell them.
34
44
 
35
- ### Top-level fields you may author
45
+ ### Legacy top-level field labels
36
46
 
37
47
  These are the only names allowed at the top level:
38
48
 
@@ -42,6 +52,8 @@ The synthesis packet's Authoring Contract names which of these are **required**
42
52
 
43
53
  Any other top-level name is rejected however reasonable it reads — a section title copied out of a lead procedure document (`Clarification Response Carried In`, `Stage Map`, `Rollback Strategy`) is a heading in that document, not a top-level field here. Nested names come from the task's block in `schemas/final-report-v3.0.schema.json`; when a name is refused, the parser's message lists the names allowed at that exact position, so correct against that list rather than guessing a second time.
44
54
 
55
+ ## Task-specific content rules (both formats)
56
+
45
57
  **Implementation-planning direction branch.** A selected-direction narrative carries `selectedDirectionRef` and `directionRealization`; the `P-Dir-1` verifier checks that realization against the selected core mechanism, architecture boundaries, planning invariants, and any hidden direction change. A legacy candidate-comparison narrative retains `P-Opt-*` option comparison semantics. These are plan-body judgments, not frontmatter fields owned by the writer. Four `directionRealization` fields — `coreMechanism`, `architectureBoundaries`, `planningInvariants`, `userConstraints` — are verbatim copies of the selected-direction snapshot and report assembly overwrites them from that snapshot at publication: do not paraphrase them; spend the writing on the fields the writer actually owns (`fileStructure` and the other realization fields).
46
58
 
47
59
  **Implementation-option-selection comparison.** Candidate details remain direction-level and must not claim planning precision:
@@ -0,0 +1,42 @@
1
+ # Implementation Trace: {{slug}}
2
+
3
+ {{guidance}}
4
+
5
+ ## analysis
6
+
7
+ | Requirement | {{description}} | {{source}} |
8
+ |---|---|---|
9
+
10
+ | Key | Value |
11
+ |---|---|
12
+ | language | |
13
+ | unitTestCommand | |
14
+ | integrationTestCommand | |
15
+ | typecheckCommand | |
16
+
17
+ ## analysis-review
18
+
19
+ ## spec
20
+
21
+ | Spec item | Requirement | {{content}} |
22
+ |---|---|---|
23
+
24
+ ## spec-review
25
+
26
+ ## interface-design
27
+
28
+ | Use case | Requirement | {{description}} |
29
+ |---|---|---|
30
+
31
+ ## interface-review
32
+
33
+ ## interface-code
34
+
35
+ ## tests-red
36
+
37
+ | Test | Use case | Requirement | Kind | Path |
38
+ |---|---|---|---|---|
39
+
40
+ ## implementation
41
+
42
+ ## integration
@@ -2,16 +2,19 @@
2
2
 
3
3
  호출부: validators/lib/fixtures.sh:110
4
4
  규칙 R1 은 실행될 소스를 문자열/heredoc 이 아니라 실파일에 두게 한다.
5
- 이 파일의 내용은 꺼내기 전과 같다 — 옮기기만 했다.
6
5
  """
7
6
  from datetime import datetime, timezone
8
7
  from pathlib import Path
9
8
  import json
9
+ import os
10
10
  import sys
11
11
 
12
12
  project_root = Path(sys.argv[1])
13
13
  task_manifest_path = project_root / sys.argv[2]
14
14
  omitted_worker_id = sys.argv[3]
15
+ WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
16
+ if WORKSPACE_ROOT:
17
+ sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
15
18
 
16
19
 
17
20
  def load_json(path: Path) -> dict:
@@ -177,36 +180,27 @@ team_state["teamCreate"] = {
177
180
  "status": "implicit",
178
181
  }
179
182
 
180
- # Phase 7 token-usage collection is normally produced by okstra-token-usage.py.
181
- # The validator (`team-state.usageSummary is empty`) treats absence as a contract
182
- # violation, so the fixture must mirror that step with a synthetic-but-valid object.
183
- team_state["usageSummary"] = {
184
- "leadTotalTokens": 0,
185
- "workerTotalTokens": 0,
186
- "grandTotalTokens": 0,
187
- "leadBillableEquivalentTokens": 0,
188
- "workerBillableEquivalentTokens": 0,
189
- "grandBillableEquivalentTokens": 0,
190
- "estimatedCostUsd": {
191
- "lead": 0.0,
192
- "claudeWorkers": 0.0,
193
- "cliWorkers": 0.0,
194
- "grandTotal": 0.0,
195
- },
196
- "collectedAt": "1970-01-01T00:00:00Z",
197
- "teamName": team_state.get("teamName", "validation-fixture"),
198
- "sessionsFound": 0,
199
- "definitions": {
200
- "totalTokens": "Validation fixture placeholder.",
201
- "billableEquivalentTokens": "Validation fixture placeholder.",
202
- "estimatedCostUsd": "Validation fixture placeholder.",
203
- },
204
- "intake": {
205
- "totalTokens": 0,
206
- "billableEquivalentTokens": 0,
207
- "estimatedCostUsd": 0,
208
- },
209
- }
183
+ # This hermetic fixture contains no provider usage records. Record that
184
+ # observation for each participant, then use the collector's summary builder.
185
+ # A timestamped summary alone cannot establish source attribution or absence.
186
+ from okstra_token_usage.blocks import na_block
187
+ from okstra_token_usage.collect import _populate_usage_summary
188
+
189
+ team_state["leadUsage"] = na_block(
190
+ "The validation fixture contains no provider usage records for the lead."
191
+ )
192
+ for worker in team_state.get("workers", []):
193
+ if isinstance(worker, dict):
194
+ worker["usage"] = na_block(
195
+ "The validation fixture contains no provider usage records for "
196
+ f"{worker.get('role') or worker.get('workerId') or 'this worker'}."
197
+ )
198
+ _populate_usage_summary(
199
+ team_state,
200
+ team_name=team_state.get("teamName", "validation-fixture"),
201
+ sessions_found=0,
202
+ needle_source="validation-fixture",
203
+ )
210
204
 
211
205
  required_status_entries = run_manifest.get("teamContract", {}).get(
212
206
  "requiredAgentStatusEntries", []
@@ -284,8 +278,6 @@ md_path.write_text("\n".join(report_lines) + "\n")
284
278
  # The workflow validator's fixture predates that step; we materialise
285
279
  # the html file in-place using the same single-reference-point helper
286
280
  # the CLI uses.
287
- import os
288
- WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
289
281
  if WORKSPACE_ROOT:
290
282
  # Write final-report .data.json SSOT next to the markdown. The validator's
291
283
  # validate_final_report_data() reads this via _data_path_for(report_path)