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.
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/trace/progression.mjs +6 -5
- package/dist/commands/trace/progression.mjs.map +1 -1
- package/dist/commands/trace/trace.mjs +2 -2
- package/dist/commands/trace/trace.mjs.map +1 -1
- package/docs/architecture/storage-model.md +19 -0
- package/docs/cli.md +41 -1
- package/docs/project-structure-overview.md +3 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
- package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
- package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
- package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
- package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
- package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
- package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
- package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
- package/runtime/python/okstra_ctl/fixed_text.py +10 -0
- package/runtime/python/okstra_ctl/project_group.py +175 -0
- package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
- package/runtime/schemas/business-flow-v1.schema.json +3 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +52 -6
- package/runtime/skills/okstra-explain-flow/SKILL.md +27 -2
- package/runtime/skills/okstra-tdd/SKILL.md +7 -4
- package/runtime/templates/doyouknow/group-view.css +103 -0
- package/runtime/templates/doyouknow/group-view.js +317 -0
- 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
|
|
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
|
|
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
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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())
|
|
@@ -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
|
|
1130
|
-
|
|
1131
|
-
and echo its output verbatim
|
|
1132
|
-
|
|
1133
|
-
task
|
|
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
|
-
|
|
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.
|