okstra 0.233.0 → 0.234.1

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 (36) hide show
  1. package/dist/cli-registry.mjs +6 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/trace/progression.mjs +6 -5
  4. package/dist/commands/trace/progression.mjs.map +1 -1
  5. package/dist/commands/trace/trace.mjs +2 -2
  6. package/dist/commands/trace/trace.mjs.map +1 -1
  7. package/docs/architecture/storage-model.md +19 -0
  8. package/docs/cli.md +41 -1
  9. package/docs/project-structure-overview.md +3 -2
  10. package/package.json +1 -1
  11. package/runtime/BUILD.json +2 -2
  12. package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
  13. package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
  14. package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
  15. package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
  16. package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
  17. package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
  18. package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
  19. package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
  20. package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
  21. package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
  22. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
  23. package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
  24. package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
  25. package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
  26. package/runtime/python/okstra_ctl/fixed_text.py +10 -0
  27. package/runtime/python/okstra_ctl/project_group.py +175 -0
  28. package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
  29. package/runtime/schemas/business-flow-v1.schema.json +3 -0
  30. package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
  31. package/runtime/skills/okstra-brief-gen/SKILL.md +52 -6
  32. package/runtime/skills/okstra-explain-flow/SKILL.md +27 -2
  33. package/runtime/skills/okstra-tdd/SKILL.md +7 -4
  34. package/runtime/templates/doyouknow/group-view.css +103 -0
  35. package/runtime/templates/doyouknow/group-view.js +317 -0
  36. package/runtime/templates/doyouknow/group-view.template.html +72 -0
@@ -3,14 +3,15 @@ from __future__ import annotations
3
3
  import json
4
4
  from dataclasses import asdict, dataclass, field
5
5
  from pathlib import Path
6
- from typing import Literal
6
+ from typing import Literal, get_args
7
7
 
8
8
  from ..json_boundary import serialize_owned_object
9
9
  from .contracts import (DoyouknowError, MAX_INPUT_BYTES, Node, Relation, _check_input_depth,
10
10
  _decoded_strings, asset_object, canonical_json, record_secret_policy_digest, reject_secrets)
11
11
  from .identity import stable_id
12
12
 
13
- SourceKind = Literal["memory", "manager", "task"]
13
+ SourceKind = Literal["memory", "manager", "task", "business"]
14
+ SOURCE_KINDS = get_args(SourceKind)
14
15
  Lifecycle = Literal["active", "archived", "unlinked", "missing"]
15
16
  JsonValue = str | int | float | bool | None | list["JsonValue"] | dict[str, "JsonValue"]
16
17
 
@@ -99,7 +100,7 @@ def snapshot_payload(snapshot: SourceSnapshot) -> dict:
99
100
 
100
101
 
101
102
  def _require_snapshot_fields(snapshot: SourceSnapshot) -> None:
102
- if snapshot.ref.kind not in ("memory", "manager", "task") or snapshot.lifecycle not in ("active", "archived", "unlinked", "missing"):
103
+ if snapshot.ref.kind not in SOURCE_KINDS or snapshot.lifecycle not in ("active", "archived", "unlinked", "missing"):
103
104
  raise DoyouknowError("invalid source kind or lifecycle")
104
105
  for value in (snapshot.ref.owner_id, snapshot.ref.native_id, snapshot.locator):
105
106
  if not isinstance(value, str) or not value.strip():
@@ -8,7 +8,7 @@ from pathlib import Path
8
8
 
9
9
  from .contracts import DoyouknowError, MAX_INPUT_BYTES, canonical_json
10
10
  from .identity import node_id, source_id, stable_id
11
- from .source_contracts import SourceRef, SourceScan, SourceSnapshot, snapshot_payload, validate_source_value
11
+ from .source_contracts import SOURCE_KINDS, SourceRef, SourceScan, SourceSnapshot, snapshot_payload, validate_source_value
12
12
  from .store import SCHEMA_VERSION, SQLITE_TIMEOUT_SECONDS, _digest, _insert_node, _require_database_location, database_path, write_connection
13
13
 
