okstra 0.231.0 → 0.232.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.
- package/README.md +15 -3
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +113 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +129 -2
- package/docs/architecture.md +11 -2
- package/docs/cli.md +234 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +85 -281
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
- package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/code_review_census.py +71 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
- package/runtime/python/okstra_ctl/code_review_target.py +85 -11
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/json_boundary.py +21 -2
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +26 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_sync.py +3 -22
- package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/report_assembly.py +15 -0
- package/runtime/python/okstra_ctl/report_narrative.py +3 -0
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +24 -1
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +25 -20
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/skills/okstra-code-review/SKILL.md +71 -123
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
- package/runtime/skills/okstra-manager/SKILL.md +7 -0
- package/runtime/skills/okstra-memory/SKILL.md +7 -0
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/validate-run.py +17 -8
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { existsSync } from "node:fs";
|
|
2
|
+
import { readFile } from "node:fs/promises";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { getPackageRoot } from "./version.mjs";
|
|
5
|
+
function compileRecordSecretPattern(value) {
|
|
6
|
+
if (typeof value !== "object" || value === null ||
|
|
7
|
+
!("pattern" in value) || typeof value.pattern !== "string" || !value.pattern ||
|
|
8
|
+
!("label" in value) || typeof value.label !== "string" || !value.label) {
|
|
9
|
+
throw new Error("Invalid record secret pattern");
|
|
10
|
+
}
|
|
11
|
+
return [new RegExp(value.pattern), value.label];
|
|
12
|
+
}
|
|
13
|
+
export async function detectRecordSecrets(content) {
|
|
14
|
+
const root = getPackageRoot();
|
|
15
|
+
const sourcePath = join(root, "schemas", "record-secret-patterns.json");
|
|
16
|
+
const policyPath = existsSync(sourcePath)
|
|
17
|
+
? sourcePath
|
|
18
|
+
: join(root, "runtime", "schemas", "record-secret-patterns.json");
|
|
19
|
+
const policy = JSON.parse(await readFile(policyPath, "utf8"));
|
|
20
|
+
if (typeof policy !== "object" || policy === null ||
|
|
21
|
+
!("schemaVersion" in policy) || policy.schemaVersion !== 1 ||
|
|
22
|
+
!("patterns" in policy) || !Array.isArray(policy.patterns) || !policy.patterns.length) {
|
|
23
|
+
throw new Error(`Invalid record secret policy: ${policyPath}`);
|
|
24
|
+
}
|
|
25
|
+
const patterns = policy.patterns.map(compileRecordSecretPattern);
|
|
26
|
+
return [...new Set(patterns.filter(([pattern]) => pattern.test(content)).map(([, label]) => label))];
|
|
27
|
+
}
|
|
28
|
+
//# sourceMappingURL=record-secrets.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"record-secrets.mjs","sourceRoot":"","sources":["../../src/lib/record-secrets.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,SAAS,0BAA0B,CAAC,KAAc;IAChD,IACE,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAC3C,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO;QAC5E,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK,EACtE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,6BAA6B,CAAC,CAAC;IACxE,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;QACvC,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,6BAA6B,CAAC,CAAC;IACpE,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IACvE,IACE,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAC7C,CAAC,CAAC,eAAe,IAAI,MAAM,CAAC,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC;QAC1D,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EACrF,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iCAAiC,UAAU,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACvG,CAAC"}
|
package/dist/lib/types.d.mts
CHANGED
|
@@ -93,7 +93,8 @@ export interface PythonModuleOptions {
|
|
|
93
93
|
readonly module: string;
|
|
94
94
|
readonly args?: CliArgs;
|
|
95
95
|
readonly extraEnv?: Readonly<Record<string, string | undefined>>;
|
|
96
|
-
readonly stdio?: "capture" | "inherit-stdout";
|
|
96
|
+
readonly stdio?: "capture" | "inherit-stdout" | "ignore";
|
|
97
|
+
readonly timeoutMs?: number;
|
|
97
98
|
}
|
|
98
99
|
export interface InstalledScriptOptions {
|
|
99
100
|
readonly scriptName: string;
|
|
@@ -1,5 +1,65 @@
|
|
|
1
1
|
# Storage model & on-disk contracts
|
|
2
2
|
|
|
3
|
+
Verification inputs version `3.0` requires `reviewPolicy`: a versioned frozen
|
|
4
|
+
architecture declaration and source bodies with SHA-256 digests. Preparation
|
|
5
|
+
captures the coding-preflight pack, project-root `AGENTS.md` and `CLAUDE.md`,
|
|
6
|
+
declared absolute `reviewRulePacks` paths, and their local `references/*.md`
|
|
7
|
+
links. Unreadable declarations fail capture before the snapshot is published.
|
|
8
|
+
Workers consume the content through `model-io verification-input`; source paths
|
|
9
|
+
record provenance rather than replacing the frozen baseline. Input versions
|
|
10
|
+
`1.0` and `2.0` retain their existing read contracts. Enforcement is in
|
|
11
|
+
`verification_inputs.py` and `review_policy.py`; preparation regression cases
|
|
12
|
+
in `tests/run/test_prepare.py` verify source preservation and rejected inputs.
|
|
13
|
+
|
|
14
|
+
Verification-input reader version `4.0` additionally requires the pre-execution
|
|
15
|
+
`reviewBase` and approved plan. Its implementation generations capture a
|
|
16
|
+
`designReview` census, policy fingerprint and any manual function inventory.
|
|
17
|
+
`agent/invocation.py` appends the same sealed worklist to initial and subsequent
|
|
18
|
+
verifier prompts. `design_review.py` parses independent responses against that
|
|
19
|
+
baseline through the same grouped-rule parser used by standalone code review.
|
|
20
|
+
New implementation and final-verification preparations with an approved plan
|
|
21
|
+
produce version `4.0`. They require stable QA command IDs and a valid conformance
|
|
22
|
+
baseline. Planning retains version `3.0`; its architecture validator reads the
|
|
23
|
+
captured declaration. Existing versions are not retrofitted on resume.
|
|
24
|
+
|
|
25
|
+
For a language without the existing Python AST census, capture writes
|
|
26
|
+
`generation-N.functions.json` beside the pending generation and refuses dispatch.
|
|
27
|
+
The lead fills `files[path]` with `functions: [{start, end, name}]` and a nonblank
|
|
28
|
+
`rationale` describing the whole-file inventory. Empty functions require that
|
|
29
|
+
rationale too. The base/head and unresolved-file set must match; spans must fit
|
|
30
|
+
the frozen source. Range validation does not prove semantic completeness of a
|
|
31
|
+
manual inventory. Named Python test helpers receive semantic cells as well as
|
|
32
|
+
the test file's state-and-tests cell. `tests/verification/test_design_review.py`
|
|
33
|
+
checks rule omissions, finding linkage, stale baselines and manual inventory.
|
|
34
|
+
|
|
35
|
+
`design_review_evidence.py` authenticates each configured verifier's current
|
|
36
|
+
invocation, latest attempt, generation and sealed result bytes. Assembly owns
|
|
37
|
+
`implementation.verifierResults[].designReview` and derives the verifier verdict
|
|
38
|
+
from that return; the narrative cannot author the evidence or turn FAIL into
|
|
39
|
+
PASS. Current blocking findings and missing required accounting prevent an
|
|
40
|
+
accepted or conditionally accepted publication. Collection errors leave the
|
|
41
|
+
previous report unchanged. Phase validation re-derives the evidence, and
|
|
42
|
+
`stage_done.py` requires the same task, stage, base, head and accepted report
|
|
43
|
+
before writing a carry or completion row.
|
|
44
|
+
|
|
45
|
+
The common `consumers.append_consumer` boundary also checks a new completion
|
|
46
|
+
from `stage-close` or carry recovery. A pending review is not recovered as done.
|
|
47
|
+
Reconciliation rows that adjust an already completed stage retain their existing
|
|
48
|
+
patch/commit reconciliation procedure; they are not a new acceptance decision.
|
|
49
|
+
An older run of the same stage cannot supply its latest completion report.
|
|
50
|
+
|
|
51
|
+
Correction generations inspect the full stage diff again. Prior judgments are
|
|
52
|
+
not inherited because dependency-complete carry attestations are not captured
|
|
53
|
+
by this contract. Earlier findings remain in `history`; every earlier blocking
|
|
54
|
+
finding needs an explicit `Design Carry` disposition and cited basis. Nits,
|
|
55
|
+
parked items and accepted-risk bases remain visible in the report. Final
|
|
56
|
+
verification checks these source implementation reports through its prepared
|
|
57
|
+
target; it does not perform another global style review. Semantic correctness,
|
|
58
|
+
grading and truth of a disposition remain worker/lead judgments. Enforcement is
|
|
59
|
+
in report assembly, implementation validation, stage completion and
|
|
60
|
+
`phases/final_verification/validation.py`; regression owners are
|
|
61
|
+
`tests/verification/test_design_review.py` and `tests/report/test_assembly.py`.
|
|
62
|
+
|
|
3
63
|
> Detailed storage and contract section from [`docs/architecture.md`](../architecture.md). This section was split out after the main document exceeded 1,000 lines.
|
|
4
64
|
|
|
5
65
|
## Storage model
|
|
@@ -320,8 +380,8 @@ Tier 3 command row. `validate-run` derives the evidence again and blocks
|
|
|
320
380
|
check, check run or generation, a changed record, a derived field that differs,
|
|
321
381
|
an omitted record, and an executed Tier 2 or Tier 3 row without a record. A
|
|
322
382
|
marked implementation run cannot settle a FAIL through `leadFixes`, and a stage
|
|
323
|
-
settled after correction round N needs
|
|
324
|
-
|
|
383
|
+
settled after correction round N needs the records of generation N + 1 of
|
|
384
|
+
each verifier that generation gives a check it may run. Unmarked runs and historical reports, including 2.0 reports and
|
|
325
385
|
`verdict: not-run` rows, assemble and validate as before; nothing converts them
|
|
326
386
|
or builds records from their strings. Execution records carry no server-target
|
|
327
387
|
observation and no applicability or skip disposition per frozen check, so the
|
|
@@ -477,7 +537,30 @@ Consumers parse only the `returnedBody` emitted by
|
|
|
477
537
|
documented `.project-docs/code-reviews/<branch>/` exception, but its invocation
|
|
478
538
|
specification, result envelope, and completion record remain under `.okstra/`.
|
|
479
539
|
|
|
540
|
+
New standalone code-review invocations also store `<invocation-id>.review-policy.json`
|
|
541
|
+
and `<invocation-id>.review-source.json`. The former binds the fixed base/head,
|
|
542
|
+
assigned canonical census, selected frozen rule bodies and the raw source-baseline
|
|
543
|
+
digest. Its digest appears in the immutable prompt. Shared policy originals are
|
|
544
|
+
archived once beside the full census; invocation selection never rereads live
|
|
545
|
+
installed rule bodies. Explicit resource selections supplement fixed-tree routing.
|
|
546
|
+
The shared policy's optional `authorPolicyDigest` identifies the complete policy
|
|
547
|
+
before protocol and additional-source capture. Reusing a census with an explicit
|
|
548
|
+
author run requires this identity to match exactly; an older shared policy without
|
|
549
|
+
it requires a new census output rather than an inferred match.
|
|
550
|
+
|
|
551
|
+
Completion for these invocations uses `schemaVersion: 2` and adds
|
|
552
|
+
`reviewAuditDigest`, binding `<invocation-id>.review-audit.json`. Publishing it
|
|
553
|
+
requires a successful source/Git comparison; CLI wrappers also require their
|
|
554
|
+
successful execution audit. Historical verification checks the stored audit and
|
|
555
|
+
baseline binding without comparing today's working tree. Older standalone
|
|
556
|
+
completions retain version 1. Source mutation detection is post-execution and
|
|
557
|
+
cannot guarantee prevention or observe arbitrary external side effects.
|
|
558
|
+
|
|
480
559
|
The persisted prompt's `**Worker Preamble Path:**` records the selected functional audience contract: analysis uses `templates/worker-prompt-preamble.md`, implementation executor/verifier uses `templates/implementation-worker-preamble.md`, and report writing uses `templates/report-writer-prompt-preamble.md`. Every initial prompt also persists `**Worker Error Contract Path:** templates/worker-error-contract.md`. A `runner=native-session` prompt additionally persists `**Host Session Contract Path:**`, resolved from the host adapter that declares `workerSessionContract`; the path is carried verbatim in the compact active-run context because it lives in the adapter tree rather than under the okstra home. Active-run and run-context runtime resources expose the same audience map plus the shared error-contract path, so dispatch replay and context-cost accounting do not infer an audience from a provider/model name.
|
|
560
|
+
The shared `Read scope` header owns the read boundary. `Analysis packet reading`
|
|
561
|
+
is emitted only for analysis or implementation workers whose input projection
|
|
562
|
+
lists the primary packet. Evidence headers own ledger syntax; the audience
|
|
563
|
+
preambles point to those headers instead of restating the protocol.
|
|
481
564
|
Unlike before, `analysis-profile.md`, `analysis-material.md`, `reference-expectations.md`, `task-brief.md`, skill copies, and `final-report-template.md` are not duplicated for every run.
|
|
482
565
|
These materials retain canonical copies in `instruction-set/` under the stable task root.
|
|
483
566
|
For `final-verification`, `verification-target.md` is also stable-task instruction-set state. Prepare owns the snapshot and stores its project-relative path plus SHA-256 digest in task/run manifests and active-run context. Initial analysis prompts carry the compact worktree/scope/base/head/path/digest identity and read this sidecar on demand instead of copying its diff stat.
|
|
@@ -764,3 +847,47 @@ Business artifacts use the original project root even when source inspection tar
|
|
|
764
847
|
- `.okstra/agent-invocations/explain-flow/`: frozen investigator prompt, role/duty snapshots, assignment metadata, process log/status, result envelope and verified completion.
|
|
765
848
|
|
|
766
849
|
The JSON boundary validates artifact schemas and atomically replaces files. Directory locks merge concurrent knowledge contributions and task links. Claims found in another project's knowledge store retain that owner; lookup does not copy them into another canonical store. A retry creates another execution id, and the original baseline and reports remain available.
|
|
850
|
+
|
|
851
|
+
## Linked work records
|
|
852
|
+
|
|
853
|
+
`okstra doyouknow` owns `<okstra-home>/doyouknow/graph.sqlite3`, independent of a
|
|
854
|
+
project or run. It stores scoped record and node identities, immutable revisions,
|
|
855
|
+
source references, evidence-bearing relations, and request identities. A write
|
|
856
|
+
uses one SQLite transaction; retries reuse their recorded result, while new
|
|
857
|
+
revisions check the expected previous revision. Lookup opens existing storage
|
|
858
|
+
read-only. `schemas/doyouknow-v1.schema.json` defines normalized write inputs.
|
|
859
|
+
|
|
860
|
+
Existing `memory-book/` notes, manager state, task artifacts, and shared business
|
|
861
|
+
knowledge retain their current owners. Explicit `sync` collects memory, manager
|
|
862
|
+
and manager-registered project task references; `list` reads current projections.
|
|
863
|
+
Native memory and manager writes request registration after their original save;
|
|
864
|
+
failures preserve identity-only pending UUIDs separately from SQLite. The
|
|
865
|
+
`pending/`, `registrations/` and `refusals/` directories under `doyouknow/` hold
|
|
866
|
+
delivery references, bounded attempt state and refusal fingerprints respectively.
|
|
867
|
+
Per-source locks serialize preparation and delivery, and acknowledgment removes
|
|
868
|
+
only the processed UUID. `preparationAttempts` records admitted preparation before
|
|
869
|
+
source I/O, independently of the fingerprint's delivery `attempts`. Three
|
|
870
|
+
incomplete preparations stop automatic work until explicit synchronization;
|
|
871
|
+
completed preparation resets that counter. Old state files without the preparation
|
|
872
|
+
counter read as zero. Excluded sources restore their prior delivery state.
|
|
873
|
+
Retry batches order references by modification time and UUID, then update only
|
|
874
|
+
an unsuccessful processed reference's modification time to let other work proceed.
|
|
875
|
+
Full synchronization combines pending recovery with
|
|
876
|
+
original-source comparison. `schemas/memory-entry-contract-v1.json`
|
|
877
|
+
owns entry fields and allowed type/status values for both Memory Book and its Python
|
|
878
|
+
collector. Collection distinguishes unreadable bodies, secret refusal and invalid
|
|
879
|
+
projections without copying source content into diagnostics.
|
|
880
|
+
The shared `schemas/record-secret-patterns.json` keeps the existing
|
|
881
|
+
memory rejection patterns available to both record writers. Its canonical digest
|
|
882
|
+
participates in source fingerprints so policy changes invalidate cached refusals.
|
|
883
|
+
Read-only collection and persistent refusal recording share the same pure
|
|
884
|
+
snapshot validator. Manager collection and automatic registration share one
|
|
885
|
+
acceptance policy: a refused manager root makes its domain unavailable, while a
|
|
886
|
+
refused task preserves healthy task updates and leaves the scan partial.
|
|
887
|
+
|
|
888
|
+
Database version 2 adds `source`, immutable `source_snapshot`, and source-owned
|
|
889
|
+
`source_relation` tables alongside the manual record tables. The same transaction
|
|
890
|
+
boundary serializes both writers. Upgrading version 1 first creates a mode-0600
|
|
891
|
+
`graph-v1-*.sqlite3` backup with a bounded backup deadline. Read-only lookup does
|
|
892
|
+
not migrate storage. `doyouknow/config.json` owns collection settings independently
|
|
893
|
+
of existing groups; incomplete scans preserve prior source data and confirmation times.
|
package/docs/architecture.md
CHANGED
|
@@ -198,6 +198,13 @@ Owned-object writes validate the complete replacement value before publication.
|
|
|
198
198
|
|
|
199
199
|
External JSON enters only through a purpose-specific adapter that validates its producer lane and path policy. The supported exceptions are user-supplied files outside `.okstra`, worker result lanes, Claude Code configuration, external-tool output inside its workspace, legacy error sidecars, and convergence results beside their state file. The sealed `ExternalJsonSource` type prevents a caller from granting itself a generic exception.
|
|
200
200
|
|
|
201
|
+
Both owned and external JSON readers accept an optional pre-parse byte limit.
|
|
202
|
+
Read-only task discovery uses `okstra_project.resolve_task_root_read_only`;
|
|
203
|
+
`find_task_root` retains its existing reconciliation behavior. Shared contained
|
|
204
|
+
path resolution lives in `okstra_project.dirs.contained_relative_path`.
|
|
205
|
+
Callers with an already validated catalog can supply it to the resolver,
|
|
206
|
+
avoiding another unbounded read of the same input.
|
|
207
|
+
|
|
201
208
|
Model callers receive fixed text projections instead of parsing owned objects. `okstra model-io` owns inspect projections, and `okstra preflight` renders named success or failure lines by default. A failure projection includes its stage, observed reason, and recovery action. Automation can request the unchanged preflight object with `--machine`; `--json` remains a deprecated one-release alias. A model-facing caller should rerun the named recovery action and then rerun the text command rather than opening the JSON artifact directly.
|
|
202
209
|
|
|
203
210
|
### State authority on disk
|
|
@@ -737,8 +744,10 @@ excludes it from default selection and rejects any mixed analysis/report batch.
|
|
|
737
744
|
The dispatch commands also record the lead checkpoints whose facts they hold
|
|
738
745
|
(`scripts/okstra_ctl/dispatch_checkpoints.py`): `team dispatch` and
|
|
739
746
|
`worker-dispatch` write `phase-3-team-create` when they write the implicit-team
|
|
740
|
-
marker, `phase-4-dispatch` per `initial` job and
|
|
741
|
-
|
|
747
|
+
marker, `phase-4-dispatch` per `initial` job and per job of an implementation
|
|
748
|
+
correction round (`correction-r<N>`, and a `reverify-r<k>` whose invocation id
|
|
749
|
+
carries `-correction-r<N>-`), and `phase-6-synthesis` on the first
|
|
750
|
+
report-writer dispatch; `team await` and `worker-dispatch` write
|
|
742
751
|
`phase-5-collect` for each `initial` dispatch they settle; `report-finalize`
|
|
743
752
|
writes `phase-7-persist` before its first step. The rows go through
|
|
744
753
|
`lead_progress.record_progress`, the writer `okstra lead-progress append` uses,
|
package/docs/cli.md
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# Implementation design-review inputs
|
|
2
|
+
|
|
3
|
+
New approved-plan implementation and final-verification preparations freeze
|
|
4
|
+
verification-input version 4.0, including the review base and coding policy.
|
|
5
|
+
Declared QA commands need stable IDs and the conformance baseline must be valid;
|
|
6
|
+
preparation reports a missing prerequisite instead of silently losing the gate.
|
|
7
|
+
`okstra model-io verification-input --run-manifest <path>` shows the core frozen
|
|
8
|
+
policy and archived resource inventory. Repeat `--source-path <changed-path>` to
|
|
9
|
+
select applicable frozen language/framework rules. Use `--resource <pack-relative-path>`
|
|
10
|
+
for an additional applicable resource, such as `languages/sql.md` for embedded SQL.
|
|
11
|
+
The original archived rules remain unchanged; normative text is never clipped.
|
|
12
|
+
|
|
13
|
+
Before verifier dispatch, a non-Python code change can require a manual inventory
|
|
14
|
+
at the reported `generation-N.functions.json` path. Retain its base/head and file
|
|
15
|
+
keys, replace each null entry with `functions: [{start, end, name}]` and a nonblank
|
|
16
|
+
whole-file `rationale`, then repeat the dispatch. An empty function list still
|
|
17
|
+
needs that rationale. Range checks do not prove inventory completeness.
|
|
18
|
+
|
|
19
|
+
`okstra stage-done` checks the same accepted report's task, stage, base/head and
|
|
20
|
+
sealed verifier results before writing completion. Current blocking findings,
|
|
21
|
+
missing rules and omitted correction dispositions prevent acceptance. Existing
|
|
22
|
+
input versions retain their stored behavior. Enforcement and limits are described
|
|
23
|
+
in [storage contracts](architecture/storage-model.md).
|
|
24
|
+
|
|
25
|
+
# Independent code-review inputs
|
|
26
|
+
|
|
27
|
+
`okstra code-review census` writes the census and an immutable adjacent
|
|
28
|
+
`<out>.policy.json`, printing `Review policy` and `Review policy digest`.
|
|
29
|
+
It uses the canonical catalog; use repeated `--policy <path>` for additional
|
|
30
|
+
project standards and `--resource <pack-relative-path>` for explicit routed resources.
|
|
31
|
+
For a stage, pass its identified `--run-manifest <path>` to reuse the author's
|
|
32
|
+
frozen policy. A missing author-policy reference is unverified policy alignment;
|
|
33
|
+
do not infer a latest run or claim that independently captured policies match.
|
|
34
|
+
|
|
35
|
+
`okstra code-review scope --review-policy <snapshot> ...` uses captured source
|
|
36
|
+
bodies for its rule fingerprints. New standalone `code-reviewer` materialization
|
|
37
|
+
requires `--review-policy`, `--review-census`, `--review-base`, and `--review-head`.
|
|
38
|
+
Repeat `--review-resource` with any explicit selections made for the census.
|
|
39
|
+
The materializer reads the fixed tree, validates canonical assigned rules, and
|
|
40
|
+
includes the selected frozen rules, calibration and assigned census itself.
|
|
41
|
+
Do not duplicate their bodies in an instruction file or replace them with live
|
|
42
|
+
installed paths. Both model coordinators and specialists use the same shared policy.
|
|
43
|
+
|
|
44
|
+
Standalone reviews audit source and Git changes after execution. A source or
|
|
45
|
+
index mutation prevents a successful review without restoring user changes.
|
|
46
|
+
New reviews publish version-2 completion markers bound to their integrity audit;
|
|
47
|
+
historical version-1 completion markers remain verifiable. This detects observed
|
|
48
|
+
mutations; it is not an operating-system write sandbox or proof of review quality.
|
|
49
|
+
|
|
50
|
+
# Linked work record commands
|
|
51
|
+
|
|
52
|
+
`okstra doyouknow` stores linked work records in the user home without requiring
|
|
53
|
+
a project registration or starting a run. Other commands describe their options
|
|
54
|
+
through `okstra <command> --help`.
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
okstra doyouknow capture --file /absolute/path/record.json
|
|
58
|
+
okstra doyouknow ingest --file /absolute/path/source.json
|
|
59
|
+
okstra doyouknow show <record-id>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
JSON is the default output. Add `--text` for fixed text fields. A successful write
|
|
63
|
+
returns `recordId`, `revisionId`, `created`, and the database `path`. Lookup returns
|
|
64
|
+
the record's revision history. A failed lookup does not create storage.
|
|
65
|
+
|
|
66
|
+
## Input contract
|
|
67
|
+
|
|
68
|
+
Both write commands accept the same normalized JSON envelope, validated against
|
|
69
|
+
`schemas/doyouknow-v1.schema.json`. Inputs are limited to 2,000,000 bytes,
|
|
70
|
+
32 levels of nesting, 1,000 nodes and 4,000 relations. `capture` records a session contribution;
|
|
71
|
+
`ingest` registers an already normalized source contribution. Neither command
|
|
72
|
+
collects a conversation, scans projects, or reads the source locator. The graph
|
|
73
|
+
viewer, automatic registration, and conversational skill belong to later changes.
|
|
74
|
+
Existing source collection is described below.
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"schemaVersion": 1,
|
|
79
|
+
"scope": "fonts",
|
|
80
|
+
"recordKey": "image-retry",
|
|
81
|
+
"requestId": "image-retry-save-1",
|
|
82
|
+
"expectedPreviousRevision": null,
|
|
83
|
+
"source": {
|
|
84
|
+
"kind": "session",
|
|
85
|
+
"id": "image-retry-session",
|
|
86
|
+
"revision": "1",
|
|
87
|
+
"locator": "local-session:image-retry-session"
|
|
88
|
+
},
|
|
89
|
+
"record": {
|
|
90
|
+
"title": "Image retry investigation",
|
|
91
|
+
"summary": "Recorded the investigation and its remaining verification.",
|
|
92
|
+
"type": "investigation"
|
|
93
|
+
},
|
|
94
|
+
"nodes": [
|
|
95
|
+
{"key": "font-image", "kind": "concept", "scope": "fonts", "title": "Font image"}
|
|
96
|
+
],
|
|
97
|
+
"relations": [
|
|
98
|
+
{
|
|
99
|
+
"from": "$record",
|
|
100
|
+
"to": "font-image",
|
|
101
|
+
"kind": "investigates",
|
|
102
|
+
"reason": "The investigation concerns font image retries.",
|
|
103
|
+
"evidence": ["Current session investigation notes"],
|
|
104
|
+
"standing": "user-stated"
|
|
105
|
+
}
|
|
106
|
+
]
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`scope` and `recordKey` identify a record stream. Each node is identified by its
|
|
111
|
+
`kind`, `scope`, and canonical `key`; titles are labels. Supply the repository
|
|
112
|
+
identity as a commit node's scope and the full commit hash as its key. Supply a
|
|
113
|
+
service and workspace scope for ticket nodes. This stage uses the supplied
|
|
114
|
+
identifiers and does not resolve Git references or verify remote tickets.
|
|
115
|
+
|
|
116
|
+
Relations reference a node's optional local `ref`, falling back to its `key`.
|
|
117
|
+
Use different refs when one envelope includes the same canonical key in different
|
|
118
|
+
scopes. `$record` references the record being saved. Each relation includes its
|
|
119
|
+
reason, evidence, and standing: `observed`, `user-stated`, or `candidate`.
|
|
120
|
+
|
|
121
|
+
To connect another record stream, supply a node with `kind: "record"`, its
|
|
122
|
+
original `recordKey` as `key`, and its original `scope`. The node resolves to the
|
|
123
|
+
same canonical identity as that record. A stream that has not been captured yet
|
|
124
|
+
creates a reference node without creating a record body or revision.
|
|
125
|
+
|
|
126
|
+
Retry the same `requestId` with the same input to reuse its result. Reusing that
|
|
127
|
+
request ID with different input is rejected. To append a revision, supply a new
|
|
128
|
+
request ID and source revision, and set `expectedPreviousRevision` to the latest
|
|
129
|
+
returned revision ID. Source revisions are immutable; registering the same source
|
|
130
|
+
revision with changed content is rejected. Writes save the record, nodes,
|
|
131
|
+
relations, and request identity in one transaction.
|
|
132
|
+
|
|
133
|
+
## Storage and existing memory
|
|
134
|
+
|
|
135
|
+
Storage lives at `<okstra-home>/doyouknow/graph.sqlite3`, where `okstra-home` follows
|
|
136
|
+
the existing `OKSTRA_HOME` setting and defaults to `~/.okstra`. Existing memory
|
|
137
|
+
entries remain in `memory-book/`; this command does not migrate or change them.
|
|
138
|
+
Both paths use the same high-confidence secret-pattern definitions before writes.
|
|
139
|
+
|
|
140
|
+
## Existing memory and manager sources
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
okstra doyouknow config
|
|
144
|
+
okstra doyouknow config --file /absolute/path/settings.json
|
|
145
|
+
okstra doyouknow sync
|
|
146
|
+
okstra doyouknow sync --source memory
|
|
147
|
+
okstra doyouknow retry --source memory --limit 100
|
|
148
|
+
okstra doyouknow register --ticket <pending-uuid>
|
|
149
|
+
okstra doyouknow list --source manager --limit 100
|
|
150
|
+
okstra doyouknow list --after <nextCursor>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`sync` reads existing Memory Book entries, manager registrations, assignments,
|
|
154
|
+
notes and snapshots, and tasks in manager-registered projects. It preserves the
|
|
155
|
+
original files. `list` reads the cached sources without collecting them again;
|
|
156
|
+
`--source`, `--scope`, `--limit` and `--after` select the returned page. JSON is
|
|
157
|
+
the default; all commands also accept `--text`. Partial collection exits 1 with
|
|
158
|
+
per-domain results while preserving successfully collected and prior sources.
|
|
159
|
+
|
|
160
|
+
Settings replacement uses `schemas/doyouknow-config-v1.schema.json`:
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"schemaVersion": 1,
|
|
165
|
+
"autoRegister": true,
|
|
166
|
+
"scope": null,
|
|
167
|
+
"sources": ["memory", "manager", "task"],
|
|
168
|
+
"includeProjects": [],
|
|
169
|
+
"excludeProjects": [],
|
|
170
|
+
"includeGroups": [],
|
|
171
|
+
"excludeGroups": []
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
An empty include list includes all; exclusions take precedence. Group filters
|
|
176
|
+
apply to Memory Book groups. A mixed-project memory is skipped before reading its
|
|
177
|
+
body if any related project is excluded or outside the include list. Unassigned
|
|
178
|
+
memory is skipped when projects are explicitly included. A null scope remains
|
|
179
|
+
unclassified and does not affect identity. Project discovery reads manager project
|
|
180
|
+
registries even when only the task source is enabled. `autoRegister` controls
|
|
181
|
+
native post-save registration. Explicit `sync` remains available when it is off
|
|
182
|
+
and still respects enabled sources and include/exclude settings.
|
|
183
|
+
|
|
184
|
+
Memory projections hold original metadata, a 1,000-character body preview and a
|
|
185
|
+
whole-body digest. The original Memory Book remains the full-text authority. The
|
|
186
|
+
whole body is checked for secrets. Files are limited to 2 MB, memory indexes to
|
|
187
|
+
10,000 rows, and list pages to 1,000 sources and 2 MB. `truncated` and `nextCursor`
|
|
188
|
+
identify another page; an oversized single item has `detailsOmitted: true`.
|
|
189
|
+
|
|
190
|
+
Source snapshots and relations have separate ownership from manual records.
|
|
191
|
+
Only a complete scan marks absent sources missing; filtered or unreadable sources
|
|
192
|
+
retain prior data and confirmation times. The first write upgrades database
|
|
193
|
+
version 1 to 2 after a private, uniquely named `graph-v1-*.sqlite3` backup succeeds.
|
|
194
|
+
|
|
195
|
+
### Automatic registration and recovery
|
|
196
|
+
|
|
197
|
+
Native memory save, source-key reuse and archive operations register the existing
|
|
198
|
+
entry after their original output. Successful manager mutations register that
|
|
199
|
+
manager's domain, including unlink changes. Reads and unconfirmed removals do not
|
|
200
|
+
enqueue work. Project task originals remain part of explicit `sync` collection.
|
|
201
|
+
|
|
202
|
+
The hooks first publish a mode-0600 identity-only reference under
|
|
203
|
+
`doyouknow/pending/<uuid>.json`, then run registration with ignored child output
|
|
204
|
+
and a five-second deadline. Failure emits a fixed stderr warning and preserves
|
|
205
|
+
the original result. If publishing itself fails, full `sync` recovers from the
|
|
206
|
+
original index or manager files. Automatic registration does not create another
|
|
207
|
+
Memory Book entry or repeat group selection.
|
|
208
|
+
|
|
209
|
+
`register` processes one pending UUID and acknowledges only that file. `retry`
|
|
210
|
+
processes up to `--limit` pending references (default 100, maximum 1,000).
|
|
211
|
+
It selects the oldest pending references first and moves unsuccessful processed
|
|
212
|
+
references behind waiting ones, so later batches can reach healthy sources.
|
|
213
|
+
Its `results` contain fixed states: `registered`, `excluded`, `pending`,
|
|
214
|
+
`exhausted` or `refused`, with source IDs, delivery `attempts` and
|
|
215
|
+
`preparationAttempts`. It exits 1 while
|
|
216
|
+
processed references remain unsuccessful; `truncated` indicates more work.
|
|
217
|
+
Automatic failures are limited to three per source fingerprint across UUIDs.
|
|
218
|
+
An unreadable source does not reset a known fingerprint's delivery budget.
|
|
219
|
+
Preparation has a separate limit of three consecutive incomplete attempts,
|
|
220
|
+
recorded after acquiring the source lock and before reading the original.
|
|
221
|
+
Completed preparation resets that counter; a process killed during preparation
|
|
222
|
+
leaves it recorded. Lock waiters have not started preparation and do not count.
|
|
223
|
+
Use `sync` after preparation exhaustion, even if the original has changed.
|
|
224
|
+
Redact or change a refused input before retrying it; unchanged secret refusal is
|
|
225
|
+
reused. Changes to the shared secret-detection policy also invalidate that refusal.
|
|
226
|
+
|
|
227
|
+
`sync` explicitly retries pending references even after exhaustion, then compares
|
|
228
|
+
the originals to recover requests lost before enqueue. Its `pendingRetry` field
|
|
229
|
+
reports pending processing separately from per-domain `results`. It exits 1 for
|
|
230
|
+
unsuccessful or truncated pending processing as well as partial collection.
|
|
231
|
+
Delivery state lives in `doyouknow/registrations/`; `doyouknow/refusals/` stores
|
|
232
|
+
only refusal fingerprints. These files do not contain source bodies. Manager
|
|
233
|
+
preparation detects changes between its fingerprint reads; it does not provide
|
|
234
|
+
an atomic snapshot across multiple manager files.
|
|
@@ -179,6 +179,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
|
|
|
179
179
|
| `task-list`, `task-show` | `scripts/okstra_ctl/task_list_cli.py`, `scripts/okstra_ctl/task_show_cli.py` | Task/run introspection for skills; `task-show` consumes the Python task read-side snapshot |
|
|
180
180
|
| `resolve-task-key` | `scripts/okstra_ctl/resolve_task_key.py` | Resolve a bare task-id to candidate task-keys from the project catalog |
|
|
181
181
|
| `set-work-status` | `scripts/okstra_ctl/set_work_status.py`, `scripts/okstra_ctl/direct_work.py` | Set user-managed `workStatus`, register an existing brief without a run, and share direct completion records through group memory and task queries |
|
|
182
|
+
| `doyouknow` | `scripts/okstra_ctl/doyouknow/cli.py`, `source_store.py`, `sources/` | Store manual records; configure, collect and list memory, manager and project-task source projections |
|
|
182
183
|
| `time-report`, `log-report`, `error-report`, `error-zip` | `scripts/okstra_ctl/time_report.py`, `scripts/okstra_ctl/log_report.py`, `scripts/okstra_ctl/error_report.py`, `scripts/okstra_ctl/error_zip.py` | Read-side task runtime, wrapper log, and error aggregation helpers |
|
|
183
184
|
| `run-audit` | `scripts/okstra_ctl/run_audit.py` | Anomaly detection — checks run artifacts against progress invariants and reports invariant violations, read-only (Python: `okstra_ctl.run_audit`) |
|
|
184
185
|
| `worker-liveness` | `scripts/okstra_ctl/worker_liveness.py` | Report whether pending workers are still alive, so the lead's poll ends a stalled wait early instead of paying the deadline (Python: `okstra_ctl.worker_liveness`) |
|
|
@@ -204,7 +205,7 @@ The Module column below is where the command's behaviour lives — a `src/` modu
|
|
|
204
205
|
| `wizard` | `src/commands/execute/wizard.mts` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
|
|
205
206
|
| `token-usage` | `scripts/okstra-token-usage.py` | Wrap installed Python token usage CLI |
|
|
206
207
|
| `spawn-followups`, `error-log` | `scripts/okstra-spawn-followups.py`, `scripts/okstra-error-log.py` | Follow-up task bundle creation and run error-log append helpers |
|
|
207
|
-
| `memory` | `src/commands/memory/memory.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
|
|
208
|
+
| `memory` | `src/commands/memory/memory.mts`, `src/lib/memory-entry-contract.mts` | Store/find global conversation memory under `~/.okstra/memory-book`; share entry validation with Python through `schemas/memory-entry-contract-v1.json`; `add --source-key` returns the stored entry for a key it already holds, under a per-key lock (`src/lib/file-lock.mts`, shared with `chat`) |
|
|
208
209
|
| `pr` | `src/commands/pr/pr.mts` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (default `templates/pr/pr-body.template.md`, shared with release-handoff), base-branch recommendation, and a fixed-text generation bundle — template, `<base>..<head>` commits, `<base>...<head>` diffstat and the `templates/pr/drafting-rules.md` drafting rules — used by the okstra-pr-gen skill and the release-handoff lead; `check` lists okstra identifiers left in a drafted body. `--json` preserves the same fields as a machine contract. Git-only; no project registration required |
|
|
209
210
|
| `recap` | `scripts/okstra_ctl/recap.py` | `okstra recap <assemble\|record\|note>` Node wrapper for task and group recaps — `assemble` is a read-only phase-transition summary for a task or, with `--task-group`, the group's start order plus each task's latest conclusion; `record` appends one line to `recap/recap-log.jsonl` (task) or `.okstra/tasks/<group>/.recap/recap-log.jsonl` (`--task-group`); `note` writes an agent-authored note under `notes/` and prints the `--clarification-response` argument for a follow-up run |
|
|
210
211
|
| `stage-map` | `scripts/okstra_ctl/stage_map_cli.py` | `okstra stage-map <task-key>` — exposes a task's implementation-planning Stage Map as JSON (`stages[].{stage_number,title,depends_on,step_count}` + consumer-state-based `doneStages[]`). If there is no Stage Map, `stages: []`. The read-side basis from which `okstra-schedule-gen` derives stage units and dependency closure |
|
package/package.json
CHANGED
package/runtime/BUILD.json
CHANGED
|
@@ -2,27 +2,27 @@
|
|
|
2
2
|
"schemaVersion": "1.0",
|
|
3
3
|
"id": "common",
|
|
4
4
|
"assignmentFidelity": [
|
|
5
|
-
"
|
|
5
|
+
"Follow the assigned scope, priorities and acceptance conditions. Preserve project architecture, terminology and ownership; choose the smallest conforming change without unrelated cleanup."
|
|
6
6
|
],
|
|
7
7
|
"requiredInputs": [
|
|
8
|
-
"Read
|
|
8
|
+
"Read required inputs completely. Report missing, unreadable, stale or contradictory inputs instead of inventing their contents."
|
|
9
9
|
],
|
|
10
10
|
"evidenceFirst": [
|
|
11
|
-
"
|
|
11
|
+
"Ground claims in inspected sources and observed results. Distinguish verified facts, inferences and unknowns; evidence outweighs repetition or votes. Recheck settled facts only for a stated cause."
|
|
12
12
|
],
|
|
13
13
|
"authorityAndScope": [
|
|
14
|
-
"Use only
|
|
14
|
+
"Use only granted permissions, tools and project scope. Outward-facing actions require explicit authorization."
|
|
15
15
|
],
|
|
16
16
|
"collaborationAndIndependence": [
|
|
17
|
-
"Respect
|
|
17
|
+
"Respect duty ownership and required independence. Preserve evidence-backed dissent; do not seed another agent's verdict or transfer your required decision to another role."
|
|
18
18
|
],
|
|
19
19
|
"instructionPrecedence": [
|
|
20
|
-
"
|
|
20
|
+
"Task instructions specialize this contract's procedures. They cannot expand authority or override independence and honesty; report such conflicts."
|
|
21
21
|
],
|
|
22
22
|
"conflictHandling": [
|
|
23
|
-
"
|
|
23
|
+
"Preserve the reserved boundaries, continue separable safe work and return the exact unresolved conflict to the responsible lead."
|
|
24
24
|
],
|
|
25
25
|
"completionHonesty": [
|
|
26
|
-
"
|
|
26
|
+
"Finish the assigned checks and deliverables, recovering from safe local failures. Report remaining work, failed or skipped checks and uncertainty; never present unperformed or partial work as complete."
|
|
27
27
|
]
|
|
28
28
|
}
|
|
@@ -2,17 +2,15 @@
|
|
|
2
2
|
"schemaVersion": "1.0",
|
|
3
3
|
"id": "verifier",
|
|
4
4
|
"legacyAliases": [],
|
|
5
|
-
"identity": "
|
|
5
|
+
"identity": "Independently judges assigned artifacts against their acceptance criteria.",
|
|
6
6
|
"responsibilities": [
|
|
7
|
-
"
|
|
8
|
-
"Report a failure with the specific condition that failed and what would satisfy it."
|
|
7
|
+
"Own the verdict and identify each unmet criterion and the evidence or correction that would satisfy it."
|
|
9
8
|
],
|
|
10
9
|
"requiredCapabilities": [
|
|
11
10
|
"source-readonly",
|
|
12
11
|
"worker-artifact-io"
|
|
13
12
|
],
|
|
14
13
|
"prohibitions": [
|
|
15
|
-
"Do not accept a claim on the strength of who made it, how many agreed, or how much effort it represents.",
|
|
16
14
|
"Do not repair the artifact you are verifying."
|
|
17
15
|
]
|
|
18
16
|
}
|
|
@@ -41,6 +41,7 @@ from okstra_ctl.dispatch_core import verify_served_model, verify_served_model_re
|
|
|
41
41
|
from okstra_ctl.dispatch_state import DispatchError # noqa: E402
|
|
42
42
|
from okstra_ctl.execution_manifest import read_execution_manifest_view # noqa: E402
|
|
43
43
|
from okstra_ctl.write_policy import ( # noqa: E402
|
|
44
|
+
build_standalone_review_write_contract,
|
|
44
45
|
WriteEnforcement,
|
|
45
46
|
WritePolicy,
|
|
46
47
|
write_enforcement_from_payload,
|
|
@@ -366,10 +367,15 @@ def _standalone_context(
|
|
|
366
367
|
return str(exc)
|
|
367
368
|
return ""
|
|
368
369
|
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
370
|
+
status = {"standaloneInvocationId": metadata["invocationId"], "role": actual_role}
|
|
371
|
+
policy, enforcement = None, None
|
|
372
|
+
if metadata["audience"] == "code-reviewer":
|
|
373
|
+
policy, enforcement = build_standalone_review_write_contract(
|
|
374
|
+
project_root, prompt_path, metadata_path, metadata,
|
|
375
|
+
)
|
|
376
|
+
status.update(standalonePurpose="code-review", writePolicyDigest=policy.digest,
|
|
377
|
+
writeEnforcement=enforcement.to_payload())
|
|
378
|
+
return _V2InvocationContext(status, verify_attestation, policy, enforcement, "")
|
|
373
379
|
|
|
374
380
|
|
|
375
381
|
def _execution_authority(
|