From 2c719487c6dc9c4d438884de24c21417eac03a27 Mon Sep 17 00:00:00 2001 From: sikjmyhre Date: Sun, 11 Oct 2026 22:25:26 +0800 Subject: [PATCH] feat: add on-demand code layouts (0.5.2) --- .agents/skills/omp-flow-check/SKILL.md | 7 ++ .agents/skills/omp-flow-design/SKILL.md | 7 ++ .agents/skills/omp-flow-research/SKILL.md | 8 ++ .claude/skills/omp-flow-check/SKILL.md | 7 ++ .claude/skills/omp-flow-design/SKILL.md | 7 ++ .claude/skills/omp-flow-research/SKILL.md | 8 ++ .omp/skills/omp-flow-check/SKILL.md | 7 ++ .omp/skills/omp-flow-design/SKILL.md | 7 ++ .omp/skills/omp-flow-research/SKILL.md | 8 ++ README.md | 14 ++++ README_EN.md | 15 ++++ package-lock.json | 4 +- package.json | 2 +- src/cli/init.ts | 8 +- .../.omp-flow/workflow/code/architect.md | 67 ++++++++++++++++ templates/.omp-flow/workflow/code/how.md | 58 ++++++++++++++ .../.omp-flow/workflow/code/interrogate.md | 77 +++++++++++++++++++ templates/.omp-flow/workflow/code/why.md | 62 +++++++++++++++ templates/.omp-flow/workflow/index.md | 12 +++ .../common/skills/omp-flow-check/SKILL.md | 7 ++ .../common/skills/omp-flow-design/SKILL.md | 7 ++ .../common/skills/omp-flow-research/SKILL.md | 8 ++ tests/codex-init.test.ts | 30 +++++++- 23 files changed, 431 insertions(+), 6 deletions(-) create mode 100644 templates/.omp-flow/workflow/code/architect.md create mode 100644 templates/.omp-flow/workflow/code/how.md create mode 100644 templates/.omp-flow/workflow/code/interrogate.md create mode 100644 templates/.omp-flow/workflow/code/why.md diff --git a/.agents/skills/omp-flow-check/SKILL.md b/.agents/skills/omp-flow-check/SKILL.md index 64ccde4d..0c8ed426 100644 --- a/.agents/skills/omp-flow-check/SKILL.md +++ b/.agents/skills/omp-flow-check/SKILL.md @@ -16,6 +16,13 @@ Fail closed unless all are available: - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions; - real implementation diff; +## Code layouts (on demand) + +Read only for the matching code-review question; resolve the installed path from the project root, +not from the Skill directory: + +- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`. + ## Review Order Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/.agents/skills/omp-flow-design/SKILL.md b/.agents/skills/omp-flow-design/SKILL.md index f5ad2928..502afaec 100644 --- a/.agents/skills/omp-flow-design/SKILL.md +++ b/.agents/skills/omp-flow-design/SKILL.md @@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re allowed output paths, actor ID, and receipt. - Source provenance needed for the design is readable through ordinary links. +## Code layouts (on demand) + +Read only for the matching code-design question; resolve the installed path from the project root, +not from the Skill directory: + +- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`. + ## Procedure Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/.agents/skills/omp-flow-research/SKILL.md b/.agents/skills/omp-flow-research/SKILL.md index b1befe83..f1efd2d1 100644 --- a/.agents/skills/omp-flow-research/SKILL.md +++ b/.agents/skills/omp-flow-research/SKILL.md @@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task - The entry contains a usable question or links to the current framing. - Each independent question has an explicit output path, normally under `research/`. +## Code layouts (on demand) + +Read only the layout matching a code question. Resolve these installed paths from the project +root, not from the Skill directory: + +- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`. +- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`. + ## Decide Research Scope For each consequential question, state which provisional anchor assumption, principal diff --git a/.claude/skills/omp-flow-check/SKILL.md b/.claude/skills/omp-flow-check/SKILL.md index 64ccde4d..0c8ed426 100644 --- a/.claude/skills/omp-flow-check/SKILL.md +++ b/.claude/skills/omp-flow-check/SKILL.md @@ -16,6 +16,13 @@ Fail closed unless all are available: - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions; - real implementation diff; +## Code layouts (on demand) + +Read only for the matching code-review question; resolve the installed path from the project root, +not from the Skill directory: + +- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`. + ## Review Order Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/.claude/skills/omp-flow-design/SKILL.md b/.claude/skills/omp-flow-design/SKILL.md index f5ad2928..502afaec 100644 --- a/.claude/skills/omp-flow-design/SKILL.md +++ b/.claude/skills/omp-flow-design/SKILL.md @@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re allowed output paths, actor ID, and receipt. - Source provenance needed for the design is readable through ordinary links. +## Code layouts (on demand) + +Read only for the matching code-design question; resolve the installed path from the project root, +not from the Skill directory: + +- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`. + ## Procedure Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/.claude/skills/omp-flow-research/SKILL.md b/.claude/skills/omp-flow-research/SKILL.md index b1befe83..f1efd2d1 100644 --- a/.claude/skills/omp-flow-research/SKILL.md +++ b/.claude/skills/omp-flow-research/SKILL.md @@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task - The entry contains a usable question or links to the current framing. - Each independent question has an explicit output path, normally under `research/`. +## Code layouts (on demand) + +Read only the layout matching a code question. Resolve these installed paths from the project +root, not from the Skill directory: + +- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`. +- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`. + ## Decide Research Scope For each consequential question, state which provisional anchor assumption, principal diff --git a/.omp/skills/omp-flow-check/SKILL.md b/.omp/skills/omp-flow-check/SKILL.md index 64ccde4d..0c8ed426 100644 --- a/.omp/skills/omp-flow-check/SKILL.md +++ b/.omp/skills/omp-flow-check/SKILL.md @@ -16,6 +16,13 @@ Fail closed unless all are available: - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions; - real implementation diff; +## Code layouts (on demand) + +Read only for the matching code-review question; resolve the installed path from the project root, +not from the Skill directory: + +- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`. + ## Review Order Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/.omp/skills/omp-flow-design/SKILL.md b/.omp/skills/omp-flow-design/SKILL.md index f5ad2928..502afaec 100644 --- a/.omp/skills/omp-flow-design/SKILL.md +++ b/.omp/skills/omp-flow-design/SKILL.md @@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re allowed output paths, actor ID, and receipt. - Source provenance needed for the design is readable through ordinary links. +## Code layouts (on demand) + +Read only for the matching code-design question; resolve the installed path from the project root, +not from the Skill directory: + +- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`. + ## Procedure Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/.omp/skills/omp-flow-research/SKILL.md b/.omp/skills/omp-flow-research/SKILL.md index b1befe83..f1efd2d1 100644 --- a/.omp/skills/omp-flow-research/SKILL.md +++ b/.omp/skills/omp-flow-research/SKILL.md @@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task - The entry contains a usable question or links to the current framing. - Each independent question has an explicit output path, normally under `research/`. +## Code layouts (on demand) + +Read only the layout matching a code question. Resolve these installed paths from the project +root, not from the Skill directory: + +- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`. +- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`. + ## Decide Research Scope For each consequential question, state which provisional anchor assumption, principal diff --git a/README.md b/README.md index fccd95cd..2e8a34bd 100644 --- a/README.md +++ b/README.md @@ -109,6 +109,20 @@ brainstorm ↔ research → design → QbD → work map → QbD → implementati 这是一条推理方向，不是 runtime phase state。证据可以让工作回到 framing 或 design；实现结果也必须经过不同 actor 的独立复核。完整语义见 [Workflow index](templates/.omp-flow/workflow/index.md)。 +### 按需代码布局（0.5.2） + +代码场景可以按需读取 `.omp-flow/workflow/code/` 下的作业布局： + +- [How](templates/.omp-flow/workflow/code/how.md)：理解子系统职责、数据归属与实际运行路径。 +- [Why](templates/.omp-flow/workflow/code/why.md)：从代码锚点追溯历史证据、约束与取舍。 +- [Architect](templates/.omp-flow/workflow/code/architect.md)：先写调用者用例，再推导数据结构和接口。 +- [Interrogate](templates/.omp-flow/workflow/code/interrogate.md)：独立检查具体失败路径、已排除风险与验证缺口。 + +Research、Design、Check Skills 只保留触发条件与路径索引，不预加载全部布局。 +布局复用当前分派的 Concept；小节可以按任务调整，不是新的 Workflow、固定文档 schema +或批准门。`init` 和 `update` 为所有选定 Harness 安装这些布局，沿用现有的本地修改保护。 + + ## 项目知识与文档系统 omp-flow 把不同生命周期和可信度的知识分开放置，但全部保持为普通 Markdown： diff --git a/README_EN.md b/README_EN.md index ec090ca9..46156159 100644 --- a/README_EN.md +++ b/README_EN.md @@ -115,6 +115,21 @@ brainstorm ↔ research → design → QbD → work map → QbD → implementati This is a reasoning direction, not runtime phase state. Evidence can return work to framing or design, and implementation results still require independent review by a different actor. See the [Workflow index](templates/.omp-flow/workflow/index.md) for the complete semantics. +### On-demand code layouts (0.5.2) + +For code-specific work, read the matching recipe under `.omp-flow/workflow/code/`: + +- [How](templates/.omp-flow/workflow/code/how.md): subsystem responsibilities, data ownership, and actual execution paths. +- [Why](templates/.omp-flow/workflow/code/why.md): code anchors, historical evidence, constraints, and tradeoffs. +- [Architect](templates/.omp-flow/workflow/code/architect.md): caller examples before data structures and interfaces. +- [Interrogate](templates/.omp-flow/workflow/code/interrogate.md): independent failure-path review, cleared risks, and verification gaps. + +The Research, Design, and Check Skills contain only trigger/path indexes; they do not preload every +layout. Reuse the assigned Concept and adapt suggested sections to the task. Layouts are not new +Workflows, fixed document schemas, or approval gates. `init` and `update` install them for every +selected Harness using the existing local-customization protection. + + ## Project knowledge and documentation omp-flow separates knowledge with different lifetimes and confidence levels while keeping all of it as ordinary Markdown: diff --git a/package-lock.json b/package-lock.json index 3decb461..d6943ed9 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "omp-flow", - "version": "0.5.1", + "version": "0.5.2", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "omp-flow", - "version": "0.5.1", + "version": "0.5.2", "license": "MIT", "dependencies": { "inquirer": "^9.3.7" diff --git a/package.json b/package.json index 5e627b68..77f0f342 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "omp-flow", - "version": "0.5.1", + "version": "0.5.2", "description": "Agent-native OKF task Bundles with a minimal portable runtime kernel.", "type": "module", "main": "dist/index.js", diff --git a/src/cli/init.ts b/src/cli/init.ts index 8c77f9c3..2abfdfaa 100644 --- a/src/cli/init.ts +++ b/src/cli/init.ts @@ -128,6 +128,10 @@ const WORKFLOW_LIBRARY_FILES = [ 'spec-formation.md', 'experiment.md', 'workflow-maintenance.md', + 'code/how.md', + 'code/why.md', + 'code/architect.md', + 'code/interrogate.md', ] as const; const CORE_RESOURCES: readonly ManagedResource[] = [ @@ -137,8 +141,8 @@ const CORE_RESOURCES: readonly ManagedResource[] = [ group: 'core', }, ...WORKFLOW_LIBRARY_FILES.map(fileName => ({ - sourcePath: path.join('templates', '.omp-flow', 'workflow', fileName), - destinationPath: path.join('.omp-flow', 'workflow', fileName), + sourcePath: path.join('templates', '.omp-flow', 'workflow', ...fileName.split('/')), + destinationPath: path.join('.omp-flow', 'workflow', ...fileName.split('/')), group: 'core' as const, })), { diff --git a/templates/.omp-flow/workflow/code/architect.md b/templates/.omp-flow/workflow/code/architect.md new file mode 100644 index 00000000..c83a7afa --- /dev/null +++ b/templates/.omp-flow/workflow/code/architect.md @@ -0,0 +1,67 @@ +# Architect: Design a Code Boundary + +Use this optional code layout with `omp-flow-design` when a selected synthesis needs a concrete +code interface, data model, or ownership boundary. The Skill, linked decisions, and native +assignment remain authoritative. Reuse the assigned Design/interface output Concept; the headings +below are suggestions, not a mandatory schema or a separate Concept per invocation. + +This is design, not implementation. Keep sketches in prose or Concept code blocks. Do not commit +source stubs, placeholder implementations, or an API merely to make the design look executable. +The layout supplies neither automatic sign-off nor permission to bypass human/QbD approval. + +## Show callers before signatures + +1. Restate the observable problem, binding requirements, non-goals, and evidence from the selected + synthesis. Name the concrete consequence the design must enable or prevent. +2. Start with realistic caller examples: where the call happens, what information is available, + the useful result, and the failure the caller must handle. Include a lifecycle or asynchronous + example only when the target needs one. Do not invent consumers to justify an abstraction. +3. Use those examples to derive the smallest useful public boundary, then sketch signatures or + messages. Explain each component's causal purpose in plain language. Prefer a deep boundary + that owns meaningful work and hides internal detail over shallow wrappers or exposed internals. + +## Make data and ownership authoritative + +- Describe the relevant data shape and the meaning of its fields: required/optional values, units, + identity, validity, and lifetime where material. Distinguish authoritative state from derived or + cached views; avoid two competing sources of truth. +- Show access paths from creation or loading through readers, writers, transformations, persistence, + and disposal. Name the owner allowed to mutate state and the boundary where ownership transfers. +- Assign responsibility for validation, resource acquisition/release, and partial completion. + Explain ordering or concurrent access only where it affects this design; do not add machinery for + hypothetical requirements. +- Specify the public contract: inputs, outputs, important invariants, errors, and which failures + callers handle versus which the boundary prevents. Cover cancellation, cleanup, and side effects + when applicable, including what remains after failure. Never rely on an unexplained fallback. +- Keep private representation and incidental operations behind the boundary. Explain unavoidable + compatibility or migration obligations without introducing an unrequested parallel API. + +## Compare only material alternatives + +Use the research evidence and caller examples to compare alternatives that could change the +selected boundary, correctness, cost, or maintainability. State the relevant trade-off and why the +chosen option solves the observed problem. There is no minimum candidate count, mandatory prototype, +or requirement to manufacture alternatives for a mechanical decision. Record consequential rejected +options and the evidence that would reopen them. + +## Plan verification and return signals + +Map observable requirements and important invariants to specific checks: caller-level examples, +contract tests, failure/cleanup cases, or other evidence suited to the risk. Separate proposed +commands and expected observations from verification actually performed. Name any material unknown +and its owner; an unresolved blocking decision is not ready for decomposition. + +State what observation would invalidate the design or its framing, such as an incompatible caller, +a violated ownership assumption, or an unmet binding constraint. Return that evidence to Main +through the assigned output for further research, framing, or design rather than suppressing it to +preserve the sketch. Main owns transitions and approval; the Architect does not approve its own gate. + +## Suggested output navigation + +Adapt or omit sections as useful: + +- **Problem and caller examples:** observable requirements, constraints, non-goals, and source links. +- **Boundary and data model:** proposed contract, authoritative values, access paths, and ownership. +- **Behavior and invariants:** normal operation, relevant failures, concurrency, and cleanup. +- **Trade-offs:** evidence-led choice, material alternatives, and compatibility obligations. +- **Verification and open decisions:** acceptance checks, return signals, and consequential unknowns. diff --git a/templates/.omp-flow/workflow/code/how.md b/templates/.omp-flow/workflow/code/how.md new file mode 100644 index 00000000..75003385 --- /dev/null +++ b/templates/.omp-flow/workflow/code/how.md @@ -0,0 +1,58 @@ +# How: Trace Code Behavior + +Use this optional code layout with `omp-flow-research` when the question is how a concrete code +path works. The Skill and native assignment remain authoritative. Write into the assigned output +Concept; a small explanation can be inline there. The headings below are suggested navigation, +not a required schema, a separate Concept per invocation, or a workflow gate. + +## Bound the explanation + +- Name the question, observed revision, and code anchor: entry point, symbol, or behavior. State + which decision or assumption the explanation can change. +- Read the implementation and its callers before relying on comments or tests. Follow only the + dependencies needed to explain the target; do not turn a local question into a repository tour. +- Use useful `file:line` references at that revision for consequential claims. Separate observed + behavior, inference, and unknowns; a function name is not evidence of what it does. + +## Follow behavior and ownership + +1. Establish each relevant component's responsibility and boundary. Identify who supplies inputs, + validates them, calls the next component, and consumes the result. +2. Track data and state: authoritative values, derived copies, mutable fields, persistence, and + the owner allowed to change each. For resources, identify acquisition, transfer, lifetime, and + the party responsible for release. +3. Trace an actual normal execution from the caller through significant branches and back to the + externally visible result. Include asynchronous handoffs and ordering when they affect behavior. +4. Trace relevant error, cancellation, and cleanup paths separately. Show where failure originates, + how it propagates, which side effects survive, and what is released on partial completion. + If cancellation is unsupported, say so with evidence; if it was not investigated, say that + instead. Do not invent a cancellation or cleanup guarantee. +5. Read relevant tests and contracts as supporting evidence. Record commands and results only when + exercised, and distinguish source-based reasoning from runtime observation. +6. Explain gotchas that change a caller's expectations: hidden mutation, blocking work, ownership + transfer, ordering, failure after a side effect, or cleanup that depends on the caller. Include + only those supported by this target, not a generic risk inventory. + +## Scale to the question + +Keep simple targets in the assigned Concept. For a complex target, identify only slices that can +be investigated independently, with their boundaries and the shared question they answer. +Only Main/coordinator may delegate those slices through the existing native operation contract: +Bundle, role, bounded objective, entry and output Concepts, actor ID, opaque receipt, and predecessor +when required. A dispatched child never spawns or redispatches. There is no fixed worker count or +mandatory decomposition. + +## Suggested output navigation + +Adapt or omit sections that do not help the reader: + +- **Anchor and scope:** question, revision, entry point, and relevant callers. +- **Responsibilities and ownership:** components, important values/resources, writers, and lifetimes. +- **Execution:** normal path and relevant error/cancel/cleanup branches, with code references; + a small sequence sketch or table is useful only if it clarifies the flow. +- **Gotchas and limits:** surprising behavior, evidence strength, and uninvestigated paths. +- **Conclusion:** the answer, its effect on the decision, and remaining consequential questions. + +If observed behavior contradicts the framing or an accepted contract, preserve that evidence and +report the contradiction through the assigned output to Main. An explanation is not authority to +change code, expand scope, or transition the workflow. diff --git a/templates/.omp-flow/workflow/code/interrogate.md b/templates/.omp-flow/workflow/code/interrogate.md new file mode 100644 index 00000000..d4babaca --- /dev/null +++ b/templates/.omp-flow/workflow/code/interrogate.md @@ -0,0 +1,77 @@ +# Interrogate: Challenge Implemented Code + +Use this optional code layout with `omp-flow-check` for an evidence-led adversarial review of one +bounded implementation. The Check Skill's inputs, independent identity, verdict rules, and native +assignment remain authoritative. Reuse the assigned Review Concept. Headings are suggestions, not +a fixed schema, a new Concept per invocation, or an additional approval gate. + +## Fix the review target + +- Read the approved Work, linked design/decisions, and completed predecessor handoff. Confirm the + reviewer is a different actor and the required receipt/output links match. A handoff is a claim, + not independent evidence of acceptance. +- Inspect the real diff and affected callers at the exact revision. Record the complete inspected + `BASE..HEAD`; for repair use the handoff's `FIX_BASE..HEAD` and identify the addressed findings. + If reviewing uncommitted changes, identify the base and exact inspected working-tree snapshot + rather than pretending it is a committed range. Do not use a stale diff. +- State the bounded approved intent, acceptance criteria, applicable non-negotiable boundaries, and + linked principal checkpoint. If a required input or linkage is missing, report it rather than + inventing the missing intent or checkpoint. + +## Build concrete failure trajectories + +Challenge the code with plausible inputs, state, and event ordering. Trace each suspected failure +from trigger through the relevant branch or interaction to an observable consequence. Use code +citations at the inspected revision; run a focused reproduction when it clarifies or tests the +claim and the assignment permits it. Distinguish an observed result from a proposed reproduction +or source-based inference. + +Inspect the risks relevant to this diff, not an obligatory checklist of findings: + +- **Scope and contracts:** approved behavior, affected callers, public/API or stored-data semantics, + invariants, and acceptance checks; detect unrelated changes or a green test that misses the goal. +- **Security and trust:** input/path boundaries, authority, sensitive data, and fail-closed behavior. +- **State and concurrency:** ownership, ordering, races, cancellation, and partially completed work. +- **Errors and cleanup:** propagation, surviving side effects, resource lifetime, and release paths. +- **Maintainability and evidence:** unnecessary complexity, hidden coupling, regression coverage, + and the limits of actual verification. + +Seek the strongest counter-case to the implementation and to the design's causal assumptions. +If code or practice contradicts the approved framing, preserve the evidence in the Review rather +than dismissing it as outside the story. Do not force a finding count, multiple models, or invented +faults. Do not broadly auto-fix code or expand the Review into implementation. + +## Preserve Check verdict semantics + +Give every finding all applicable labels; do not call every issue a Hard Blocker: + +- `HARD_BLOCKER`: violates a non-negotiable boundary. +- `PRINCIPAL_BLOCKER`: concretely prevents the linked principal checkpoint. +- `WORK_FAIL`: fails this Work's acceptance criterion or a test exercising it. If the Work is + required for the next principal checkpoint, also apply `PRINCIPAL_BLOCKER`. +- `ADVISORY`: explicit residual risk that does not fail Work acceptance or the principal checkpoint. + A red test is advisory only with evidence that it is unrelated, pre-existing, and separately + attributable, including the exact command/result. Missing or ambiguous attribution cannot + justify `PASS`. + +Any `HARD_BLOCKER`, `PRINCIPAL_BLOCKER`, or `WORK_FAIL` makes this Work `FAIL`; only the first two +pause the principal path. A `WORK_FAIL` without a stronger label stays in the recorded owning-Work +backlog and requires explicit human/design routing at the principal checkpoint, not autonomous +repair/review dispatch. Advisory findings alone do not fail or reopen accepted Work or preempt the +principal queue. + +Use `PASS` only when the Work's acceptance criteria hold, the linked principal checkpoint is not +blocked and required linkage is present, and every test exercising either passes. Record cleared +risks and remaining evidence gaps explicitly; unexamined behavior is not a cleared risk. A model +verdict never replaces human/QbD judgment or authorizes a workflow transition. + +## Suggested output navigation + +Adapt to the assigned Review without weakening the Check contract: + +- **Verdict and severity-ordered findings:** all applicable labels, concrete consequence, affected + requirement/checkpoint, code citations, reproduction/evidence, and a bounded repair direction. +- **Inspected scope:** Work/handoff/design links, revision or snapshot, reviewer identity, and receipts. +- **Verification:** exact exercised commands/results and counts; distinguish pending checks from passes. +- **Cleared risks and gaps:** what was challenged, supporting evidence, residual risks, and limits. +- **Contradictions and disposition:** design/framing-return signals for Main and any required routing. diff --git a/templates/.omp-flow/workflow/code/why.md b/templates/.omp-flow/workflow/code/why.md new file mode 100644 index 00000000..5d9d52d1 --- /dev/null +++ b/templates/.omp-flow/workflow/code/why.md @@ -0,0 +1,62 @@ +# Why: Recover Code Rationale + +Use this optional code layout with `omp-flow-research` when a code decision's origin or continuing +justification matters. The Skill and native assignment remain authoritative. Reuse the assigned +output Concept. Suggested headings are human navigation, not a fixed schema, a new Concept per +invocation, or an approval gate. + +## Start with the observed code + +Name the question, current revision, and precise code anchor using `file:line`. Describe the +behavior or constraint that actually exists before asking why it exists. Separate an explanatory +question from a proposed change; historical research does not authorize implementation. + +## Recover useful provenance + +1. Follow repository history to the change that introduced the relevant behavior or constraint. + A blame result is a lead, not necessarily the originating decision: follow moves, rewrites, and + earlier changes when they matter. +2. Record exact commit hashes, PR/issue URLs, or relevant incident/decision records and the passages + that support the explanation. Distinguish what each source says from what the diff demonstrates. + Follow the Research Skill's source/Reference guidance; avoid duplicating existing provenance. +3. Reconstruct the pressures at the time: observed failures, caller needs, compatibility, operating + conditions, or other evidenced constraints. Establish chronology when it changes the explanation. +4. Identify alternatives actually considered and the stated reasons for choosing or rejecting them. + A present-day alternative is not evidence that the original author considered it. Mark any causal + interpretation without direct support as inference. +5. Look for counter-evidence: later corrections, changed requirements, exceptions, or an incident + that weakens the apparent rationale. Do not protect an attractive historical story from facts. + +Use only sources useful to the question; there is no required source count or fan-out. When history, +an issue, or an incident record is missing or inaccessible, record the gap and its effect on the +conclusion. Missing provenance means the original motive is unknown, not that it was sensible, +accidental, or malicious. Do not invent author intent or insist on unavailable sources to fill a +checklist. + +## Test the rationale against today + +- Compare the original pressures with current code, callers, tests, requirements, and operating + conditions. Identify which constraints still apply and which have evidence of changing. +- Keep three claims distinct: what caused the decision, what the implementation currently does, + and whether retaining it is justified now. Evidence for one does not automatically prove another. +- State what evidence would permit removal or simplification: for example, disappearance of a + supported caller or a regression check showing the old failure no longer occurs. Identify the + compatibility, safety, or ownership obligations that would still need a bounded approved change. +- If current validity cannot be determined, say what remains unknown and which observation would + change the decision. Recommend investigation or a return to framing/design when warranted; + do not quietly turn this explanation into a redesign or a removal patch. + +## Suggested output navigation + +Adapt or omit sections that do not serve this question: + +- **Observed anchor:** current behavior, revision, and code citations. +- **Provenance:** exact sources, chronology, and the claims each supports. +- **Original pressures and alternatives:** documented rationale versus inferred explanations. +- **Current validity:** surviving constraints, changed conditions, and counter-evidence. +- **Removal conditions and gaps:** evidence needed for a new decision, unknowns, and a bounded + recommendation to Main. + +Keep facts, inferences, and unknowns explicit throughout. Report material evidence contradicting +the current framing through the assigned output; source recovery does not supply human approval or +choose the next workflow transition. diff --git a/templates/.omp-flow/workflow/index.md b/templates/.omp-flow/workflow/index.md index 54456adc..dc6248c1 100644 --- a/templates/.omp-flow/workflow/index.md +++ b/templates/.omp-flow/workflow/index.md @@ -42,3 +42,15 @@ changes the decision. The links are authored navigation. Workflow documents guide reasoning and evidence; Runtime and Harnesses continue to own session, assignment, actor identity, execution, and atomic side effects. + +## Code layouts (optional) + +These are on-demand code recipes within existing Skills, not additional Workflows, Skills, +operation types, or approval gates. Load only the matching layout for code work; do not preload +them for ordinary research or discussion. Reuse the assigned output Concept and adapt or omit +suggested headings rather than treating them as a fixed schema. + +- [How](code/how.md) — execution and data/state ownership explanation with `omp-flow-research`. +- [Why](code/why.md) — code history, rationale, and current validity with `omp-flow-research`. +- [Architect](code/architect.md) — caller, interface, and ownership design with `omp-flow-design`. +- [Interrogate](code/interrogate.md) — bounded adversarial code review with `omp-flow-check`. diff --git a/templates/common/skills/omp-flow-check/SKILL.md b/templates/common/skills/omp-flow-check/SKILL.md index 64ccde4d..0c8ed426 100644 --- a/templates/common/skills/omp-flow-check/SKILL.md +++ b/templates/common/skills/omp-flow-check/SKILL.md @@ -16,6 +16,13 @@ Fail closed unless all are available: - work Concept and predecessor-linked handoff, plus any applicable linked design or decisions; - real implementation diff; +## Code layouts (on demand) + +Read only for the matching code-review question; resolve the installed path from the project root, +not from the Skill directory: + +- Adversarial review of bounded implemented code: `.omp-flow/workflow/code/interrogate.md`. + ## Review Order Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/templates/common/skills/omp-flow-design/SKILL.md b/templates/common/skills/omp-flow-design/SKILL.md index f5ad2928..502afaec 100644 --- a/templates/common/skills/omp-flow-design/SKILL.md +++ b/templates/common/skills/omp-flow-design/SKILL.md @@ -11,6 +11,13 @@ description: Turn a selected synthesis in an omp-flow task Bundle into linked re allowed output paths, actor ID, and receipt. - Source provenance needed for the design is readable through ordinary links. +## Code layouts (on demand) + +Read only for the matching code-design question; resolve the installed path from the project root, +not from the Skill directory: + +- Caller, interface, data-shape, and ownership design: `.omp-flow/workflow/code/architect.md`. + ## Procedure Main/coordinator alone dispatches, correlates receipts, records human calibration, and chooses diff --git a/templates/common/skills/omp-flow-research/SKILL.md b/templates/common/skills/omp-flow-research/SKILL.md index b1befe83..f1efd2d1 100644 --- a/templates/common/skills/omp-flow-research/SKILL.md +++ b/templates/common/skills/omp-flow-research/SKILL.md @@ -12,6 +12,14 @@ description: Investigate repository or external evidence within an omp-flow task - The entry contains a usable question or links to the current framing. - Each independent question has an explicit output path, normally under `research/`. +## Code layouts (on demand) + +Read only the layout matching a code question. Resolve these installed paths from the project +root, not from the Skill directory: + +- Code execution and data/state ownership explanation: `.omp-flow/workflow/code/how.md`. +- Code history, original rationale, and current validity: `.omp-flow/workflow/code/why.md`. + ## Decide Research Scope For each consequential question, state which provisional anchor assumption, principal diff --git a/tests/codex-init.test.ts b/tests/codex-init.test.ts index 4fa8cbdf..a0ced556 100644 --- a/tests/codex-init.test.ts +++ b/tests/codex-init.test.ts @@ -186,9 +186,21 @@ export function runCodexInitTests(check: Check): void { writeHarnessConfig(modifiedRoot); const userModifiedHook = `${oldHook.trim()}\n// user modification\n`; const userWikiSpecsIndex = '# User-owned specs navigation\n\n- keep me\n'; + const customizedLayout = '.omp-flow/workflow/code/how.md'; + const missingLayouts = [ + '.omp-flow/workflow/code/why.md', + '.omp-flow/workflow/code/architect.md', + '.omp-flow/workflow/code/interrogate.md', + ] as const; + const previousLayout = '# Previously managed code layout\n'; + const userCodeLayout = '# Project coding layout\n\nKeep project-local changes.\n'; write(modifiedRoot, '.codex/hooks.json', userModifiedHook); write(modifiedRoot, '.omp-flow/wiki/specs/index.md', userWikiSpecsIndex); - saveHashes(modifiedRoot, { '.codex/hooks.json': computeHash(oldHook) }); + write(modifiedRoot, customizedLayout, userCodeLayout); + saveHashes(modifiedRoot, { + '.codex/hooks.json': computeHash(oldHook), + [customizedLayout]: computeHash(previousLayout), + }); const modifiedPlan = analyzeChanges(modifiedRoot, loadHashes(modifiedRoot)); check( entry(modifiedPlan, '.codex/hooks.json')?.status === 'changed' @@ -200,6 +212,15 @@ export function runCodexInitTests(check: Check): void { && entry(modifiedPlan, '.omp-flow/wiki/specs/index.md')?.action === 'skip', 'update preserves a pre-existing user-owned Wiki specs index as a visible conflict', ); + check( + entry(modifiedPlan, customizedLayout)?.status === 'changed' + && entry(modifiedPlan, customizedLayout)?.action === 'skip' + && missingLayouts.every(relativePath => + entry(modifiedPlan, relativePath)?.status === 'new' + && entry(modifiedPlan, relativePath)?.action === 'create', + ), + 'update preserves a customized code layout while planning the missing nested layouts', + ); executeUpdate(modifiedRoot, modifiedPlan, loadHashes(modifiedRoot)); check( fs.readFileSync(path.join(modifiedRoot, '.codex', 'hooks.json'), 'utf8') === userModifiedHook, @@ -210,6 +231,13 @@ export function runCodexInitTests(check: Check): void { === userWikiSpecsIndex, 'update never overwrites the customized Wiki specs index', ); + check( + fs.readFileSync(path.join(modifiedRoot, customizedLayout), 'utf8') === userCodeLayout + && missingLayouts.every(relativePath => + fs.statSync(path.join(modifiedRoot, relativePath)).isFile(), + ), + 'update keeps project code-layout edits and installs every missing sibling layout', + ); } finally { fs.rmSync(freshRoot, { recursive: true, force: true }); fs.rmSync(foreignRoot, { recursive: true, force: true });