14
14
  SOURCE_SCHEMA_STATEMENTS = (
@@ -61,7 +61,7 @@ def _validated_scan(scan: SourceScan) -> tuple[list[dict], list[SourceRef]]:
61
61
  raise DoyouknowError("invalid source scan status")
62
62
  if scan.status == "complete" and scan.errors:
63
63
  raise DoyouknowError("a complete source scan cannot contain errors")
64
- if scan.domain.kind not in ("memory", "manager", "task") or not scan.domain.owner_id.strip():
64
+ if scan.domain.kind not in SOURCE_KINDS or not scan.domain.owner_id.strip():
65
65
  raise DoyouknowError("invalid source scan domain")
66
66
  if any((ref.kind, ref.owner_id) != (scan.domain.kind, scan.domain.owner_id) for ref in refs):
67
67
  raise DoyouknowError("source scan contains a different domain")
@@ -0,0 +1,116 @@
1
+ from __future__ import annotations
2
+
3
+ from pathlib import Path
4
+ from typing import cast
5
+
6
+ from okstra_project.dirs import PROJECT_JSON_RELATIVE
7
+
8
+ from ...business_flow.contracts import BusinessFact, BusinessFlowError, BusinessResult, FlowExecution, business_root, schema_definition
9
+ from ...business_flow.history import flow_id, latest_explanations, recorded_source_states
10
+ from ...business_flow.store import CONFIRMED_LEVELS
11
+ from ...json_boundary import JsonBoundaryError, load_owned_object
12
+ from ..config import SourceConfig, includes_project
13
+ from ..contracts import MAX_INPUT_BYTES, DoyouknowError, Node, Relation
14
+ from ..source_contracts import SourceDomain, SourceRef, SourceScan, SourceSnapshot, snapshot_payload
15
+ from .io import read_source_object, safe_source_path
16
+
17
+ _UNREADABLE = (DoyouknowError, BusinessFlowError, JsonBoundaryError, OSError, RecursionError)
18
+
19
+
20
+ def _evidence_refs(fact: BusinessFact) -> list[str]:
21
+ return [f"{row['projectId']}:{row['path']}:{row['line']}" for row in fact["evidence"]]
22
+
23
+
24
+ def _project_node(project_id: str) -> Node:
25
+ return {"kind": "project", "scope": "okstra-project", "key": project_id, "title": project_id, "ref": "project:" + project_id}
26
+
27
+
28
+ def _graph(project_id: str, result: BusinessResult, locator: str) -> tuple[list[Node], list[Relation]]:
29
+ facts = {fact["key"]: fact for fact in result["facts"]}
30
+ involved = {project_id, *result["inspectedProjects"]}
31
+ for step in result["steps"]:
32
+ involved.update(step["projectIds"])
33
+ for row in result["relationships"]:
34
+ involved.update((row["from"], row["to"]))
35
+ nodes = [_project_node(name) for name in sorted(involved)]
36
+ relations: list[Relation] = [
37
+ {
38
+ "from": "$source", "to": "project:" + name,
39
+ "kind": "belongs-to" if name == project_id else "involves",
40
+ "reason": "The project stores this explanation." if name == project_id else "The explanation covers this project.",
41
+ "evidence": [locator], "standing": "observed",
42
+ }
43
+ for name in sorted(involved)
44
+ ]
45
+ # The explanation schema allows a blank term or meaning; a graph node and its relation do not.
46
+ terms = {row["term"].casefold(): row for row in result["terms"] if row["term"].strip() and row["meaning"].strip()}
47
+ for index, (key, row) in enumerate(sorted(terms.items())):
48
+ ref = f"term:{index}"
49
+ nodes.append({"kind": "concept", "scope": project_id, "key": key, "title": row["term"], "ref": ref})
50
+ relations.append({"from": "$source", "to": ref, "kind": "defines", "reason": row["meaning"], "evidence": [locator], "standing": "observed"})
51
+ for row in result["relationships"]:
52
+ linked = [facts[key] for key in row["factKeys"] if key in facts]
53
+ relations.append({
54
+ "from": "project:" + row["from"], "to": "project:" + row["to"], "kind": row["kind"],
55
+ "reason": row["data"],
56
+ "evidence": [ref for fact in linked for ref in _evidence_refs(fact)] or [locator],
57
+ "standing": "observed" if linked and all(fact["level"] in CONFIRMED_LEVELS for fact in linked) else "candidate",
58
+ })
59
+ return nodes, relations
60
+
61
+
62
+ def _snapshot(project_id: str, locator: str, execution: FlowExecution, settings: SourceConfig) -> SourceSnapshot:
63
+ result, request = execution["result"], execution["request"]
64
+ nodes, relations = _graph(project_id, result, locator)
65
+ metadata = {
66
+ "projectId": project_id, "executionId": execution["id"], "question": request["question"], "mode": request["mode"],
67
+ "status": execution["status"], "summary": result["summary"],
68
+ "terms": result["terms"], "steps": result["steps"], "relationships": result["relationships"],
69
+ # Excerpts are source text; the graph keeps where each fact was read, not the text.
70
+ "facts": [{**{key: fact[key] for key in ("key", "business", "value", "level")}, "evidence": _evidence_refs(fact)} for fact in result["facts"]],
71
+ "inspectedProjects": result["inspectedProjects"], "gaps": result["gaps"], "questions": result["questions"],
72
+ "sourceStates": recorded_source_states(execution),
73
+ }
74
+ native_id = flow_id(request["question"])
75
+ snapshot = SourceSnapshot(
76
+ ref=SourceRef("business", project_id, native_id),
77
+ primary_node={"kind": "flow", "scope": project_id, "key": native_id, "ref": "primary", "title": result["title"]},
78
+ locator=locator, metadata=metadata, nodes=tuple(nodes), relations=tuple(relations),
79
+ source_updated_at=execution["createdAt"], scope=settings["scope"],
80
+ )
81
+ snapshot_payload(snapshot)
82
+ return snapshot
83
+
84
+
85
+ def _latest_explanations(project_root: Path) -> tuple[dict[str, tuple[Path, FlowExecution]], int]:
86
+ """The owner's selection, read with this store's containment and size limits."""
87
+ safe_source_path(project_root, business_root(project_root) / "executions")
88
+
89
+ def read(path: Path) -> FlowExecution:
90
+ return cast(FlowExecution, load_owned_object(
91
+ safe_source_path(project_root, path), artifact="business flow execution",
92
+ schema=schema_definition("execution"), max_bytes=MAX_INPUT_BYTES,
93
+ ))
94
+
95
+ return latest_explanations(project_root, read=read, unreadable=(DoyouknowError,))
96
+
97
+
98
+ def scan_business_flows(project_root: Path, project_id: str, settings: SourceConfig) -> SourceScan:
99
+ domain = SourceDomain("business", project_id)
100
+ if "business" not in settings["sources"] or not includes_project(settings, project_id):
101
+ return SourceScan(domain, (), (), "partial")
102
+ try:
103
+ if read_source_object(project_root, PROJECT_JSON_RELATIVE).get("projectId") != project_id:
104
+ raise DoyouknowError("registered project identity does not match its source")
105
+ latest, unreadable = _latest_explanations(project_root)
106
+ except _UNREADABLE:
107
+ return SourceScan(domain, (), (), "unavailable", ("project-source-unavailable",))
108
+ snapshots, observed = [], []
109
+ errors = ["business-source-unavailable"] * unreadable
110
+ for native_id, (locator, execution) in sorted(latest.items()):
111
+ observed.append(SourceRef("business", project_id, native_id))
112
+ try:
113
+ snapshots.append(_snapshot(project_id, str(locator), execution, settings))
114
+ except _UNREADABLE:
115
+ errors.append("business-source-unavailable")
116
+ return SourceScan(domain, tuple(snapshots), tuple(observed), "partial" if errors else "complete", tuple(errors))
@@ -1,16 +1,18 @@
1
1
  from __future__ import annotations
2
2
 
3
- from collections.abc import Iterator
3
+ from collections.abc import Callable, Iterator
4
4
  from functools import partial
5
5
  from pathlib import Path
6
6
 
7
7
  from ..json_boundary import JsonBoundaryError
8
+ from ..project_group import group_project_roots
8
9
  from .config import SourceConfig, load_config
9
10
  from .contracts import DoyouknowError
10
11
  from .identity import stable_id
11
12
  from .registration import retry_pending, validate_source_and_update_refusal_cache
12
13
  from .source_contracts import SourceDomain, SourceKind, SourceScan
13
14
  from .source_store import apply_source_scan
15
+ from .sources.business import scan_business_flows
14
16
  from .sources.manager import scan_managers
15
17
  from .sources.memory import scan_memory_sources
16
18
  from .sources.task import scan_project_tasks
@@ -26,14 +28,37 @@ def _source_scans(home: Path, settings: SourceConfig) -> Iterator[SourceScan]:
26
28
  managers, projects = scan_managers(home, settings, gate=gate)
27
29
  yield from managers
28
30
  if "task" in enabled:
29
- registry_unavailable = any(scan.status == "unavailable" for scan in managers)
30
- for project_id, roots in sorted(projects.items()):
31
- if registry_unavailable:
32
- yield SourceScan(SourceDomain("task", project_id), (), (), "unavailable", ("project-registry-incomplete",))
33
- elif len(roots) != 1:
34
- yield SourceScan(SourceDomain("task", project_id), (), (), "unavailable", ("conflicting-project-roots",))
35
- else:
36
- yield scan_project_tasks(roots[0], project_id, settings)
31
+ incomplete = "project-registry-incomplete" if any(scan.status == "unavailable" for scan in managers) else None
32
+ yield from _project_scans("task", projects, incomplete, partial(_scan_with, scan_project_tasks, settings))
33
+ if "business" in enabled:
34
+ projects, registry_errors = group_project_roots(home)
35
+ incomplete = "project-group-registry-incomplete" if registry_errors else None
36
+ if incomplete:
37
+ # Reported on its own domain as well: with no readable group there is no project to carry it.
38
+ yield SourceScan(SourceDomain("business", "project-group-registry"), (), (), "unavailable", (incomplete,))
39
+ yield from _project_scans("business", projects, incomplete, partial(_scan_with, scan_business_flows, settings))
40
+
41
+
42
+ def _scan_with(scan: Callable[[Path, str, SourceConfig], SourceScan], settings: SourceConfig, root: Path, project_id: str) -> SourceScan:
43
+ return scan(root, project_id, settings)
44
+
45
+
46
+ def _project_scans(
47
+ kind: SourceKind, projects: dict[str, tuple[Path, ...]], incomplete: str | None, scan: Callable[[Path, str], SourceScan],
48
+ ) -> Iterator[SourceScan]:
49
+ """Scan each project under its one registered root.
50
+
51
+ A complete scan marks sources it did not see as missing, and one root is only known
52
+ to be the only root when the whole registry was read, so an incomplete registry
53
+ scans nothing.
54
+ """
55
+ for project_id, roots in sorted(projects.items()):
56
+ if incomplete:
57
+ yield SourceScan(SourceDomain(kind, project_id), (), (), "unavailable", (incomplete,))
58
+ elif len(roots) != 1:
59
+ yield SourceScan(SourceDomain(kind, project_id), (), (), "unavailable", ("conflicting-project-roots",))
60
+ else:
61
+ yield scan(roots[0], project_id)
37
62
 
38
63
 
39
64
  def sync_sources(*, home: Path | None = None, source: SourceKind | None = None) -> dict:
@@ -52,6 +52,16 @@ def value_lines(label: str, value: object) -> list[str]:
52
52
  return _value_lines(label, value, line)
53
53
 
54
54
 
55
+ def emit_result(payload: dict, *, text: bool, title: str) -> None:
56
+ """Print a command result as one JSON line, or as fixed text fields under `title`."""
57
+ if not text:
58
+ print(json.dumps(payload, ensure_ascii=False, allow_nan=False))
59
+ return
60
+ rows = [f"{title}\n", line("OK", payload["ok"])]
61
+ rows.extend(value_lines("Result", payload))
62
+ print("".join(rows), end="")
63
+
64
+
55
65
  def _quoted_scalar_line(label: str, value: object) -> str:
56
66
  return _line_prefix(label) + json.dumps(value, ensure_ascii=True) + "\n"
57
67
 
@@ -0,0 +1,175 @@
1
+ """Project-group registry: the project roots that belong to a named group."""
2
+ from __future__ import annotations
3
+
4
+ from datetime import datetime, timezone
5
+ from pathlib import Path
6
+
7
+ from okstra_project import ResolverError, upsert_project_json
8
+ from okstra_project.dirs import json_lock_path, registry_lock
9
+
10
+ from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
11
+ from .manager_paths import ManagerPathError, _slug_segment
12
+
13
+ ARTIFACT = "project group"
14
+
15
+
16
+ class ProjectGroupError(ValueError):
17
+ """Project-group validation or I/O failure."""
18
+
19
+
20
+ def groups_root(home: Path) -> Path:
21
+ return Path(home) / "project-groups"
22
+
23
+
24
+ def group_path(home: Path, name: str) -> Path:
25
+ try:
26
+ segment = _slug_segment(name, "project-group")
27
+ except ManagerPathError as exc:
28
+ raise ProjectGroupError(str(exc)) from exc
29
+ return groups_root(home) / f"{segment}.json"
30
+
31
+
32
+ def _now_iso() -> str:
33
+ return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
34
+
35
+
36
+ def _read_file(path: Path) -> dict:
37
+ try:
38
+ data = load_owned_object(path, artifact=ARTIFACT)
39
+ except JsonBoundaryError as exc:
40
+ raise ProjectGroupError(str(exc)) from exc
41
+ projects = data.get("projects")
42
+ if not isinstance(data.get("projectGroup"), str) or not isinstance(projects, list) or not all(
43
+ isinstance(row, dict)
44
+ and isinstance(row.get("projectId"), str)
45
+ and isinstance(row.get("projectRoot"), str)
46
+ for row in projects
47
+ ):
48
+ raise ProjectGroupError(f"malformed project group file: {path}")
49
+ return data
50
+
51
+
52
+ def _write_file(path: Path, data: dict) -> None:
53
+ try:
54
+ write_owned_object_atomic(path, data, artifact=ARTIFACT)
55
+ except JsonBoundaryError as exc:
56
+ raise ProjectGroupError(str(exc)) from exc
57
+
58
+
59
+ def _load(path: Path, name: str) -> dict:
60
+ data = _read_file(path)
61
+ # Different names can share one slug, and the file belongs to the first name stored in it.
62
+ if data["projectGroup"] != name:
63
+ raise ProjectGroupError(
64
+ f"project-group {name!r} shares its file with existing group "
65
+ f"{data['projectGroup']!r}: {path}"
66
+ )
67
+ return data
68
+
69
+
70
+ def read_group(home: Path, name: str) -> dict:
71
+ name = name.strip()
72
+ path = group_path(home, name)
73
+ if not path.is_file():
74
+ raise ProjectGroupError(f"unknown project-group: {name}")
75
+ return _load(path, name)
76
+
77
+
78
+ def add_project(
79
+ home: Path, name: str, project_id: str, project_root: Path, *, now: str | None = None
80
+ ) -> dict:
81
+ name = name.strip()
82
+ path = group_path(home, name)
83
+ root = Path(project_root).resolve()
84
+ if not root.is_dir():
85
+ raise ProjectGroupError(f"projectRoot is not a directory: {root}")
86
+ when = now or _now_iso()
87
+ with registry_lock(json_lock_path(path)):
88
+ data = (
89
+ _load(path, name)
90
+ if path.is_file()
91
+ else {"schemaVersion": 1, "projectGroup": name, "createdAt": when, "projects": []}
92
+ )
93
+ entry = next((row for row in data["projects"] if row["projectId"] == project_id), None)
94
+ changed = entry is None or entry.get("projectRoot") != str(root)
95
+ if changed:
96
+ try:
97
+ upsert_project_json(root, project_id, now=when)
98
+ except ResolverError as exc:
99
+ raise ProjectGroupError(str(exc)) from exc
100
+ if entry is None:
101
+ data["projects"].append(
102
+ {"projectId": project_id, "projectRoot": str(root), "linkedAt": when}
103
+ )
104
+ elif changed:
105
+ entry["projectRoot"] = str(root)
106
+ if changed:
107
+ data["projects"].sort(key=lambda row: row["projectId"])
108
+ _write_file(path, data)
109
+ return {
110
+ "ok": True,
111
+ "projectGroup": name,
112
+ "projectId": project_id,
113
+ "projectRoot": str(root),
114
+ "added": entry is None,
115
+ "changed": changed,
116
+ }
117
+
118
+
119
+ def remove_project(home: Path, name: str, project_id: str) -> dict:
120
+ name = name.strip()
121
+ path = group_path(home, name)
122
+ with registry_lock(json_lock_path(path)):
123
+ data = read_group(home, name)
124
+ kept = [row for row in data["projects"] if row["projectId"] != project_id]
125
+ if len(kept) == len(data["projects"]):
126
+ raise ProjectGroupError(f"project {project_id} is not in project-group {name}")
127
+ data["projects"] = kept
128
+ _write_file(path, data)
129
+ return {"ok": True, "projectGroup": name, "projectId": project_id, "removed": True}
130
+
131
+
132
+ def show_group(home: Path, name: str) -> dict:
133
+ data = read_group(home, name)
134
+ return {
135
+ "ok": True,
136
+ "projectGroup": data["projectGroup"],
137
+ "createdAt": str(data.get("createdAt") or ""),
138
+ "projects": [
139
+ {**row, "rootExists": Path(str(row.get("projectRoot") or "")).is_dir()}
140
+ for row in data["projects"]
141
+ ],
142
+ }
143
+
144
+
145
+ def _read_all(home: Path) -> tuple[list[dict], list[str]]:
146
+ groups, errors = [], []
147
+ groups_dir = groups_root(home)
148
+ for path in sorted(groups_dir.glob("*.json")) if groups_dir.is_dir() else []:
149
+ try:
150
+ groups.append(_read_file(path))
151
+ except ProjectGroupError as exc:
152
+ errors.append(f"{path.name}: {exc}")
153
+ return groups, errors
154
+
155
+
156
+ def list_groups(home: Path) -> dict:
157
+ groups, errors = _read_all(home)
158
+ return {
159
+ "ok": not errors,
160
+ "groups": [
161
+ {"projectGroup": data["projectGroup"], "projectCount": len(data["projects"])}
162
+ for data in groups
163
+ ],
164
+ "errors": errors,
165
+ }
166
+
167
+
168
+ def group_project_roots(home: Path) -> tuple[dict[str, tuple[Path, ...]], list[str]]:
169
+ """Every root the groups register for each projectId, and the unreadable group files."""
170
+ groups, errors = _read_all(home)
171
+ roots: dict[str, set[Path]] = {}
172
+ for data in groups:
173
+ for row in data["projects"]:
174
+ roots.setdefault(row["projectId"], set()).add(Path(row["projectRoot"]).resolve())
175
+ return {project_id: tuple(sorted(found)) for project_id, found in roots.items()}, errors
@@ -0,0 +1,62 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ from pathlib import Path
5
+
6
+ from okstra_project.dirs import okstra_home
7
+
8
+ from .fixed_text import emit_result
9
+ from .project_group import (
10
+ ProjectGroupError,
11
+ add_project,
12
+ list_groups,
13
+ remove_project,
14
+ show_group,
15
+ )
16
+
17
+
18
+ def _parser() -> argparse.ArgumentParser:
19
+ parser = argparse.ArgumentParser(
20
+ prog="okstra project-group",
21
+ description="Register which project roots belong to a named project group.",
22
+ )
23
+ commands = parser.add_subparsers(dest="command", required=True)
24
+ for name in ("add", "remove", "show", "list"):
25
+ command = commands.add_parser(name)
26
+ if name != "list":
27
+ command.add_argument("--project-group", required=True)
28
+ if name in ("add", "remove"):
29
+ command.add_argument("--project-id", required=True)
30
+ if name == "add":
31
+ command.add_argument("--project-root", required=True, type=Path)
32
+ output = command.add_mutually_exclusive_group()
33
+ output.add_argument("--json", action="store_true", help="emit JSON (default)")
34
+ output.add_argument("--text", action="store_true", help="emit fixed text fields")
35
+ return parser
36
+
37
+
38
+ def _emit(payload: dict, *, text: bool) -> None:
39
+ emit_result(payload, text=text, title="Okstra project-group")
40
+
41
+
42
+ def main(argv: list[str] | None = None) -> int:
43
+ args = _parser().parse_args(argv)
44
+ home = okstra_home()
45
+ try:
46
+ if args.command == "add":
47
+ result = add_project(home, args.project_group, args.project_id, args.project_root)
48
+ elif args.command == "remove":
49
+ result = remove_project(home, args.project_group, args.project_id)
50
+ elif args.command == "show":
51
+ result = show_group(home, args.project_group)
52
+ else:
53
+ result = list_groups(home)
54
+ except (ProjectGroupError, OSError) as exc:
55
+ _emit({"ok": False, "reason": str(exc)}, text=args.text)
56
+ return 1
57
+ _emit(result, text=args.text)
58
+ return 0 if result["ok"] else 1
59
+
60
+
61
+ if __name__ == "__main__":
62
+ raise SystemExit(main())
@@ -749,6 +749,9 @@
749
749
  "host_runtime": {
750
750
  "type": "string",
751
751
  "minLength": 1
752
+ },
753
+ "project_group": {
754
+ "type": "string"
752
755
  }
753
756
  }
754
757
  },
@@ -7,7 +7,7 @@
7
7
  "schemaVersion": {"type": "integer", "const": 1},
8
8
  "autoRegister": {"type": "boolean"},
9
9
  "scope": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/text"}]},
10
- "sources": {"type": "array", "uniqueItems": true, "items": {"enum": ["memory", "manager", "task"]}},
10
+ "sources": {"type": "array", "uniqueItems": true, "items": {"enum": ["memory", "manager", "task", "business"]}},
11
11
  "includeProjects": {"$ref": "#/$defs/names"},
12
12
  "excludeProjects": {"$ref": "#/$defs/names"},
13
13
  "includeGroups": {"$ref": "#/$defs/names"},
@@ -1126,16 +1126,60 @@ constraints, ticket relations — and no single brief can recover it
1126
1126
  selection measures the wrong quantity). If the file is absent, ask once via
1127
1127
  `prompt_user`:
1128
1128
 
1129
- - `Create the group context skeleton now (Recommended for a new task-group)`
1130
- → run `okstra group-context init --project-root <PROJECT_ROOT> --task-group <task-group>`
1131
- and echo its output verbatim. The skeleton carries one `<...>` placeholder
1132
- line per section; the user fills it. `/okstra-run` refuses to prepare any
1133
- task in the group while a placeholder line remains.
1129
+ - `Create the group context skeleton now` → run
1130
+ `okstra group-context init --project-root <PROJECT_ROOT> --task-group <task-group>`
1131
+ and echo its output verbatim, then continue with
1132
+ "Filling the sections" below. Label it
1133
+ `(Recommended for a new task-group)` only when the group directory holds no
1134
+ brief other than the ones this run wrote. The option description states the
1135
+ consequence: `/okstra-run` refuses to prepare **any** task in the group —
1136
+ existing ones included — while a placeholder line remains. When the group
1137
+ directory already holds other briefs, the description names them by brief id.
1134
1138
  - `Skip — this group needs no shared context`.
1135
1139
 
1136
1140
  Never fill the skeleton yourself from the tickets: a ticket summary decides
1137
1141
  nothing, and the sections ask for what the tickets do not say.
1138
1142
 
1143
+ #### Filling the sections
1144
+
1145
+ Run this right after `init`, and whenever the user asks to write or fill the
1146
+ group context — including a skeleton created earlier that still carries
1147
+ `<...>` lines. The user's answers are the only content; you collect and record
1148
+ them. If the file is absent, or holds only okstra's `## Task Memory` region
1149
+ and no `## ` section above it, run `okstra group-context init` first: `init`
1150
+ keeps that region and inserts the four sections above it.
1151
+
1152
+ 1. Ask one section at a time, in file order (`Why This Group Exists`,
1153
+ `Definition of Better`, `Group-Wide Constraints`, `Ticket Relations`), via
1154
+ `prompt_user` free text in the user's language. Each question restates what
1155
+ the section's template line asks for; for `Definition of Better` it asks
1156
+ for the quantity, its direction, and its denominator. Skip a section that
1157
+ already holds no `<...>` line.
1158
+ 2. For `Group-Wide Constraints` and `Ticket Relations`, offer `_(none)_` as an
1159
+ answer. `Why This Group Exists` and `Definition of Better` do not accept
1160
+ `_(none)_` — the validator rejects it there.
1161
+ 3. You may offer a draft sentence for a section only when it quotes something
1162
+ the user said in this conversation or a document the user names, with that
1163
+ source shown next to it. Ticket text and brief summaries are never a draft
1164
+ source. A draft is written only after the user accepts or edits it.
1165
+ 4. Replace the section's `<...>` line with the answer, keeping the user's
1166
+ wording. Splitting it into bullets is allowed; adding facts is not. Never
1167
+ touch the `## Task Memory` region.
1168
+ 5. After the last section, run
1169
+ `python3 ~/.okstra/lib/validators/validate-brief.py <group-context path> --briefs-root <PROJECT_ROOT>/.okstra/briefs`
1170
+ and show its result. Fix only what it names, by asking the user again.
1171
+ 6. If the user stops before every section is answered, leave the remaining
1172
+ `<...>` lines in place and say that every run of the group stays blocked
1173
+ until they are filled. Offer the other way out, and act only on the user's
1174
+ answer:
1175
+ - When the `## Task Memory` region holds no task entry (only
1176
+ `_(no runs recorded yet)_`), offer deleting the file.
1177
+ - When it holds task entries, offer removing the four authored sections and
1178
+ keeping the frontmatter, the H1 and the region. A file without authored
1179
+ sections passes preparation, and the region is the only copy of the
1180
+ recorded task conclusions, so deleting the file would lose them. If the
1181
+ user asks to delete it anyway, say that first.
1182
+
1139
1183
  If the file exists, what you do with it depends on what you are writing:
1140
1184
 
1141
1185
  - **A new brief** leaves it untouched. Mention its path in the hand-off block.
@@ -1166,7 +1210,9 @@ started; the brief ordinal in each brief id (`<TICKET>-<n>-<slug>`) is what
1166
1210
  okstra reads as the group's start order (`Related Task Graph` edges are
1167
1211
  quoted beside it as `waits for`, never reordering), so number the briefs in
1168
1212
  the order the user wants them started. When a
1169
- skeleton was created in 7a, add one line to the hand-off block:
1213
+ section body of the group context file still holds a `<...>` placeholder line
1214
+ after 7a (the validator command of "Filling the sections" reports `still carries a template placeholder`),
1215
+ add one line to the hand-off block:
1170
1216
 
1171
1217
  ```
1172
1218
  group context skeleton: <abs>/<task-group>/group-context.md (fill before /okstra-run)
@@ -19,12 +19,37 @@ Resolve `<host-runtime>` from the launcher's `OKSTRA_RUNTIME_HOST` when present;
19
19
 
20
20
  The runtime owns operation/model resolution, auditable invocation preparation, provider execution, source snapshots, validated result publication, shared knowledge and reports. Do not dispatch an unaudited replacement investigator or rerun an entire task when only an explanation failed.
21
21
 
22
+ By default the candidate projects are every project okstra has run in. When the user names a product or organization whose projects are registered as a project group (`okstra project-group list`), add `--project-group <name>`. The investigation then inspects that group's registered projects plus the current project, and the knowledge it receives is the claims those projects own. A claim's conflict status is still judged against every known project, so a conflict with a project outside the group is reported and reconciled across both. An unknown group fails the explanation; do not retry without the flag unless the user asks for the wider scope.
23
+
22
24
  For relevant stored knowledge:
23
25
 
24
26
  ```sh
25
- okstra explain-flow knowledge --query "<business question>"
27
+ okstra explain-flow knowledge --query "<business question>" [--project-group <name>]
26
28
  ```
27
29
 
30
+ ## Sweep a project group
31
+
32
+ Use this when the user wants the business flows of a whole project group explained, or stored explanations brought up to date. It runs one investigation per question, so the cost grows with the number of targets.
33
+
34
+ 1. List the group's projects with `okstra project-group show --project-group <name>`.
35
+ 2. Propose the questions. Read each member project's entry points, routes, jobs and top-level modules (read-only) and name one question per business domain, each owned by the project where the flow starts. Show the user the list and change it until they confirm it. Do not invent questions for a project you did not read.
36
+ 3. Write the confirmed list to a file as a JSON array of `{"projectId": "<member>", "question": "<business question>"}`.
37
+ 4. Plan first. This calls no model:
38
+
39
+ ```sh
40
+ okstra explain-flow sweep --project-group <name> --questions <file> [--stale]
41
+ ```
42
+
43
+ A listed question is a target unless its newest explanation is still `current`. Each target carries its reason: `new` (never explained), `historical` (a recorded project changed since) or `unverified` (a recorded source version cannot be compared, for example a member that is not a Git repository or tracks a symbolic link). An `unverified` question stays a target on every sweep, even right after it was explained. `--stale` adds every stored explanation that is `historical`; `--stale` alone refreshes without new questions. Report the target count with its reasons, the questions skipped as current, and every `Problem` line to the user. A `Problem` line can name a listed question that was not planned.
44
+ 5. Run only after the user accepts the target count:
45
+
46
+ ```sh
47
+ okstra explain-flow sweep --project-group <name> --questions <file> [--stale] --run --report-language <reader language> --host-runtime <current host runtime>
48
+ ```
49
+
50
+ Targets run one after another under the group, and a failed one does not stop the rest; the command exits 1 when any failed. A failed target printed with `(no record)` failed before its execution record was written. To retry one recorded target, run `okstra explain-flow rerun --execution <execution-id> --project-root <that member's root>`; the plan's JSON output lists each member's root under `roots`. To retry several, go back to step 4: plan again, report the new target count and run only after the user accepts it. Do not repeat `--run` on the earlier count, because `unverified` questions are targets again.
51
+ 6. To show the result, run `okstra doyouknow sync --source business` and then `okstra doyouknow view --project-group <name>`.
52
+
28
53
  For a failed or partial explanation:
29
54
 
30
55
  ```sh
@@ -43,4 +68,4 @@ Read the returned human report. Explain the business findings, verified scope an
43
68
 
44
69
  The investigation reads source, configuration, test bodies and explicitly supplied existing results. Its policy forbids executing tests, starting services, deploying, migrating or editing investigated projects. The report distinguishes that policy and the before/after source audit from an enforced write boundary. A report and a shared fact use the same accepted evidence. New runs retain prior reports and source baselines.
45
70
 
46
- Enforcement: `business_flow.engine` validates the result schema, source evidence and source stability before contribution; `agent.invocation` verifies standalone completion; `business_flow.store` preserves claim provenance and source versions. These behaviors are covered by the retired Python suite and existing invocation/JSON-boundary contract tests.
71
+ Enforcement: `business_flow.source.candidate_projects` selects the investigated projects and `business_flow.store.query_knowledge` the returned claims, covered by `tests/run/test_business_flow_invocation.py`; `business_flow.sweep.plan_sweep` decides the sweep targets, covered by `tests/doyouknow/test_explain_flow_sweep.py`; `business_flow.engine` validates the result schema, source evidence and source stability before contribution; `agent.invocation` verifies standalone completion; `business_flow.store` preserves claim provenance and source versions. These behaviors are covered by the retired Python suite and existing invocation/JSON-boundary contract tests.