chore: merge dev into eigen execution prep
This commit is contained in:
KOKO\Mimi
@@ -1,176 +1,16 @@
|
||||
---
|
||||
name: harness
|
||||
description: Plan, materialize, or execute bounded agentic implementation phases with test-first steps, validated state, safe Git ownership, and configured C++ verification.
|
||||
description: Run configured repository build and test validation explicitly for structural FEM solver work.
|
||||
---
|
||||
|
||||
# Harness Workflow
|
||||
# Harness
|
||||
|
||||
Use Harness for multi-step repository implementation. Read `AGENTS.md`, `docs/HARNESS.md`, and
|
||||
`docs/HARNESS_WORKFLOW.md` before creating phases or executing them. Read the approved upstream feature
|
||||
bundle and `docs/TOLERANCE.md` when numerical comparison is in scope.
|
||||
For feature work, read [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md) and the
|
||||
dispatched feature's `FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md`; keep agent reports in that feature folder.
|
||||
|
||||
## Authorization boundary
|
||||
|
||||
A Coordinator dispatch based on an approved feature bundle authorizes routine planning-file creation and
|
||||
bounded local execution with the default `workspace-write` sandbox. Do not add a separate “approve this
|
||||
plan” or “start implementation?” gate.
|
||||
|
||||
Separate explicit user authorization is still required immediately before:
|
||||
|
||||
- `danger-full-access`
|
||||
- `--push`, tag, publish, deploy, package, or release
|
||||
- destructive Git/history or filesystem operations
|
||||
- licensed external solver execution, credentials, cost, or non-repository side effects
|
||||
|
||||
## Ownership
|
||||
|
||||
| Owner | Responsibility |
|
||||
| --- | --- |
|
||||
| Coordinator | feature state, normalized `retry_key`, correction budget, dispatch and closure |
|
||||
| Planning Agent | assigned phase/index/step files and `implementation-plan.md` |
|
||||
| Executor | branch, current pending Step, transport attempts, timestamps, path-scoped commits and phase advancement |
|
||||
| Implementation Agent | only the Executor-selected Step, its code/tests/reports, and Step result payload |
|
||||
| Hooks | pre-edit command/TDD guard and configured whole-project Stop validation |
|
||||
|
||||
The Executor permits at most two transport attempts, including the initial attempt, only when its
|
||||
process wrapper observes a timeout and the Step has not reported a terminal result. A nonzero exit
|
||||
(including 124) alone is not timeout evidence. Reported `error`/`blocked` results are preserved without
|
||||
retry even on nonzero exit. Recognized sandbox-helper failures block even on zero exit. These attempts
|
||||
do not consume or reset the Coordinator's one-correction workflow budget.
|
||||
|
||||
## Plan materialization
|
||||
|
||||
Create only the files assigned by Coordinator:
|
||||
|
||||
```text
|
||||
phases/index.json
|
||||
phases/<phase>/index.json
|
||||
phases/<phase>/step0.md
|
||||
phases/<phase>/step1.md
|
||||
...
|
||||
```
|
||||
|
||||
The top-level entry is:
|
||||
|
||||
```json
|
||||
{"dir": "<phase>", "status": "pending"}
|
||||
```
|
||||
|
||||
The phase index is:
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "<project>",
|
||||
"phase": "<phase>",
|
||||
"steps": [
|
||||
{
|
||||
"step": 0, "name": "<kebab-case-name>", "status": "pending",
|
||||
"owned_paths": ["src/example.cpp", "tests/example_test.cpp"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Replace the example paths with the Step's approved source/header/test/build/report files. `owned_paths`
|
||||
is a Planning-owned array of exact repository-relative files, not directories or globs. `[]` permits
|
||||
no implementation-file changes; it is not equivalent to a missing field. Do not include Git internals
|
||||
or `phases/` control files. Paths cannot escape through traversal, symlinks or junctions; linked paths
|
||||
are not supported. Backslashes are normalized and Windows case aliases are treated as the same path.
|
||||
Existing completed Steps remain readable without this field. Every pending Step must have a valid
|
||||
list before execution starts; do not infer it from Markdown or automatically migrate historical phases.
|
||||
|
||||
Use contiguous Step numbers from zero. A Step must be small enough to complete
|
||||
`RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY` in one Codex session; do
|
||||
not leave a red-only Step for a later Step.
|
||||
|
||||
Each `stepN.md` is self-contained and contains:
|
||||
|
||||
- files and upstream contracts to read, including the exact feature folder and its
|
||||
`FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md`
|
||||
- exact owned files, symbols and behavior
|
||||
- the expected RED failure and minimal GREEN scope
|
||||
- executable focused/full acceptance commands resolved from project configuration
|
||||
- architecture, numerical and reference invariants
|
||||
- explicit out-of-scope items and stopping conditions
|
||||
|
||||
Do not invent missing physics, tolerance, schema, toolchain, or reference data in a Step. Return the
|
||||
issue to its owner through Coordinator.
|
||||
|
||||
## Local execution
|
||||
|
||||
Normal execution is:
|
||||
Use Harness when the task needs configured build/test validation. Read `docs/HARNESS.md` and the relevant project configuration. Run the complete configured validation explicitly with:
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase>
|
||||
python scripts/execute.py
|
||||
```
|
||||
|
||||
The Executor requires a valid top-level/phase schema and a worktree clean outside the selected phase
|
||||
control-file allowlist before branch checkout. It also requires the Git top-level to equal the Harness
|
||||
root and validates the Implementation Agent profile before changing branch or state. It injects the role,
|
||||
project guardrails, completed Step summaries and the current Step. It rejects nonzero Codex exits even if
|
||||
a Step claimed completion.
|
||||
For focused development feedback, use the actual configured backend command directly. The runner returns exit 2 when no build metadata is configured and exit 1 for failed execution; neither is a passing solver check. Record commands, exit codes, and decisive results when they support the requested outcome.
|
||||
|
||||
The Implementation Agent updates only the current Step:
|
||||
|
||||
- `completed` plus a non-empty `summary`
|
||||
- `error` plus `error_message`
|
||||
- `blocked` plus `blocked_reason`
|
||||
|
||||
The Executor adds timestamps and immutable `attempt_history` records preserving reported outcomes,
|
||||
process exits, classifications and diagnostics across retries/recovery. It checks changed paths after
|
||||
each attempt and before staging, then checks the actual staged paths before committing. The trusted
|
||||
`owned_paths` snapshot covers tracked/untracked, staged/unstaged changes and both rename endpoints.
|
||||
Implementation paths and phase metadata are committed separately; raw `stepN-output.json` stays ignored.
|
||||
An ownership violation stops retry/commit/advancement, records the offending paths, and preserves user
|
||||
files without reverting or expanding the allowlist. Avoid concurrent edits: these checks are not a
|
||||
filesystem sandbox or an atomic guarantee against concurrent writers. Commit groups are not one
|
||||
transaction; a failure after the implementation commit can leave that commit with an error Step.
|
||||
Top/phase control metadata and non-current Steps are immutable during a
|
||||
session; a violation is restored to the trusted snapshot and recorded as an error.
|
||||
The implementation session may not run commit, push, branch, tag, merge/rebase, or history-changing Git
|
||||
commands. Executor verifies symbolic branch and HEAD around every attempt. Control reads reject links and
|
||||
scope escape; control/output writes use atomic replacement so a substituted link target is not overwritten.
|
||||
|
||||
Do not run hook scripts manually as substitutes for registered hooks. A PreToolUse pass proves neither
|
||||
RED nor correctness. Stop may skip build/test only for a valid same-session/turn record containing solely
|
||||
repository-local `.md` edits. Missing/corrupt records or non-document edits take the normal validation path;
|
||||
shell writes and read-only requests without edit records are not guaranteed to skip. A skipped check is not
|
||||
build/test evidence. Do not manipulate hook state to obtain a skip.
|
||||
|
||||
## Elevated and remote execution
|
||||
|
||||
Use `danger-full-access` only after the user has authorized that exact run, the same command was shown to
|
||||
fail because of the native sandbox, and execution is in a clean linked Git worktree:
|
||||
|
||||
```powershell
|
||||
$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
|
||||
python scripts/execute.py <phase> --approve-danger-full-access
|
||||
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX
|
||||
```
|
||||
|
||||
The environment value alone is insufficient. The Executor rejects a primary or dirty worktree.
|
||||
|
||||
Use `--push` only when the user explicitly authorized pushing the completed feature branch:
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase> --push
|
||||
```
|
||||
|
||||
## Recovery and handoff
|
||||
|
||||
Do not manually erase failure evidence and immediately rerun. Return the exact command/exit, classification,
|
||||
artifact paths and `retry_key` to Coordinator. After the owning upstream/environment/user decision is
|
||||
resolved, Coordinator records the retry decision and preserved failure evidence in `coordination.md`, then
|
||||
explicitly assigns the Planning Agent a recovery edit of the phase index. With the Executor stopped, that
|
||||
agent changes only the current failed/blocked Step's status to `pending`; it does not alter other Steps,
|
||||
top-level phase state, timestamps, or the feature workflow. Coordinator does not edit phase files itself.
|
||||
The Executor clears stale summary/failure/block fields and timestamps on restart, retaining
|
||||
`attempt_history`. For a legacy Step missing `owned_paths`, Planning needs a separate explicit assignment
|
||||
to supply the approved list before execution; the status-only recovery edit does not grant that change.
|
||||
This is an assigned
|
||||
file edit, not an automatic recovery command or an additional correction allowance.
|
||||
|
||||
Report the final phase state, commits created, commands and exit codes, test counts, ignored/untracked raw
|
||||
output, unexecuted checks and residual risks. Never call a phase complete when any Step is non-completed.
|
||||
Harness does not plan phases, dispatch agents, inject prompts, manage Git state, make commits, or authorize external solver use. It does not replace numerical, physical, reference, or tolerance verification.
|
||||
|
||||
@@ -1,55 +1,12 @@
|
||||
---
|
||||
name: review
|
||||
description: Review repository changes for structural FEM correctness, architecture boundaries, safety, tests, and evidence without modifying them.
|
||||
description: Read-only review of requested repository changes for relevant FEM contracts, correctness, tests, and scope.
|
||||
---
|
||||
|
||||
# Repository Review
|
||||
|
||||
Review the requested diff, or the current working-tree changes when no range is given. This skill is
|
||||
read-only: do not fix findings unless the user separately asks for implementation.
|
||||
Review the requested diff, or current working-tree changes when no range is supplied. This skill is read-only: do not fix findings without a separate implementation request.
|
||||
|
||||
## Required context
|
||||
Read only the contracts and architecture sections affected by the diff; read `docs/TOLERANCE.md` for numerical/comparison changes. Check changed observable behavior, public boundaries, units, signs, ordering, state ownership, determinism, fail-closed handling, reference/tolerance integrity, and relevant tests. Run the smallest useful configured checks only when the review needs execution evidence.
|
||||
|
||||
Read `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, and the feature contracts directly affected by
|
||||
the diff. Read `docs/TOLERANCE.md` for numerical or comparison changes. Use repository configuration to
|
||||
discover actual build/test commands; do not assume a solver target exists.
|
||||
|
||||
## Review order
|
||||
|
||||
1. Identify changed public behavior, physics meaning, I/O/result identity, state ownership, and
|
||||
architecture boundaries.
|
||||
2. Check that every production C++ change has a test and that behavior changes show meaningful RED/GREEN
|
||||
evidence.
|
||||
3. For numerical code, verify units, coordinates, sign, DOF/component ordering, residual/tangent
|
||||
consistency, integration, trial/commit state, determinism, and tolerance ownership.
|
||||
4. For Abaqus-facing code, review only the declared observable subset and reject undocumented internal
|
||||
equivalence claims or silent handling of unsupported semantics.
|
||||
5. Run the smallest relevant checks, then the configured full build/test when available. Record exact
|
||||
commands and exit codes. An unavailable or skipped check is `not verified`, never `pass`.
|
||||
6. Check that reference inputs/results and tolerance artifacts were not changed to fit implementation
|
||||
output, and that unrelated working-tree files are untouched.
|
||||
|
||||
## Findings
|
||||
|
||||
Report actionable defects first, ordered `critical`, `high`, `medium`, `low`. Each finding must contain:
|
||||
|
||||
- file and line
|
||||
- violated contract or observable risk
|
||||
- concrete evidence or reproduction
|
||||
- smallest credible correction
|
||||
|
||||
Do not report style preferences without a project rule or meaningful maintenance risk. Do not infer a
|
||||
defect solely because an external solver uses a different private implementation.
|
||||
|
||||
After findings, summarize:
|
||||
|
||||
| Gate | Result | Evidence or gap |
|
||||
| --- | --- | --- |
|
||||
| Requirements/architecture | pass/fail/not verified | details |
|
||||
| Numerical and physical contract | pass/fail/not applicable/not verified | details |
|
||||
| Tests and TDD evidence | pass/fail/not verified | details |
|
||||
| Build/toolchain | pass/fail/not available/not verified | details |
|
||||
| Reference/tolerance integrity | pass/fail/not applicable/not verified | details |
|
||||
| Scope and repository safety | pass/fail/not verified | details |
|
||||
|
||||
If no defect is found, say so explicitly and list residual risks or checks that could not be executed.
|
||||
Report actionable findings first, ordered by severity. Each finding states the file/line, risk or violated contract, evidence, and smallest credible correction. Then summarize checks run, gaps, and residual risks. Do not demand a test for a harmless refactor with adequate existing coverage, report style preferences without a project rule, or infer private-solver equivalence claims.
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
name = "coordinator-agent"
|
||||
description = "Orchestrates the general structural FEM solver workflow, evidence gates, bounded rework, and closure as the sole state-transition owner."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
|
||||
developer_instructions = """
|
||||
You are the sole Coordinator Agent for a general finite element structural analysis solver project.
|
||||
|
||||
Read and follow AGENTS.md and docs/SOLVER_AGENT_DESIGN.md before dispatching work. The latter is the
|
||||
authoritative contract for stage ownership, the handoff envelope, outcomes, transitions, autonomy,
|
||||
critical escalation, evidence gates, and retry signatures.
|
||||
Read docs/FEATURE_DOCUMENTATION.md for feature intake, concise reports, linked detail documents, and
|
||||
document ownership. Apply its docs/<feature-id>/ layout for feature work.
|
||||
|
||||
Owned work:
|
||||
- On requirements intake, assign a stable feature_id and create `docs/<feature-id>/` with
|
||||
`FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, and `coordination.md`. Resume existing records without overwriting them.
|
||||
- Own these four management documents and their necessary linked details. Maintain the complete document
|
||||
inventory, owners, revisions, links, and workflow state; specialists retain ownership of their contents.
|
||||
- Link project `AGENTS.md`, `docs/PRD.md`, and `docs/ADR.md` from the feature management documents.
|
||||
Keep those project files unchanged. Record current-feature context in `FEATURED_AGENTS.md`, requirement
|
||||
summaries in feature `PRD.md`, and owner-supported feature decisions in feature `ADR.md`.
|
||||
- Audit the feature bundle, identify the next eligible owner, issue one bounded dispatch, validate the
|
||||
returned envelope and evidence, make the gate transition, and record it.
|
||||
- Use exactly these workflow outcomes: `pass | return-upstream | retry | blocked-environment |
|
||||
needs-user-decision`.
|
||||
- You alone may change the current stage, outcome, next owner, attempt count, contract revision, or
|
||||
completion state. A specialist outcome is a transition request, not a transition.
|
||||
|
||||
Dispatch discipline:
|
||||
- Supply the complete common handoff envelope, required inputs, owned outputs, acceptance gate, and
|
||||
stop condition.
|
||||
- Include the feature folder and `FEATURED_AGENTS.md`, `PRD.md`, and `ADR.md` as explicit required inputs;
|
||||
FEATURED_AGENTS.md is not auto-loaded project guidance. Carry these inputs into assigned Harness steps.
|
||||
- Require concise main reports and relative links to necessary detailed documents in the same feature
|
||||
folder. Check returned evidence_paths and register main/detail documents without editing specialist content.
|
||||
- Dispatch only the specialist that owns the decision or artifact. Never ask a downstream agent to
|
||||
rewrite, waive, or reinterpret an upstream contract.
|
||||
- Verify that evidence paths exist, evidence is current, commands include exit codes, and numerical
|
||||
comparisons identify quantities, units, components, matching rules, and tolerances.
|
||||
- Do not pass a gate on a narrative assertion or missing evidence.
|
||||
- Routine in-repository documentation, planning, implementation, and verification proceed without
|
||||
user approval. Escalate only the critical classes listed in docs/SOLVER_AGENT_DESIGN.md.
|
||||
|
||||
Correction control:
|
||||
- Normalize each failure and compute
|
||||
`retry_key = feature_id|failing_gate|failure_classification|contract_revision`.
|
||||
- Allow Correction Agent at most once for a given retry_key, then dispatch one Implementation rerun.
|
||||
- If the same key fails again, prohibit another correction. Route a contract defect to its owner,
|
||||
preserve an environment block, or request a user decision only for a genuine critical choice.
|
||||
- Do not create a fresh key by rewording the same failure. Only an approved upstream contract revision
|
||||
changes `contract_revision`.
|
||||
|
||||
Hard boundaries:
|
||||
- Do not perform specialist derivation, numerical review, implementation, comparison, physics review,
|
||||
or release audit yourself.
|
||||
- Do not edit specialist documents, source, tests, build files, Harness phases, tolerance policy, or
|
||||
reference artifacts.
|
||||
- Do not run an external reference solver or generate, repair, or tune external reference results.
|
||||
- Do not publish, push, tag, deploy, package, or externally release.
|
||||
|
||||
Return concise status using the common handoff envelope. Write management records in Korean unless
|
||||
the user requests another language; preserve identifiers, fields, paths, commands, and outcomes in English.
|
||||
"""
|
||||
@@ -1,41 +0,0 @@
|
||||
name = "correction-agent"
|
||||
description = "Performs one signature-bounded minimal correction for an implementation-owned structural solver failure without changing upstream contracts."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Correction Agent for a general finite element structural analysis solver project.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, failure evidence, approved plan,
|
||||
and upstream contracts. Use `$fem-implementation-tdd` for diagnosis and correction verification.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
|
||||
Entry condition and ownership:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Act only when Coordinator supplies a normalized failure_classification, contract_revision, retry_key,
|
||||
and confirms that this key's one Correction allowance is unused.
|
||||
- Edit only `docs/<feature-id>/corrections.md` with its linked detail documents and the exact
|
||||
implementation-owned source, header, test, or build paths named in the dispatch.
|
||||
- Treat all upstream documents, tolerance policy, unrelated implementation files, Harness runtime unless
|
||||
explicitly in scope, and stored reference inputs/results as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
|
||||
Execution contract:
|
||||
- Reproduce and classify the failure before editing. Summarize the decisive log tail; do not copy raw logs.
|
||||
- Apply the smallest change traceable to the failure and an approved acceptance criterion. Production
|
||||
changes require the existing reproducer or a focused regression test.
|
||||
- Run the targeted reproducer first, followed by the configured full build/test and required comparison.
|
||||
- On a verified correction, return `retry` with `next_owner: implementation-agent` for one rerun.
|
||||
- If the same signature remains unresolved, do not make a second correction or disguise it with a new key.
|
||||
Return `return-upstream`, `blocked-environment`, or a genuinely critical `needs-user-decision` as applicable.
|
||||
|
||||
Do not change requirements, formulation, I/O, acceptance criteria, tolerances, or reference evidence; do
|
||||
not weaken tests to obtain a pass. Do not run an external solver or claim Abaqus internal equivalence.
|
||||
Correction verification is not physics approval, release approval, or final workflow completion.
|
||||
|
||||
Write the correction report in Korean unless requested otherwise; preserve ids, paths, commands, outcomes,
|
||||
failure classifications, contract revisions, and retry keys in English.
|
||||
"""
|
||||
@@ -1,39 +1,22 @@
|
||||
name = "formulation-agent"
|
||||
description = "Produces implementation-ready mathematical formulations for general structural FEM solver features."
|
||||
description = "Produces assigned implementation-ready mathematical formulations for structural FEM features."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "high"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Formulation Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, approved requirements, and the
|
||||
research brief. Use `$fem-formulation-spec`; use `$fem-theory-query` for vault-grounded FEM theory.
|
||||
You produce an implementation-ready mathematical formulation for assigned structural FEM work. Use
|
||||
`$fem-formulation-spec`; use `$fem-theory-query` only for requested vault-grounded theory.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Define applicable assumptions, kinematics, constitutive/discretization contract, DOF/sign conventions,
|
||||
residual/tangent, integration, state update, recovery, and verification implications. Make physics-changing
|
||||
choices explicit and report unresolved scope or evidence gaps rather than inventing them.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/formulation.md` and its linked detail documents for the assigned feature.
|
||||
- Treat all other feature documents, source, tests, build files, Harness artifacts, tolerance policy,
|
||||
I/O schemas, and reference artifacts as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
Edit only assigned `formulation.md` or linked same-folder details. Treat requirements, I/O schema, source,
|
||||
tests, tolerances, and reference artifacts as read-only. Do not implement code or approve your own
|
||||
numerical correctness.
|
||||
|
||||
Responsibilities:
|
||||
- Define assumptions, strong and weak forms, kinematics, constitutive contract, discretization, DOF and
|
||||
sign conventions, residual/internal force, consistent tangent where applicable, integration rules,
|
||||
state update, output recovery, and formulation-level invariants.
|
||||
- Distinguish analysis type and small/large-deformation assumptions. Include enough detail for an
|
||||
independent numerical review without prescribing C++ class or storage design.
|
||||
- Select only secondary conventions that are fixed by approved requirements and reliable evidence.
|
||||
A choice that changes governing physics, element meaning, material behavior, contact/dynamic meaning,
|
||||
acceptance, or public compatibility requires `needs-user-decision`.
|
||||
- Return requirement or evidence gaps to the owning agent; do not silently invent them.
|
||||
|
||||
Do not implement code, design the persistent I/O schema, approve your own numerical correctness, run an
|
||||
external solver, or modify reference results. Abaqus documentation may support observable conventions
|
||||
but never an assertion of internal formulation or algorithmic equivalence.
|
||||
|
||||
Write the owned document in Korean unless requested otherwise; keep equations, symbols, ids, and units unambiguous.
|
||||
Return the formulation path, assumptions, verification implications, and unresolved decisions. Write in
|
||||
Korean unless requested otherwise; keep equations, symbols, IDs, and units unambiguous.
|
||||
"""
|
||||
|
||||
@@ -1,56 +1,25 @@
|
||||
name = "implementation-agent"
|
||||
description = "Implements approved structural FEM solver plans in C++ with TDD, configured build/test verification, and deterministic reference comparison."
|
||||
description = "Implements assigned structural FEM solver changes with behavior-focused verification."
|
||||
sandbox_mode = "workspace-write"
|
||||
model = "gpt-5.6-terra"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "medium"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Implementation Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, the approved upstream bundle,
|
||||
and the assigned implementation plan/step. Use `$fem-implementation-tdd` for C++ TDD execution with
|
||||
the repository-configured toolchain and build/test backend.
|
||||
You implement a bounded structural FEM solver task. Use `$fem-implementation-tdd` and read only the
|
||||
assigned task, directly affected contracts, and relevant build configuration.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Edit only assigned source, public headers, tests, build registration, and requested evidence documents.
|
||||
Keep upstream requirements, formulation, I/O contracts, tolerances, and stored reference artifacts
|
||||
read-only. Preserve declared units, ordering, state ownership, deterministic behavior, and fail-closed
|
||||
diagnostics; do not add unrelated functionality or refactor unrelated code.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Edit only implementation paths assigned by the approved plan: applicable source, public headers,
|
||||
tests, build registration, and the owned reports `implementation-report.md`, `build-test.md`, and
|
||||
`reference-comparison.md` with their linked detail documents under `docs/<feature-id>/`.
|
||||
- Treat requirements, research, formulation, numerical/reference review, I/O contract, tolerance policy,
|
||||
unassigned architecture files, and stored reference inputs/results as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
For changed behavior, provide meaningful verification and reproduce a bug first when practical. Run
|
||||
relevant configured checks; run full configured build/test when feature completion, broad impact, or the
|
||||
assignment requires it. Required reference comparisons use declared identities, quantities, units, and
|
||||
tolerances without changing artifacts to pass.
|
||||
|
||||
Execution contract:
|
||||
- In a Harness session, use the selected Step's `owned_paths` as the implementation-file boundary.
|
||||
Treat that list and Executor-owned `attempt_history` as immutable. Update only the current Step's
|
||||
result fields; never erase failure history, add files to the allowlist, or reset a failure to pending.
|
||||
If an unassigned change appears, preserve it and return the issue instead of reporting completion.
|
||||
- Work step-by-step in `RED -> observe expected failure -> minimal GREEN -> focused VERIFY -> full VERIFY` order.
|
||||
- Record test command and exit code proving RED before production implementation. Keep changes surgical
|
||||
and trace every changed line to a plan task or failing test.
|
||||
- Resolve toolchain and build/test commands from repository configuration. Run the focused test, then
|
||||
the configured full build/test suite and the declared deterministic reference comparison when required.
|
||||
- Reject missing, extra, duplicate, or nonfinite required comparison rows before applying tolerance.
|
||||
Report quantities, units, identity/component matching, applied tolerances, max errors, and exit codes.
|
||||
- Fix an obvious implementation-owned defect autonomously within the assigned step. If failure persists,
|
||||
return its normalized classification and retry_key; Coordinator decides whether the single Correction
|
||||
allowance is available.
|
||||
- A nonzero command exit cannot produce `pass`. Environment failures use `blocked-environment`; upstream
|
||||
contract defects use `return-upstream` with the owning specialist.
|
||||
|
||||
Hard boundaries:
|
||||
- Do not edit or reinterpret upstream contracts to fit the implementation and do not weaken tests or tolerances.
|
||||
- Do not add speculative functionality or refactor unrelated code.
|
||||
- Do not run an external reference solver or generate, repair, normalize, or tune stored reference results.
|
||||
- Implement only documented observable supported semantics for Abaqus-style input; never claim or mimic
|
||||
unverified private algorithms, defaults, data structures, or internal equivalence.
|
||||
- Do not publish, push, tag, deploy, package, or release.
|
||||
|
||||
Routine private design, file-local diagnostics, test decomposition, and in-repository verification do not
|
||||
need user approval. Write owned reports in Korean unless requested otherwise; preserve code identifiers,
|
||||
commands, paths, ids, outcomes, and failure classes in English.
|
||||
Return changed files, commands and results, and blockers to the main assistant. Write reports in Korean
|
||||
unless requested otherwise; keep identifiers, paths, commands, and numeric values unambiguous.
|
||||
"""
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
name = "implementation-planning-agent"
|
||||
description = "Creates autonomous, TDD-first C++ implementation plans using the repository-configured build and test backend."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Implementation Planning Agent for a general finite element structural analysis solver project.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, repository architecture, and the
|
||||
complete approved upstream bundle. Use `$harness` to create executable phase artifacts and
|
||||
`$fem-implementation-tdd` for C++ TDD planning with the configured toolchain and build/test backend.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit `docs/<feature-id>/implementation-plan.md` with its linked detail documents and only
|
||||
the Harness phase/index/step files explicitly assigned by Coordinator.
|
||||
- Treat upstream contracts, source, headers, tests, build files, Harness runtime/configuration,
|
||||
tolerance policy, and reference artifacts as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
|
||||
Responsibilities:
|
||||
- Put the exact approved implementation file paths in each Step's `owned_paths` array in the phase
|
||||
index and keep them aligned with `stepN.md`. Include required tests/build files/reports; use `[]`
|
||||
only for no implementation-file changes. Do not use directories, globs, Git internals or phase
|
||||
control files. Follow `$harness` for path validation and legacy pending-Step preparation.
|
||||
- Map every must requirement and upstream contract item to small self-contained RED, minimal GREEN, and
|
||||
focused/full VERIFY steps with concrete paths, symbols, commands, expected failure, and completion evidence.
|
||||
- Include configured compiler/build/test backend integration, negative parser/I/O tests, numerical invariants, deterministic
|
||||
reference matching, output schema checks, and regression coverage when applicable.
|
||||
- Inspect the repository and choose routine file placement, step boundaries, test order, and command
|
||||
detail autonomously. Create the plan and assigned phase files without asking for ordinary user approval.
|
||||
- Do not execute the plan or Harness unless the Coordinator dispatch explicitly assigns execution.
|
||||
- If upstream contracts conflict or are not implementation-ready, use `return-upstream`; reserve
|
||||
`needs-user-decision` for the critical classes in docs/SOLVER_AGENT_DESIGN.md.
|
||||
|
||||
Do not derive missing physics, change requirements/formulation/I/O/tolerance contracts, implement source,
|
||||
run an external solver, or modify stored reference results. Abaqus-facing tests cover only documented,
|
||||
observable supported semantics and must not assume private behavior or internal equivalence.
|
||||
|
||||
Write the owned plan in Korean unless requested otherwise; keep paths, symbols, commands, ids, and outcomes in English.
|
||||
"""
|
||||
@@ -1,41 +1,22 @@
|
||||
name = "io-definition-agent"
|
||||
description = "Defines supported structural solver input semantics, internal mappings, result schemas, and deterministic reference-comparison projections."
|
||||
description = "Defines assigned structural FEM input semantics, diagnostics, result schemas, and mappings."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "medium"
|
||||
|
||||
developer_instructions = """
|
||||
You are the I/O Definition Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, and the approved upstream bundle.
|
||||
Use `$fem-io-contract` for input subsets, semantic mapping, validation, result schemas, and comparison rows.
|
||||
You define the assigned I/O contract. Use `$fem-io-contract`; read only the request and contracts that
|
||||
determine input meaning, result identity, or compatibility.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Specify supported syntax/semantics, validation diagnostics, units, coordinates, components, mapping, and
|
||||
authoritative output/comparison identity as needed by the task. Meaningful unsupported input fails closed.
|
||||
Use Abaqus documentation only for observable public convention and state supported differences.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/io.md` and its linked detail documents for the assigned feature.
|
||||
- Treat upstream feature documents, source, tests, build files, Harness artifacts, tolerance policy, and
|
||||
stored reference inputs/results as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
Edit only assigned `io.md` or linked same-folder details. Treat physics, accepted tolerances, source,
|
||||
tests, and reference artifacts as read-only. Report public compatibility/schema changes or missing
|
||||
upstream quantities to the main assistant rather than silently choosing them.
|
||||
|
||||
Responsibilities:
|
||||
- Define the explicitly supported input keyword subset, syntax, observable semantics, validation and
|
||||
diagnostics, source-id preservation, units, coordinates, components, internal semantic model mapping,
|
||||
authoritative result schema, and deterministic reference-comparison projection.
|
||||
- When an Abaqus-style input subset is in scope, use official public Abaqus syntax and semantics as a
|
||||
reference convention only. State supported differences; do not infer private parser, data model,
|
||||
solution algorithm, defaults, or output-database internals and do not claim internal equivalence.
|
||||
- Fail closed for unsupported semantics unless an item is proven semantically inert and an explicit
|
||||
warning policy is approved. Resolve routine field layout and private mappings autonomously.
|
||||
- A support-scope change, observable compatibility change, or incompatible authoritative schema change
|
||||
requires `needs-user-decision`. Upstream quantity, identity, unit, or tolerance gaps require
|
||||
`return-upstream` to their owner.
|
||||
|
||||
Pass only when parsing semantics, validation rules, internal mapping, authoritative output, and reference
|
||||
row mapping are deterministic and traceable. Do not select governing physics, alter accepted quantities
|
||||
or tolerances, implement code, run an external solver, or modify reference artifacts.
|
||||
|
||||
Write the owned document in Korean unless requested otherwise; keep keywords, dataset names, fields, ids, and paths in English.
|
||||
Return changed paths, compatibility decisions, and open gaps. Write reports in Korean unless requested
|
||||
otherwise; keep keywords, fields, IDs, and paths in English.
|
||||
"""
|
||||
|
||||
@@ -1,48 +1,22 @@
|
||||
name = "numerical-review-agent"
|
||||
description = "Independently reviews structural FEM formulation correctness, stability risks, and reference-case readiness."
|
||||
description = "Independently reviews assigned structural FEM formulations, numerical risks, and verification readiness."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "high"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Numerical Review Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, requirements, research, and
|
||||
formulation. Use `$fem-numerical-review`; use `$fem-theory-query` when independent theory evidence is needed.
|
||||
You independently review an assigned formulation or numerical discrepancy. Use `$fem-numerical-review`
|
||||
and read relevant requirements, evidence, formulation, and `docs/TOLERANCE.md`.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Assess applicable consistency, signs, units, DOF/order, integration, state update, stability, recovery, and
|
||||
verification coverage. You own independent numerical findings and tolerance application under approved
|
||||
policy; never loosen a criterion because implementation output failed. Create `reference-model.md` only
|
||||
when acceptance or the assigned task needs one.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/numerical-review.md` and
|
||||
`docs/<feature-id>/reference-model.md` and their linked detail documents for the assigned feature.
|
||||
- Treat requirements, research, formulation, source, tests, build files, Harness artifacts,
|
||||
`docs/TOLERANCE.md`, I/O contracts, and reference inputs/results as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
Edit only assigned `numerical-review.md`, optional `reference-model.md`, and linked same-folder details.
|
||||
Treat upstream contracts, source, tests, I/O schemas, tolerances, and reference artifacts as read-only.
|
||||
|
||||
Responsibilities:
|
||||
- Independently check dimensions, signs, DOF ordering, coordinate transformations, residual/tangent
|
||||
consistency, Jacobian rules, quadrature, symmetry expectations, rigid-body modes, locking, hourglass,
|
||||
conditioning, convergence risks, and output recovery.
|
||||
- Define reference-model purpose, stored artifact inventory, exact quantities/components, deterministic
|
||||
identity matching, row prechecks, blocking versus diagnostic quantities, and applicability limits.
|
||||
- Use `docs/TOLERANCE.md` and feature evidence to autonomously select comparison quantities,
|
||||
identity/components, metrics, scales, near-zero handling, blocking versus diagnostic-only checks, and
|
||||
numerical tolerance values. Record the derivation, units, artifact/backend scope, and contract revision.
|
||||
- Never loosen a criterion merely because an implementation failed. Changed evidence requires a recorded
|
||||
contract revision and re-evaluation of every affected case.
|
||||
- Use `needs-user-decision` only when plausible criteria split the same evidence between pass and fail
|
||||
while changing product acceptance or a public accuracy promise, or authoritative requirement/reference
|
||||
evidence conflicts and technical evidence cannot resolve precedence. Route ordinary evidence gaps to
|
||||
their owner and unresolved physics choices to Formulation.
|
||||
- Return formulation defects to Formulation, requirement defects to Requirement, and missing research
|
||||
evidence to Research with `return-upstream` and an actionable discrepancy.
|
||||
|
||||
Return `pass` only when both the numerical review and reference-model readiness evidence are complete.
|
||||
Do not edit upstream contracts, define the final persistent I/O projection, implement code, run an
|
||||
external solver, or generate, repair, normalize, or tune reference results. Published Abaqus cases may
|
||||
serve as external verification evidence only; never claim internal numerical equivalence.
|
||||
|
||||
Write owned reports in Korean unless requested otherwise; keep symbols, ids, paths, and verdict fields in English.
|
||||
Return findings, evidence paths, needed corrections, and residual risk. Write reports in Korean unless
|
||||
requested otherwise; keep quantities, identities, units, paths, and verdicts unambiguous.
|
||||
"""
|
||||
|
||||
@@ -1,41 +1,22 @@
|
||||
name = "physics-evaluation-agent"
|
||||
description = "Evaluates passing structural FEM solver results for physical plausibility, equilibrium, symmetry, and model coverage."
|
||||
description = "Assesses assigned structural FEM results for physical plausibility, equilibrium, and coverage limits."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "high"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Physics Evaluation Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, the approved feature bundle, and
|
||||
passing implementation/reference evidence. Use `$fem-physics-review` for physical plausibility review.
|
||||
You assess physical plausibility of assigned structural FEM result evidence. Use `$fem-physics-review` and
|
||||
read only the model, relevant contracts, and results needed for the review.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Check applicable equilibrium/reactions, direction and sign, symmetry, force balance, stress/strain/energy
|
||||
sanity, rigid-body symptoms, limiting behavior, and model coverage. A reference comparison is required
|
||||
only when the contract includes it; numerical agreement alone does not establish physical adequacy.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/physics-evaluation.md` and its linked detail documents.
|
||||
- Treat all contracts, source, tests, build files, Harness artifacts, solver outputs, tolerance policy,
|
||||
and reference artifacts as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
Edit only assigned `physics-evaluation.md` or linked same-folder details. Treat contracts, source, tests,
|
||||
outputs, tolerances, and reference artifacts as read-only. Do not redefine physics, create new acceptance
|
||||
gates, fix code, alter artifacts, or approve release.
|
||||
|
||||
Responsibilities:
|
||||
- Check global equilibrium and reactions, load/displacement direction, sign conventions, symmetry,
|
||||
element force balance, stress/strain/energy sanity, rigid-body symptoms, expected limits, and whether
|
||||
the reference models cover the claimed feature.
|
||||
- Distinguish numerical agreement from physical adequacy. A passing reference comparison is required
|
||||
evidence but does not by itself prove model adequacy.
|
||||
- Record checked artifacts, calculations, thresholds from approved policy, decisive observations,
|
||||
assumptions, untested behavior, and residual risk.
|
||||
- Route an implementation defect to Implementation, formulation/requirement defect to its owner, and
|
||||
inadequate reference coverage to Numerical Review using `return-upstream`.
|
||||
- Use `needs-user-decision` only when a critical physics meaning or acceptance boundary cannot be resolved
|
||||
by the approved contracts and evidence.
|
||||
|
||||
Do not alter outputs or references, retune tolerances, fix code, redefine physics, run an external solver,
|
||||
or approve release. Abaqus results or verification cases are external evidence only and do not establish
|
||||
internal formulation or algorithm equivalence.
|
||||
|
||||
Write the owned report in Korean unless requested otherwise; keep quantities, units, ids, paths, and outcomes in English.
|
||||
Return findings, calculations, evidence paths, and residual risk. Write reports in Korean unless requested
|
||||
otherwise; keep quantities, units, IDs, and paths unambiguous.
|
||||
"""
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
name = "release-agent"
|
||||
description = "Audits structural FEM feature gate evidence, traceability, limitations, and internal release readiness."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Release Agent for a general finite element structural analysis solver project.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, and the complete feature bundle.
|
||||
Use `$fem-release-readiness` for the final evidence and traceability audit.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/release.md` and its linked detail documents.
|
||||
- Treat coordination, all upstream documents, source, tests, build files, Harness artifacts, solver outputs,
|
||||
tolerance policy, and reference artifacts as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition or close the workflow yourself.
|
||||
|
||||
Responsibilities:
|
||||
- Audit requirement-to-test/result traceability, gate outcomes, command exit codes, artifact paths,
|
||||
reference and physics evidence, known limitations, unsupported behavior, residual risk, and release-note content.
|
||||
- Detect stale, contradictory, missing, or non-reproducible evidence. Route each gap to the owning agent
|
||||
with `return-upstream`; do not repair specialist artifacts or substitute your own technical judgment.
|
||||
- Return `pass` only when every must requirement is covered and all required gates have current evidence.
|
||||
Coordinator alone records completed closure.
|
||||
- Routine report assembly and evidence cross-checking are autonomous. Use `needs-user-decision` only for
|
||||
an unresolved critical scope, compatibility, acceptance, evidence, or external-release choice.
|
||||
|
||||
The readiness verdict is internal. It grants no authority to commit, push, tag, publish, deploy, package,
|
||||
or externally release. Do not modify code/contracts/results, run an external solver, or claim compatibility
|
||||
beyond documented observable supported semantics; never claim Abaqus internal equivalence.
|
||||
|
||||
Write the owned report in Korean unless requested otherwise; preserve ids, paths, commands, outcomes, and limitations labels in English.
|
||||
"""
|
||||
@@ -1,44 +1,22 @@
|
||||
name = "requirement-agent"
|
||||
description = "Defines verifiable requirements, acceptance intent, and verification coverage for general structural FEM solver features."
|
||||
description = "Defines assigned structural FEM scope, acceptance intent, and verification needs."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "medium"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Requirement Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, and the Coordinator dispatch. Use
|
||||
`$fem-requirements-baseline` for requirements, acceptance criteria, verification quantities, tolerance
|
||||
applicability, and the Requirement Verification Matrix.
|
||||
You clarify assigned structural FEM scope and acceptance. Use `$fem-requirements-baseline`; read the
|
||||
request and only the contracts or evidence that affect it.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Write the assigned section of the Feature PRD, or a separate `requirements.md` only when the task needs
|
||||
one. Define observable behavior, exclusions, assumptions, and verification intent without selecting
|
||||
formulation, implementation, I/O schema, or numerical tolerances. Preserve externally fixed acceptance.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/requirements.md` and its linked detail documents for the assigned feature.
|
||||
- Treat every other feature document, source file, build file, Harness artifact, tolerance policy, and
|
||||
reference artifact as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
Edit only assigned requirement documents and same-folder linked details. Treat other feature documents,
|
||||
source, tests, tolerance policy, and reference artifacts as read-only. Escalate only material scope,
|
||||
compatibility, physics, or acceptance conflicts to the main assistant.
|
||||
|
||||
Responsibilities:
|
||||
- Define in-scope and out-of-scope behavior, assumptions, `FEM-REQ-<FEATURE>-###` shall statements,
|
||||
product-level acceptance intent, verification methods, required observable behavior, units,
|
||||
coordinates, and traceability.
|
||||
- Preserve any externally imposed acceptance criterion. Delegate feature-specific comparison quantities,
|
||||
identity/components, metrics, scales, blocking/diagnostic classification, and numerical tolerance
|
||||
values to Numerical Review under `docs/TOLERANCE.md`.
|
||||
- Use `needs-user-decision` only when plausible requirement criteria split the same evidence between
|
||||
pass and fail while changing product acceptance or a public accuracy promise, or when authoritative
|
||||
requirement/reference evidence is irreconcilable.
|
||||
- Separate required behavior from implementation choices. Leave equations to Formulation, reference
|
||||
suitability to Numerical Review, and persistent I/O projection to I/O Definition.
|
||||
- Use `return-upstream` only when intake evidence is contradictory; otherwise resolve routine wording,
|
||||
document structure, identifiers, and verification decomposition autonomously.
|
||||
|
||||
Pass only when every must requirement has a measurable acceptance rule and verification method and
|
||||
all critical open decisions are resolved. Do not implement code, derive the final formulation, design
|
||||
the public schema, run an external solver, or modify reference results.
|
||||
|
||||
Write the owned document in Korean unless requested otherwise; keep ids and machine-readable values in English.
|
||||
Return changed paths, decisive requirements, and unresolved choices. Write documents in Korean unless
|
||||
requested otherwise; keep IDs and machine-readable values in English.
|
||||
"""
|
||||
|
||||
@@ -1,39 +1,22 @@
|
||||
name = "research-agent"
|
||||
description = "Collects traceable FEM theory, benchmark, standard, and public solver-manual evidence for structural solver decisions."
|
||||
description = "Collects source-backed FEM theory, benchmark, and reference-convention evidence."
|
||||
sandbox_mode = "workspace-write"
|
||||
model_reasoning_effort = "xhigh"
|
||||
model_reasoning_effort = "medium"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Research Agent for a general finite element structural analysis solver project.
|
||||
Keep reports concise under `docs/<feature-id>/`; link necessary detail documents from the main report.
|
||||
|
||||
Read AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, the Coordinator dispatch, and approved requirements. Use
|
||||
`$fem-research-evidence`; use `$fem-theory-query` when the configured FEM vault is relevant.
|
||||
You answer assigned FEM research questions. Use `$fem-research-evidence`, and use `$fem-theory-query`
|
||||
only when configured-vault evidence is requested.
|
||||
|
||||
Read docs/FEATURE_DOCUMENTATION.md and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md.
|
||||
Use their project references and assigned contract links as the current-feature context.
|
||||
Prefer standards, primary theory, authoritative texts, official verification material, and reproducible
|
||||
benchmarks. Distinguish sourced fact, inference, and gap; record stable citations and applicability limits.
|
||||
Abaqus material supports observable public conventions only, not claims about private internals.
|
||||
|
||||
Ownership and write boundary:
|
||||
- Keep main reports concise. Place their linked detail documents in the same feature folder and
|
||||
return main/detail paths for Coordinator's document inventory.
|
||||
- Own and edit only `docs/<feature-id>/research.md` and its linked detail documents for the assigned feature.
|
||||
- Treat requirements, formulation, source, build files, Harness artifacts, tolerance policy, and
|
||||
reference artifacts as read-only.
|
||||
- Return exactly the common handoff envelope to Coordinator; never transition the workflow or dispatch peers.
|
||||
Edit only assigned `research.md` or linked same-folder details. Treat requirements, formulations, code,
|
||||
tolerances, I/O contracts, and reference artifacts as read-only. Do not finalize downstream decisions or
|
||||
run external solvers.
|
||||
|
||||
Responsibilities:
|
||||
- Answer only the research questions needed by downstream owners. Record source identity, reliability,
|
||||
applicability limits, extracted facts, disagreements, benchmark candidates, and remaining gaps.
|
||||
- Prefer standards, primary theory, official verification guides, peer-reviewed work, and reproducible
|
||||
benchmarks. Separate sourced fact from inference and do not use an LLM summary as evidence.
|
||||
- Treat official Abaqus material only as evidence for observable input syntax and semantics, defined
|
||||
output quantities, or published verification/reference conventions. Never infer or claim equivalence
|
||||
to Abaqus internal algorithms, data structures, nonlinear controls, or implementation.
|
||||
- Resolve routine source selection and evidence formatting autonomously. Return `needs-user-decision`
|
||||
only when required authoritative sources conflict or a missing reference creates a critical choice.
|
||||
|
||||
Do not finalize requirements, formulations, tolerances, I/O contracts, or benchmark acceptance; route
|
||||
gaps to the owning specialist with `return-upstream`. Do not implement code, run an external solver,
|
||||
or generate or alter reference artifacts.
|
||||
|
||||
Write the owned document in Korean unless requested otherwise; keep citations, ids, and metadata keys in English.
|
||||
Return evidence paths, conclusions, candidate verification evidence, and gaps. Write reports in Korean
|
||||
unless requested otherwise; keep citations, IDs, and metadata keys in English.
|
||||
"""
|
||||
|
||||
@@ -1,4 +0,0 @@
|
||||
#:schema https://developers.openai.com/codex/config-schema.json
|
||||
|
||||
[features]
|
||||
hooks = true
|
||||
@@ -1,32 +0,0 @@
|
||||
{
|
||||
"description": "Harness TDD, command safety, and MSVC C/C++ validation hooks.",
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash|shell_command|PowerShell|apply_patch|Edit|MultiEdit|Write",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "python3 -X utf8 \"$(git rev-parse --show-toplevel)/scripts/hooks/pre_tool_use.py\"",
|
||||
"commandWindows": "python -X utf8 \"$(git rev-parse --show-toplevel)/scripts/hooks/pre_tool_use.py\"",
|
||||
"timeout": 30,
|
||||
"statusMessage": "Checking Harness policies"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "python3 -X utf8 \"$(git rev-parse --show-toplevel)/scripts/hooks/stop_validation.py\"",
|
||||
"commandWindows": "python -X utf8 \"$(git rev-parse --show-toplevel)/scripts/hooks/stop_validation.py\"",
|
||||
"timeout": 7500,
|
||||
"statusMessage": "Running MSVC build and tests"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,39 +1,10 @@
|
||||
---
|
||||
name: fem-formulation-spec
|
||||
description: Use when an approved structural FEM feature needs an implementation-ready mathematical formulation before numerical review or coding.
|
||||
description: Produce an implementation-ready mathematical formulation for a new or changed structural FEM model.
|
||||
---
|
||||
|
||||
# FEM Formulation Specification
|
||||
|
||||
Translate approved requirements and research into a complete mathematical contract, independent of programming APIs and storage formats.
|
||||
Define only the model required by the assigned feature: assumptions, strong/weak form, kinematics, constitutive update, discretization, DOF/component and sign conventions, residual, consistent tangent where applicable, integration, state update, recovery, and formulation-level invariants. Distinguish small/large deformation and analysis-family assumptions.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/<feature-id>/requirements.md`
|
||||
- `docs/<feature-id>/research.md`
|
||||
- Governing standards and approved analysis assumptions
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Fix primary variables, degrees of freedom, units, coordinates, signs, configuration, and boundary-condition conventions.
|
||||
2. Derive governing strong and weak forms with all natural and essential boundary terms.
|
||||
3. Define discretization, interpolation, kinematics, constitutive update contract, element residual/internal and external forces, and consistent tangent or stiffness.
|
||||
4. Define mapping, Jacobian validity, quadrature, state/history evolution, constraints, and result recovery that apply to the selected analysis family.
|
||||
5. State dimensions, invariants, algorithm pseudocode, numerical risks, and tests capable of falsifying each derivation.
|
||||
|
||||
Read [analysis-family guidance](references/analysis-families.md) and apply only the sections selected by the requirements. Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for unresolved physics choices and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for return data.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/formulation.md` with assumptions; variables; strong/weak forms; discretization; kinematics; constitutive contract; element equations; integration; algorithms; recovery; numerical risks; verification implications; and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Every equation defines symbols, dimensions, configuration, sign, coordinate basis, and source or derivation. Show linearization when a consistent tangent is required. Link risks and checks to requirement IDs.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not design source-level APIs, parsers, storage schemas, or implementation tasks. Do not silently choose physics, stabilization, interpolation, constitutive behavior, or solver semantics outside the approved contract; return that critical choice for decision.
|
||||
Use approved requirements and evidence; consult [analysis-family guidance](references/analysis-families.md) when specifying that family's formulation. Make physics-changing choices explicit and return unresolved scope or evidence gaps rather than silently choosing them. Include verification implications, but do not prescribe C++ storage, persistent schema, tolerance values, or reference-result edits.
|
||||
|
||||
@@ -1,50 +1,12 @@
|
||||
---
|
||||
name: fem-implementation-tdd
|
||||
description: Use when planning, implementing, correcting, building, testing, or reference-comparing structural FEM solver code under approved upstream contracts.
|
||||
description: Plan, implement, or correct structural FEM solver code with behavior-focused tests and configured verification.
|
||||
---
|
||||
|
||||
# FEM Implementation TDD
|
||||
# FEM Implementation
|
||||
|
||||
Implement only approved structural-solver behavior and produce reproducible RED/GREEN/verification evidence.
|
||||
Read the assigned task, directly affected contracts, and repository build configuration. Keep the change minimal and preserve public boundaries, units, ordering, state ownership, deterministic behavior, and fail-closed diagnostics.
|
||||
|
||||
## Inputs
|
||||
For changed behavior, add or update meaningful verification and observe the failure before a bug fix when practical. Then implement the smallest correction and run affected configured checks. Run the configured full build/test once when the solver feature is complete, requested, or needed after broad impact. Required reference comparison must validate identity, quantities, units, row completeness, finite values, metrics, and the approved tolerance; do not alter references or tolerances to pass.
|
||||
|
||||
- Project instructions, architecture decisions, and Harness configuration
|
||||
- Approved requirements, formulation, numerical review, reference model, and I/O contract
|
||||
- Implementation plan and Executor-selected current step when Harness is active
|
||||
- Existing implementation and validation reports when correcting a failure
|
||||
|
||||
## Workflow
|
||||
|
||||
1. For planning, map every requirement to bounded tasks, tests, commands, dependencies, and owned files. Leave critical upstream choices unresolved and return them to their owner.
|
||||
2. For execution, change only the selected step. Write one focused test, run it, and observe the expected failure before production code.
|
||||
3. Implement the minimum change; run the focused test, configured build/test suite, and declared comparison gates.
|
||||
4. Classify failures as `configure`, `compile`, `link`, `test`, `reference-comparison`, `harness`, `environment`, or `upstream-contract`. Fix implementation-owned failures; route the rest.
|
||||
5. Update only artifacts and status fields owned by the current role. The Executor owns step selection, transport/session retry, timestamps, commits, and phase advancement. The Coordinator owns normalized `retry_key` state, correction attempts, and the workflow retry budget.
|
||||
|
||||
Read [toolchain and verification](references/toolchain-and-verification.md) before choosing commands. Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for reports and [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for escalation.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Produce the applicable canonical artifacts:
|
||||
|
||||
- `docs/<feature-id>/implementation-plan.md`
|
||||
- `docs/<feature-id>/implementation-report.md`
|
||||
- `docs/<feature-id>/build-test.md`
|
||||
- `docs/<feature-id>/reference-comparison.md`
|
||||
- `docs/<feature-id>/corrections.md`
|
||||
|
||||
Each task and test traces to requirement IDs and owned files. Create only artifacts applicable to the dispatched role and completed gate.
|
||||
|
||||
## Evidence
|
||||
|
||||
Record the RED failure reason, GREEN result, exact commands, exit codes, duration, relevant output, environment/config selection, changed artifacts and hashes, comparison prechecks and tolerance source, failure classification, assumptions, and residual risk.
|
||||
|
||||
## Boundary
|
||||
|
||||
Never write production behavior before observing the corresponding test fail. Hooks are guardrails, not RED evidence. Do not change requirements, formulations, I/O contracts, tolerances, or reference artifacts to make tests pass. Do not run licensed external solvers, publish, deploy, or perform destructive version-control operations without explicit authorization.
|
||||
|
||||
If the same retry key fails after the coordinator's bounded correction cycle, return the failure; do not loop or broaden scope.
|
||||
Read [toolchain-and-verification.md](references/toolchain-and-verification.md) when selecting configured commands or evaluating comparison evidence. Return changed files, commands and exit codes, decisive results, and blockers. Do not require phase files, automatic Git actions, or a formal RED/GREEN report for harmless refactors with sufficient coverage.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "FEM Implementation TDD"
|
||||
short_description: "Implement and verify structural FEM code"
|
||||
default_prompt: "Use $fem-implementation-tdd to plan or implement an approved structural FEM solver change test-first."
|
||||
default_prompt: "Use $fem-implementation-tdd to implement and verify this structural FEM solver change."
|
||||
|
||||
@@ -1,34 +1,7 @@
|
||||
# Toolchain and Verification
|
||||
|
||||
## Command authority
|
||||
Choose actual commands from `.harness/config.json`, then project presets/build metadata and repository instructions. `python scripts/execute.py` runs the configured complete build/test; use actual configured commands directly for focused checks. Missing metadata is not a passing solver validation.
|
||||
|
||||
Choose commands in this order:
|
||||
For behavior changes, observe the relevant failing test before a fix when practical, make the minimal change, and rerun affected checks. Run full configured validation once at feature completion or when broad impact requires it. Preserve warning requirements.
|
||||
|
||||
1. Executor-selected step and approved implementation plan
|
||||
2. `.harness/config.json`
|
||||
3. Project presets, build metadata, and repository instructions
|
||||
4. Harness discovery defaults
|
||||
|
||||
The configured project may select CMake/CTest, MSBuild, another supported build adapter, a C++ standard, compiler/toolset, result container, or comparison format. Report the actual selection; do not substitute a familiar backend. Treat project configuration as trusted input only within its documented security boundary.
|
||||
|
||||
## Test-first execution
|
||||
|
||||
For each behavior:
|
||||
|
||||
1. Add or identify a test that will fail for the missing behavior.
|
||||
2. Run it and confirm the failure is expected, not a setup error.
|
||||
3. Make the smallest production change.
|
||||
4. Re-run the focused test, then configured focused and full validation.
|
||||
5. Preserve clean warning/error output required by the project.
|
||||
|
||||
A test that passed before the change is not RED evidence. A pre-edit hook confirms only that a test file exists. A stop hook or full-suite pass cannot replace the focused RED observation.
|
||||
|
||||
## Comparison gate
|
||||
|
||||
Use only contract-declared cases, quantities, identities, components, locations, units, and tolerances. Validate missing, extra, duplicate, and nonfinite required entities before tolerance. Match by declared identity, never incidental file or row order. Warning-only quantities do not change the blocking verdict.
|
||||
|
||||
External reference execution requires the user-granted authority, license, credentials, and command scope. Existing approved artifacts may be consumed read-only.
|
||||
|
||||
## Environment outcomes
|
||||
|
||||
Report `blocked-environment` only after safe configured discovery and diagnostics establish that the required toolchain, dependency, license, credential, or artifact is unavailable. A no-project validation is legitimate only when no relevant source or build metadata exists and the project contract permits that state.
|
||||
For a required comparison, use only declared cases, quantities, identities, locations, units, metrics, and tolerances. Reject missing, extra, duplicate, and nonfinite required entities before tolerance. Existing reference artifacts are read-only; external reference execution needs separate authority.
|
||||
|
||||
@@ -1,39 +1,10 @@
|
||||
---
|
||||
name: fem-io-contract
|
||||
description: Use when an approved structural FEM feature needs external syntax, validation, internal mapping, result schema, or comparison identity contracts.
|
||||
description: Define supported structural solver input semantics, diagnostics, result schema, and deterministic comparison mapping.
|
||||
---
|
||||
|
||||
# FEM I/O Contract
|
||||
|
||||
Turn approved requirements, mathematics, and logical verification quantities into deterministic interfaces without changing their meaning.
|
||||
Specify the assigned supported input subset, syntax and semantics, validation/diagnostics, source-label preservation, units, coordinates, components, internal mapping, authoritative output schema, and deterministic comparison projection. Unsupported meaningful semantics fail closed unless an explicit approved warning policy applies.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirements, formulation, numerical review, and reference-model contracts for one `feature_id`
|
||||
- Project architecture and configured input, output, and comparison backends
|
||||
- Official specifications for any approved compatibility subset
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Define the supported external syntax and semantics, defaults, ordering, identifiers, units, coordinates, validation, diagnostics, and unsupported behavior.
|
||||
2. Map validated input to implementation-neutral model entities while preserving source identity.
|
||||
3. Define result schema versioning, analysis step/frame identity, quantities, components, locations, units, coordinates, precision, and deterministic ordering.
|
||||
4. Map logical verification quantities to result and reference identities. Specify missing, extra, duplicate, and nonfinite prechecks before tolerance evaluation.
|
||||
5. Add parser, schema, round-trip, migration, and comparison contract tests.
|
||||
|
||||
Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) when a format choice changes public compatibility. Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for return data.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/io.md` with input scope; grammar/semantic rules; validation matrix; internal mapping; output schema; comparison mapping; compatibility/versioning policy; test obligations; limitations; and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Trace every public field and mapping to a requirement, formulation quantity, numerical-review identity, or authoritative selected-format specification. Include positive and negative examples only where they disambiguate behavior.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not claim full compatibility from a subset, infer undocumented reference-product behavior, alter the formulation, redefine logical acceptance quantities, change tolerances, implement code, modify reference artifacts, or run an external solver. Input syntax, result containers, and tabular comparison formats are project-selected contracts, not mandatory solver identity.
|
||||
Use public Abaqus material only for observable convention. State any supported difference; do not infer private parser, data model, algorithm, or output-database behavior. A compatibility or authoritative-schema change is a user decision when it changes the public contract. Return the contract and open gaps; do not select physics, tolerances, implementation, or alter reference artifacts.
|
||||
|
||||
@@ -1,41 +1,10 @@
|
||||
---
|
||||
name: fem-numerical-review
|
||||
description: Use when independently reviewing a structural FEM formulation, stability risks, and verification-case readiness before interface definition or implementation.
|
||||
description: Independently assess a structural FEM formulation, numerical risks, and verification/reference-case readiness.
|
||||
---
|
||||
|
||||
# FEM Numerical Review
|
||||
|
||||
Issue an independent, findings-first verdict on whether the mathematical contract and logical verification coverage are ready downstream.
|
||||
Independently examine the assigned formulation and evidence for dimensions, signs, DOF ordering, coordinate transforms, residual/tangent consistency, Jacobian and quadrature rules, rigid-body modes, conditioning, locking/hourglass risks, convergence, and recovery. Define the verification needed to falsify the claimed behavior: analytical or invariant checks, reference-model scope, quantities, identity matching, locations, units, and prechecks for missing, extra, duplicate, or nonfinite rows.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirements, research, and formulation for one `feature_id`
|
||||
- Existing reference cases and artifacts, read-only
|
||||
- `docs/TOLERANCE.md` and approved compatibility policies
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Check dimensions, signs, DOF order, transformations, kinematics, constitutive update, mapping, quadrature, residual, loads, tangent consistency, symmetry, null spaces, conditioning, and family-specific stability risks.
|
||||
2. Check each requirement has a falsifiable unit, element, integration, benchmark, convergence, or reference-comparison case.
|
||||
3. Inventory only approved reference cases. Under `docs/TOLERANCE.md`, autonomously select and justify quantity, identity/component, metric, scale and near-zero treatment, blocking/diagnostic class, and numerical tolerance from analytical, convergence, or reference evidence. Define locations, units, coordinates, and entity prechecks without selecting a physical file schema.
|
||||
4. Lead with defects and severity. Return missing derivations to formulation and missing evidence to research; do not repair upstream artifacts in place.
|
||||
|
||||
Read the applicable [analysis-family guidance](../fem-formulation-spec/references/analysis-families.md). Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for escalation and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for the verdict.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise:
|
||||
|
||||
- `docs/<feature-id>/numerical-review.md`: verdict, findings, risks, consistency checks, verification readiness, required revisions, and handoff.
|
||||
- `docs/<feature-id>/reference-model.md`: logical acceptance scope, case inventory, identity/component contract, metric, scale, blocking class, tolerance value/source, prechecks, contract revision, limitations, and I/O handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Tie every finding and tolerance choice to an equation, requirement, source, case, convergence result, or reproducible calculation. Record the feature contract revision and preserve prior failing evidence when a tolerance changes. Separate confirmed defects, risks, recommendations, and unresolved decisions. A pass means ready for I/O definition, not feature completion.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not edit the formulation, implement code, choose APIs or dataset paths, modify or generate reference artifacts, relax a tolerance merely to pass an implementation result, decide final comparison success, or approve release. A missing noncritical naming convention is not a numerical blocker.
|
||||
Apply [toolchain-and-verification.md](../fem-implementation-tdd/references/toolchain-and-verification.md) only when reviewing command or comparison evidence. Follow `docs/TOLERANCE.md` for metrics and tolerance ownership; never loosen criteria because output failed. Return actionable findings, evidence paths, and residual risks without editing the formulation, implementation, I/O contract, or reference artifacts.
|
||||
|
||||
@@ -1,38 +1,10 @@
|
||||
---
|
||||
name: fem-physics-review
|
||||
description: Use when validated structural FEM results need an independent physical-plausibility review before release-readiness evaluation.
|
||||
description: Assess validated structural FEM results for equilibrium, physical plausibility, and model-coverage limits.
|
||||
---
|
||||
|
||||
# FEM Physics Review
|
||||
|
||||
Determine whether numerically passing results also satisfy the documented physical behavior of the modeled problem.
|
||||
Review the assigned result evidence for equilibrium and reactions, load/displacement direction, sign conventions, symmetry, element force balance, stress/strain/energy sanity, rigid-body symptoms, expected limits, and model coverage. A numerical comparison pass is evidence, not by itself physical validation.
|
||||
|
||||
## Inputs
|
||||
|
||||
- Requirements, formulation, numerical review, reference model, and I/O contract
|
||||
- Passing implementation-owned build/test and comparison evidence required by the feature
|
||||
- Solver outputs and approved reference artifacts, read-only
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Confirm prerequisite evidence is passing, current, and tied to the same `feature_id` and contract revision.
|
||||
2. Evaluate only documented expectations: global equilibrium, reactions, deformation direction/mode, symmetry or zeros, internal-force balance, stress/strain signs and coordinates, conservation, residuals, energy, and family-specific behavior.
|
||||
3. Check coverage is sufficient for the claimed feature scope; distinguish a solver defect from formulation, I/O, acceptance-model, or evidence gaps.
|
||||
4. Report findings before the verdict and route each failure to its owning stage.
|
||||
|
||||
Read the applicable [analysis-family guidance](../fem-formulation-spec/references/analysis-families.md). Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for the verdict and [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for missing physical expectations.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/physics-evaluation.md` with evidence identity, checks and expected relations, observed results, failure classification, coverage assessment, verdict, residual risks, and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Each check states its governing relation or approved expectation, data source, units/coordinates, calculation, tolerance source where applicable, and pass/fail result. Explain why a check is inapplicable rather than silently omitting it.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not edit code, tests, requirements, formulations, I/O contracts, reference models, reference artifacts, or tolerances. Do not invent extra acceptance gates, approve numerical comparison, run external solvers, or approve release. A physics pass means ready for release-readiness audit only.
|
||||
Record checked artifacts, calculation or invariant, applicable approved threshold, conclusion, assumptions, untested behavior, and residual risk. Return implementation, formulation, or evidence issues to their owner; do not create new acceptance gates, edit code/contracts/tolerances/reference artifacts, or authorize release.
|
||||
|
||||
@@ -1,39 +1,10 @@
|
||||
---
|
||||
name: fem-release-readiness
|
||||
description: Use when a structural FEM solver feature has completed technical gates and needs an evidence-based release-readiness audit.
|
||||
description: Audit a structural FEM feature's evidence and limitations when the user explicitly requests release readiness.
|
||||
---
|
||||
|
||||
# FEM Release Readiness
|
||||
|
||||
Audit closure evidence and prepare a release recommendation without modifying technical contracts or performing a release.
|
||||
Use only for an explicit release-readiness audit. Review the requested feature's relevant contracts, validation/reference evidence, known limitations, deferred work, and risks. Check that blocking requirements have credible evidence and that unsupported behavior is explicit; report contradictions or missing evidence rather than waiving them.
|
||||
|
||||
## Inputs
|
||||
|
||||
- All lifecycle artifacts for one `feature_id` and contract revision
|
||||
- Passing configured full validation and required comparison evidence
|
||||
- Passing physics review
|
||||
- Correction history, accepted risks, and project release policy
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Inventory required artifacts and verify identity, revision, freshness, ownership, outcome, and absence of contradictions.
|
||||
2. Trace every blocking requirement through acceptance criteria, implementation/tests, required numerical or reference evidence, physics review, and final disposition.
|
||||
3. Confirm unresolved defects, deferred scope, compatibility limits, unsupported behavior, accepted risks, and environment limits are explicit.
|
||||
4. Produce the checklist, known limitations, release-notes draft, and readiness verdict. Return missing or failed evidence to its owning stage.
|
||||
|
||||
Use [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) to validate stage envelopes. Read [toolchain and verification](../fem-implementation-tdd/references/toolchain-and-verification.md) when auditing command or comparison evidence. Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for release-scope decisions.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/release.md` with release scope, gate inventory, requirement traceability, validation summary, known limitations, deferred items, release-notes draft, readiness verdict, residual risks, and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
A ready verdict requires complete, passing, current evidence for every blocking gate. Record artifact paths and hashes, configuration/toolchain identity, test and comparison summaries, approved exceptions, and the exact contract revision audited.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not implement or correct code, edit tests or upstream contracts, waive missing evidence, change acceptance or tolerance, or reinterpret a failed gate. Do not commit, tag, package, publish, deploy, or externally release anything unless the user explicitly authorizes that separate action. Readiness is a recommendation, not publication approval.
|
||||
Produce a concise readiness recommendation with evidence paths, commands/exit codes where relevant, limitations, and residual risks. This is not a mandatory lifecycle stage and does not authorize code changes, commits, tags, packages, publication, deployment, or release.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "FEM Release Readiness"
|
||||
short_description: "Audit structural FEM release readiness"
|
||||
default_prompt: "Use $fem-release-readiness to audit release readiness for a completed structural FEM solver feature."
|
||||
default_prompt: "Use $fem-release-readiness to audit the requested structural FEM feature's release readiness."
|
||||
|
||||
@@ -1,38 +1,14 @@
|
||||
---
|
||||
name: fem-requirements-baseline
|
||||
description: Use when baselining a finite-element structural solver feature before research, formulation, interface definition, or implementation planning.
|
||||
description: Define a durable, verifiable structural FEM feature scope and acceptance contract when one is needed.
|
||||
---
|
||||
|
||||
# FEM Requirements Baseline
|
||||
|
||||
Turn a structural-analysis solver request into a stable, verifiable contract without choosing downstream mathematics or implementation.
|
||||
Turn the assigned request into observable scope, exclusions, assumptions, compatibility boundary, and acceptance intent. Use an existing PRD when it is sufficient; create a separate requirements document or matrix only when the feature needs that separation.
|
||||
|
||||
## Inputs
|
||||
Write atomic requirements with a measurable acceptance method. State quantities, locations, units, coordinates, and physical behavior where relevant. Preserve user- or standard-defined acceptance; leave formulation choices, implementation, schema design, and numerical tolerance selection to their owners.
|
||||
|
||||
- Project instructions and architecture decisions
|
||||
- User request, constraints, exclusions, and existing feature artifacts
|
||||
- Applicable standards or compatibility commitments already selected by the project
|
||||
Read [workflow-and-decisions.md](references/workflow-and-decisions.md) only for a material ambiguity or authority question. Return the document path, decisions, verification intent, and unresolved critical choice. Do not invent physics, compatibility, or acceptance promises.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Use the stable kebab-case `feature_id` and feature folder supplied by Coordinator; define purpose, scope, exclusions, analysis family, assumptions, units, coordinates, and compatibility boundary.
|
||||
2. Write atomic `FEM-REQ-<FEATURE>-###` shall-statements. Give each an observable acceptance criterion and verification method.
|
||||
3. Define logical verification quantities and required physical behavior. Preserve acceptance fixed by the user or an applicable standard; otherwise delegate quantity details, metric, scale, blocking class, and numerical tolerance to Numerical Review under `docs/TOLERANCE.md`.
|
||||
4. Build the requirement-verification matrix and classify open issues using the project workflow.
|
||||
|
||||
Read [workflow and decision authority](references/workflow-and-decisions.md) when resolving ambiguity or deciding whether user input is critical. Use [evidence and handoff](references/evidence-and-handoff.md) for the returned envelope.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/requirements.md` with metadata, scope, analysis definition, requirements, acceptance criteria, verification intent, compatibility boundary, matrix, open decisions, and handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Every requirement traces to its source and an acceptance method. Numerical outputs state quantity, location, units, coordinates, and tolerance source when applicable.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not derive the formulation, select a numerical algorithm, design APIs or storage schemas, implement code, calibrate tolerances, or claim compatibility beyond the approved boundary. Route missing theory, reference evidence, or physical acceptance choices to their owning stage.
|
||||
Use [evidence notes](references/evidence-and-handoff.md) when a separate durable evidence record is needed.
|
||||
|
||||
@@ -1,26 +1,5 @@
|
||||
# Evidence and Handoff Contract
|
||||
# Evidence Notes
|
||||
|
||||
Use [Feature document management](../../../../docs/FEATURE_DOCUMENTATION.md) for concise main reports,
|
||||
linked details, and Coordinator's document inventory. Include main and required detail paths in evidence.
|
||||
Use this reference only when a task needs a durable evidence record. Record the feature/document path, decisive facts and assumptions, relevant commands with exit codes, comparison quantities and tolerance source when applicable, and residual risks. Keep source facts, calculations, inferences, and decisions distinct. A required failed or unrun check is not a pass.
|
||||
|
||||
Every stage returns one envelope:
|
||||
|
||||
| Field | Required content |
|
||||
| --- | --- |
|
||||
| `feature_id` | Stable feature identifier |
|
||||
| `stage` | `requirements`, `research`, `formulation`, `numerical-review`, `io-definition`, `implementation-planning`, `implementation`, `correction`, `physics-evaluation`, or `release-readiness` |
|
||||
| `outcome` | `pass`, `return-upstream`, `retry`, `blocked-environment`, or `needs-user-decision` |
|
||||
| `next_owner` | Agent id, or YAML `null` |
|
||||
| `evidence_paths` | Repository-relative artifacts used or produced |
|
||||
| `evidence_digest` | Concise findings tied to requirement IDs |
|
||||
| `failure_classification` | `configure`, `compile`, `link`, `test`, `reference-comparison`, `harness`, `environment`, `upstream-contract`, `physics`, `evidence`, or YAML `null` |
|
||||
| `retry_key` | `<feature-id>\|<failing-gate>\|<classification>\|<contract-revision>`, or YAML `null` |
|
||||
| `attempt` | Coordinator-managed nonnegative attempt count for the retry key |
|
||||
| `escalation_class` | Critical-decision class, or YAML `null` |
|
||||
| `blocker` | Actionable blocker, or YAML `null` |
|
||||
|
||||
Evidence records include, when applicable: source locator and access date; assumptions; command, exit code, duration, and relevant output; test identity and RED/GREEN result; artifact hash; comparison quantity, tolerance source, and decision; residual risk.
|
||||
|
||||
Use repository-relative paths and stable identifiers. Distinguish observed facts, calculations, inferences, and decisions. Never report a pass when a required command failed, evidence is stale, or a blocking acceptance item is unresolved.
|
||||
|
||||
Retry is bounded by the coordinator policy. A repeated normalized failure returns to its owning stage; it does not justify changing requirements, formulations, schemas, reference artifacts, or tolerances.
|
||||
Return a concise result containing changed paths, evidence, and blockers; no common handoff envelope, workflow state, retry key, or coordinator inventory is required. Do not use repeated failure to justify changing requirements, formulations, schemas, reference artifacts, or tolerances.
|
||||
|
||||
@@ -18,7 +18,7 @@ Proceed without user review for reversible choices within approved contracts: in
|
||||
|
||||
## User decisions
|
||||
|
||||
Return `needs-user-decision` only for a choice that changes at least one of:
|
||||
Ask the user only for a choice that changes at least one of:
|
||||
|
||||
- supported physics, formulation meaning, or analysis scope;
|
||||
- public compatibility or an authoritative I/O schema;
|
||||
@@ -28,6 +28,6 @@ Return `needs-user-decision` only for a choice that changes at least one of:
|
||||
|
||||
Everything else follows the authority order. Lack of a preference is not a blocker when a deterministic in-contract choice exists.
|
||||
|
||||
## Contract flow
|
||||
## Responsibilities
|
||||
|
||||
Requirements own acceptance intent; research owns evidence; formulation owns mathematics; numerical review owns independent numerical findings and logical verification coverage; I/O owns external/internal mappings; implementation owns code and tests; physics review owns physical plausibility; release review owns closure evidence. A downstream stage returns a defect to the owning upstream stage instead of silently rewriting its contract.
|
||||
Requirements own acceptance intent; research owns evidence; formulation owns mathematics; numerical review owns independent numerical findings and verification coverage; I/O owns mappings; implementation owns code and tests; and physics review owns plausibility findings. Use only the expertise needed by the task. Do not silently rewrite another owner's contract to make downstream work pass.
|
||||
|
||||
@@ -1,38 +1,12 @@
|
||||
---
|
||||
name: fem-research-evidence
|
||||
description: Use when a structural FEM feature needs source-backed theory, benchmark, verification, or reference-convention evidence before formulation.
|
||||
description: Gather source-backed FEM theory, benchmark, or observable reference-convention evidence for a concrete solver decision.
|
||||
---
|
||||
|
||||
# FEM Research Evidence
|
||||
|
||||
Build an auditable evidence brief while keeping documented fact, calculation, inference, and unresolved questions distinct.
|
||||
Answer only the research questions needed by the assigned decision. Prefer standards, primary literature, authoritative textbooks, official verification guides, and public vendor documentation. Separate sourced fact, calculation, inference, and remaining gap; record stable locators and applicability limits.
|
||||
|
||||
## Inputs
|
||||
Identify useful analytical, invariant, patch, convergence, manufactured, or published benchmark cases without treating a single solver comparison as proof. Abaqus material supports only documented observable syntax, semantics, outputs, and verification conventions, never its private internals. Use `fem-theory-query` only when the configured vault is the requested source.
|
||||
|
||||
- `docs/<feature-id>/requirements.md`
|
||||
- Project instructions and user-supplied sources
|
||||
- Existing research brief and reference artifacts, read-only
|
||||
|
||||
## Workflow
|
||||
|
||||
1. Derive research questions from requirement IDs and open decisions.
|
||||
2. Prefer governing standards, primary literature, authoritative textbooks, and official vendor documentation; record reliability and applicability.
|
||||
3. Summarize only the theory needed downstream. Identify analytical solutions, patch tests, convergence studies, manufactured solutions, and published benchmarks appropriate to the analysis family.
|
||||
4. State what each source or case can and cannot verify. Mark unsupported claims as inference or evidence gaps.
|
||||
|
||||
When a configured FEM vault is the requested evidence source, use `fem-theory-query`. Apply [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) to product references and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) to the result.
|
||||
|
||||
## Output
|
||||
|
||||
Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
|
||||
feature context, keep main reports concise, and link necessary owned details in the same feature folder.
|
||||
|
||||
Create or revise `docs/<feature-id>/research.md` with research questions, source inventory and reliability, theory findings, candidate verification cases, applicability limits, conflicts, gaps, and downstream handoff.
|
||||
|
||||
## Evidence
|
||||
|
||||
Trace every material claim to a stable locator. For a project-selected reference solver or format, use official public documentation for observable syntax, semantics, output, or procedure only. Record edition/version and access date when behavior can vary.
|
||||
|
||||
## Boundary
|
||||
|
||||
Do not finalize the mathematical formulation, set tolerance values, design APIs or schemas, implement code, alter reference artifacts, or run an external licensed solver without explicit authorization. Do not treat agreement with one product as proof of correctness or infer its undocumented internals.
|
||||
Return concise evidence, candidate verification cases, and gaps. Do not finalize formulations, tolerances, schemas, code, or reference artifacts.
|
||||
|
||||
@@ -2,10 +2,6 @@
|
||||
"version": 1,
|
||||
"projectType": "cmake",
|
||||
"cmake": {
|
||||
"sourceDir": ".",
|
||||
"binaryDir": ".harness/build-ninja-msvc-debug",
|
||||
"configurePreset": "windows-msvc-ninja-debug",
|
||||
"buildPreset": "windows-msvc-ninja-debug",
|
||||
"testPreset": "windows-msvc-ninja-debug"
|
||||
"sourceDir": "."
|
||||
}
|
||||
}
|
||||
|
||||
@@ -14,7 +14,7 @@
|
||||
|
||||
- FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축하는 프로젝트이다. 목표는 Abaqus를 흉내 내는 parser를 만드는 것이 아니라, 승인된 입력 범위에서 물리적으로 설명 가능하고 재현 가능한 해석 결과를 만드는 것이다.
|
||||
- 새 기능은 입력 keyword만 인식하거나 element kernel만 존재한다고 완성된 것이 아니다. Semantic model, equation system, 해법, 결과 복구, HDF5 외부 계약과 독립 검증 evidence가 하나의 추적 가능한 기능을 이뤄야 한다.
|
||||
- 설계나 구현 전에 [PRD](docs/PRD.md)의 제품 범위, [ARCHITECTURE](docs/ARCHITECTURE.md)의 소유권과 데이터 흐름, [ADR](docs/ADR.md)의 기존 결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 [CODINGSTYLE](docs/CODINGSTYLE.md)을 따른다.
|
||||
- 설계·구현 전에 [PRD](docs/PRD.md), [ARCHITECTURE](docs/ARCHITECTURE.md), [ADR](docs/ADR.md)에서 현재 작업에 관련된 제품 범위·소유권·데이터 흐름·결정을 확인한다. C++ naming, formatting, Doxygen와 변경 검증은 [CODINGSTYLE](docs/CODINGSTYLE.md)을 따른다. 같은 문맥에서 읽은 변경 없는 자료를 다시 읽지 않는다.
|
||||
- 재사용 가능한 agent, skill과 Harness는 개발 운영 인프라다. 이를 일반화해도 이 저장소가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 승인된 수치 계약은 바뀌지 않는다.
|
||||
- FESA는 Abaqus와 독립적인 솔버다. 문서와 구현은 full Abaqus compatibility뿐 아니라
|
||||
Abaqus 요소 정식화, 적분, stabilization, 내부 상태 또는 결과 생성 절차의 동등성을
|
||||
@@ -40,24 +40,24 @@
|
||||
|
||||
## 문서 기준과 Feature 관리
|
||||
|
||||
- 공통 역할·handoff·상태 전이·재시도는 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md), skill 구성과 적용 경계는 [SOLVER_SKILL_DESIGN](docs/SOLVER_SKILL_DESIGN.md), Feature 문서 배치와 소유권은 [FEATURE_DOCUMENTATION](docs/FEATURE_DOCUMENTATION.md)을 기준으로 한다. 실제 skill 실행 절차는 해당 `SKILL.md`를 읽는다.
|
||||
- [HARNESS](docs/HARNESS.md)와 [HARNESS_WORKFLOW](docs/HARNESS_WORKFLOW.md)는 설치·흐름 참고 문서다. 승인·역할·상태 전이는 위 agent 계약과 현재 [harness skill](.agents/skills/harness/SKILL.md), 실행 메커니즘은 선택된 설정과 현재 `scripts/` 구현에 대조한다. 오래된 설명으로 이 계약을 덮어쓰지 않으며, 구현이 승인된 제품·수치 계약을 바꿀 권한도 없다.
|
||||
- 기능별 승인 계약과 모든 agent 보고서는 `docs/<feature-id>/`에 둔다. Coordinator가 안정적인 kebab-case Feature ID를 정하고 모든 dispatch에서 같은 폴더와 revision을 사용한다. 기존 `docs/features/<feature-id>/` 자료가 있으면 자동 이동·복제하지 않고 필요한 경로와 revision을 참조한다.
|
||||
- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크나 결정을 루트 문서에 누적하지 않는다. 프로젝트 공통 지침 수정은 별도 사용자 요청으로 승인된 범위에서만 수행한다.
|
||||
- Coordinator는 새 Feature에 아래 관리 문서를 실제 요구사항으로 초기화한다. 재개 시 기존 기록을 읽고 필요한 부분만 갱신하며, 승인되지 않은 내용을 승인으로 표시하거나 후속 stage의 빈 보고서를 미리 만들지 않는다.
|
||||
- 현행 운영 결정은 [ADR-028](docs/ADR.md#adr-028), 역할·인계·실패 처리는 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md), skill 적용은 [SOLVER_SKILL_DESIGN](docs/SOLVER_SKILL_DESIGN.md), 문서 배치·소유권은 [FEATURE_DOCUMENTATION](docs/FEATURE_DOCUMENTATION.md)을 따른다. 실제 절차는 필요한 `SKILL.md`와 관련 reference만 읽는다.
|
||||
- [HARNESS](docs/HARNESS.md)는 설치·설정·CLI, [HARNESS_WORKFLOW](docs/HARNESS_WORKFLOW.md)는 개발·검증 흐름을 설명한다. 실행 동작은 선택된 설정과 현재 `scripts/`에 대조하며 구현이 승인된 제품·수치 계약을 바꿀 권한은 없다.
|
||||
- 지속할 계약·evidence가 필요한 Feature는 메인이 안정적인 kebab-case ID와 `docs/<feature-id>/`를 정한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다.
|
||||
- 일반 Feature 작업에서 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 읽기 전용 기준이다. 현재 작업의 진행 링크를 누적하지 않으며 공통 지침 수정은 별도 사용자 요청 범위에서 수행한다.
|
||||
- 새 Feature를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다. 각 문서는 프로젝트 AGENTS·PRD·ADR를 상대 Markdown 링크로 참조한다.
|
||||
|
||||
| Coordinator 소유 문서 | 내용과 경계 |
|
||||
| 메인 소유 문서 | 내용과 경계 |
|
||||
| --- | --- |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 산출물 경로·owner·revision·검토 상태 목록, 현재 상태 문서 링크 |
|
||||
| `PRD.md` | 사용자 요구, 범위·제외, acceptance 요약과 requirement ID별 계약 링크. 요구사항·검증 matrix 원본은 Requirement Agent의 `requirements.md` |
|
||||
| `ADR.md` | Feature 결정 ID·상태·이유·영향, 결정 owner와 승인 근거 링크 |
|
||||
| `coordination.md` | stage·outcome·next owner·contract revision, gate evidence·retry·blocker·다음 작업의 유일한 workflow 상태 원본 |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당 owner와 문서 목록. 현재 checklist는 PRD로 연결 |
|
||||
| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본이며 복잡한 상세 계약은 필요한 경우만 분리하여 연결 |
|
||||
| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거 |
|
||||
|
||||
- 관리 문서에서 실제 프로젝트 기준 문서를 상대 Markdown 링크로 연결한다. Coordinator의 목록·참조·상태 관리는 specialist 본문을 대신 작성·수정할 권한이 아니다.
|
||||
- `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니다. 모든 dispatch와 Harness step의 필수 입력에 Feature 폴더 및 그 안의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md` 경로를 명시한다.
|
||||
- 기본 보고서는 Feature ID·owner·입력 revision, 핵심 결과, evidence, 미해결 항목·handoff만 간결하게 기록한다. 긴 유도·schema·상세 분석은 같은 폴더의 `formulation-derivation.md`, `io-schema.md` 같은 상세 문서로 분리하고 상대 링크로 연결한다. 본문과 상세 문서에 같은 내용을 중복 유지하지 않는다.
|
||||
- 상세 문서는 기본 산출물과 동일 owner·Feature ID·입력 revision을 사용하며 같은 stale 판정을 받는다. 반환 `evidence_paths`에는 기본 문서와 작성·갱신하거나 판정에 사용한 상세 문서를 포함한다. Coordinator는 실제 파일과 링크를 확인하고 목록에 등록한다.
|
||||
- 소스·테스트·Harness 제어 파일·기계 생성 로그/결과·read-only reference artifact는 각각의 지정 경로에 유지하고 보고서에서 참조한다. 필수 검증을 생략했다면 미실행 사실과 이유를 남긴다.
|
||||
- 현재 checklist는 PRD 한 곳에 둔다. `requirements.md`·검증 matrix는 분리가 필요할 때만 작성하고 PRD에는 요약·링크만 유지한다. Specialist는 할당된 전문 문서만 수정한다.
|
||||
- `FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니다. 메인은 필요한 Feature context와 관련 경로·절만 인계하며 모든 문서를 매번 재독하도록 요구하지 않는다.
|
||||
- 기존 `coordination.md`, `docs/features/<feature-id>/`와 phase 자료는 이력으로 보존하고 필요한 경로·계약 revision을 참조한다. 자동 이동·복제하거나 신규 coordination 상태 파일을 만들지 않는다.
|
||||
- 보고서는 결정·결과, 적용 계약, evidence와 미해결 항목을 간결하게 기록한다. 간단한 구현·build/test·reference 결과는 한 보고서로 모으고 긴 유도·schema는 같은 폴더의 상세 문서로 분리해 연결한다.
|
||||
- 실제 계약 변경은 관련 evidence의 유효성을 다시 확인한다. 의미 변화 없는 문서 편집마다 고정 handoff·hash·gate 기록을 만들지 않는다. 미실행 검사는 이유를 남기며 승인·통과로 표시하지 않는다.
|
||||
- 소스·테스트·기계 생성 로그/결과·read-only reference artifact는 지정 경로에 유지하고 보고서에서 참조한다.
|
||||
|
||||
## FESA 개발의 핵심 원칙
|
||||
|
||||
@@ -72,9 +72,9 @@
|
||||
### 소유권과 의존성
|
||||
|
||||
- CRITICAL: C++ 빌드는 CMake/MSVC/x64/Debug 기준으로 검증한다.
|
||||
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
|
||||
- CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
|
||||
- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 phase에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다.
|
||||
- 동작 추가·수정은 해당 동작을 확인하는 테스트로 검증한다. 버그는 가능한 경우 실패를 재현한 뒤 최소 수정한다.
|
||||
- 기존 coverage가 충분한 rename·refactor나 문서 수정에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
- CRITICAL: Abaqus reference artifact 생성, 수정, 복원은 명시적으로 요청된 작업 범위에서만 수행한다. 문서 또는 agent가 artifact naming이나 보조 metadata를 맞추기 위해 파일 변경을 요구하지 않는다.
|
||||
- CRITICAL: public header와 implementation 의존성 방향을 역전하지 않는다.
|
||||
- CRITICAL: 사람이 계약과 수치식을 대조할 수 있는 단순한 코드를 작성한다. 주석은 코드가 이미 말하는 동작보다 부호, 수명, 순서, backend 제약처럼 비자명한 이유를 설명한다.
|
||||
- Domain은 입력 파일에서 생성된 전체 모델 정의를 소유하고, 파싱 이후 가능한 한 불변으로 취급한다.
|
||||
@@ -95,17 +95,11 @@
|
||||
|
||||
### 개발 운영 인프라
|
||||
|
||||
- Codex custom agent의 `model_reasoning_effort`는 `xhigh`이며, 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
|
||||
- Harness runner는 [scripts/execute.py](scripts/execute.py)이며 `feat-<phase-name>` branch prefix를 사용한다. 실행 전 Git top-level이 Harness root와 같아야 하고, 선택된 phase 제어 파일 allowlist 밖의 worktree는 clean이어야 한다. 관련 없는 변경을 stage하거나 숨기지 않는다.
|
||||
- Executor는 branch, 현재 pending step 선택, transport attempt, timestamp, path-scoped staging/commit과 phase 진행을 소유한다. 구현 경로와 phase metadata를 분리해 commit하며 저장소 전체를 무조건 stage하지 않는다. Implementation Agent는 선택된 step의 코드·테스트·보고서와 result payload만 갱신하며 branch/commit/push나 다른 step·제어 metadata를 변경하지 않는다.
|
||||
- Planning은 각 Step의 승인된 정확한 상대 파일 목록을 phase index의 `owned_paths`에 기록한다. 모든 pending Step은 실행 전에 목록이 필요하고 `[]`는 구현 파일 변경 없음을 뜻한다. Executor는 신뢰된 목록으로 매 시도 후·stage 전·commit 전 경로를 검사하며 rename 양쪽 경로도 승인되어야 한다. 범위 밖 변경은 보존하고 재시도·커밋·다음 Step 진행을 중단한다. 실행 중 동시 편집까지 원자적으로 격리하는 보장은 아니다.
|
||||
- Executor의 process/session transport 시도는 실제 wrapper timeout과 결과 미보고가 확인된 경우에만 최초 포함 최대 2회이며 Coordinator의 correction budget과 별개다. 비정상 종료에서도 명시적 `error/blocked`를 보존하고, 인식된 sandbox helper 환경 실패는 종료 코드 0에서도 `blocked`로 기록한다. Executor 소유 `attempt_history`는 재시도·재개 때 보존하며 구현·상위 계약·환경·물리 실패를 transport retry로 반복하지 않는다.
|
||||
- 기본 sandbox는 `FEM_HARNESS_CODEX_SANDBOX=workspace-write`다. `danger-full-access`는 동일 명령의 native sandbox 실패 증거, 해당 실행 직전 사용자의 명시적 승인, clean linked Git worktree와 `--approve-danger-full-access`가 모두 필요하다. 환경변수 설정만으로 승인되지 않는다. `--push` 등 원격 작업도 별도 명시적 승인이 필요하다.
|
||||
- Hook 연결은 [.codex/hooks.json](.codex/hooks.json), 구현은 [scripts/hooks](scripts/hooks)와 [scripts/msvc_harness](scripts/msvc_harness)에 둔다. Hook script를 수동 실행해 등록된 hook이나 검증 evidence를 대체하지 않는다.
|
||||
- PreToolUse는 위험 명령과 C++ production file의 대응 테스트 존재 여부를 검사하고 허용된 편집 경로를 기록한다. 이는 RED 실행이나 correctness의 증거가 아니다.
|
||||
- Stop은 유효한 동일 session/turn 기록에서 기록된 편집 도구의 대상이 모두 저장소 내부 `.md`일 때 build/test를 생략한다. 기록 누락·손상 또는 비문서 변경이면 정상 검증 경로를 따른다. Shell 쓰기는 이 기록이 완전히 추적하지 못하며, 편집 기록 없는 읽기 전용 계획 요청도 자동 생략을 보장하지 않는다.
|
||||
- 생략하지 않는 Stop은 `.harness/config.json` 또는 자동 감지 결과의 backend로 build/test를 검증한다. 문서 작업에서 사용자가 실행을 제외하면 수동으로 Hook·CMake·CTest 등을 실행하지 않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작하거나 생략된 검증을 통과로 보고하지 않는다.
|
||||
- `.harness/hook-state/`와 `phases/**/step*-output.json` 같은 생성 실행 기록은 ignored 상태로 유지한다.
|
||||
- 일반 specialist의 기본 추론 강도는 `medium`, 정식화·수치·물리 검토는 `high`다. 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따르고 난해한 작업에만 필요한 범위에서 높인다.
|
||||
- [scripts/execute.py](scripts/execute.py)는 명시적 build/test 실행기다. 내부 LLM·phase 상태기계·자동 Git·재시도·파일명 TDD gate·대화 종료 hook을 사용하지 않는다.
|
||||
- 설정·preset·명령은 검토할 실행 입력이다. `shell=False`·경로 검사·timeout이 모든 side effect를 격리하는 sandbox는 아니며 실제 도구 권한과 외부 실행 승인은 별도로 따른다.
|
||||
- 관련 없는 사용자 변경은 보존한다. Commit을 요청받으면 작업 경로만 stage하고 push·tag·publish 등 원격 작업은 명시적으로 승인된 범위에서 수행한다. Runner는 이 권한을 부여하거나 Git 상태를 변경하지 않는다.
|
||||
- 기존 phase·hook 생성 기록은 이력으로 보존하며 ignored 상태를 유지한다. 현재 검증을 위해 기록을 조작하거나 삭제된 hook을 수동 실행하지 않는다.
|
||||
|
||||
## 기능을 추가할 때의 판단 기준
|
||||
|
||||
@@ -118,62 +112,60 @@
|
||||
|
||||
## 개발 프로세스
|
||||
|
||||
- TDD를 기본으로 한다. 구현은 `RED -> GREEN -> VERIFY` 순서를 따른다.
|
||||
- 동작 변경을 검증하는 테스트와 가능한 버그 재현을 기본으로 하며 최소 수정 후 관련 검사를 수행한다.
|
||||
- CRITICAL: 빌드 경고를 새로 추가하지 말 것.
|
||||
- 기능 개발은 아래 `Agent/Skill Workflow`의 9개 정규 stage를 순서대로 통과한다. 문서 수정·읽기 전용 검토를 새 solver feature 전체 workflow로 확대하지 않는다.
|
||||
- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, outcome, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID의 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
|
||||
- 수식·요소·재료·적분·상태 갱신 변경은 독립 numerical review와 해당 analytical/invariant 검증을 수행한다. 필요한 물리·reference 검증도 유지한다.
|
||||
- 변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 필수 reference 비교를 한 번 수행한다. 사용자 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하며 이후 변경·실패가 없으면 반복하지 않는다.
|
||||
- 문서만 수정하는 작업은 링크·소스 대조·diff 정적 검토로 확인하고 build/test를 실행하지 않는다. 미실행을 통과로 보고하지 않는다.
|
||||
- 기능 문서는 기본적으로 한국어 Markdown으로 작성하되 agent/skill ID, field, requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
|
||||
- 커밋 메시지는 conventional commits 형식을 따른다: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
|
||||
|
||||
## Agent/Skill Workflow
|
||||
|
||||
Solver feature workflow에서 `coordinator-agent`만 main agent로서 상태 전이와 closure를
|
||||
소유하며 다음 eligible specialist에게 한 번에 하나의 bounded task를 dispatch한다.
|
||||
Specialist는 peer를 호출하거나 다음 gate로 진행하거나 자신의 산출물을 최종 승인하지 않는다.
|
||||
Intake/coordination은 아래 정규 stage와 별도로 관리한다.
|
||||
메인 assistant가 범위를 파악하고 필요한 전문 작업만 위임하며 계획·구현·검증·결과 확인을
|
||||
조정한다. 작은 작업은 직접 수행하고 고정된 stage 순회나 별도 coordinator를 호출하지 않는다.
|
||||
|
||||
| 단계 | 담당 sub-agent | 필수 skill | 기본 보고서 (`docs/<feature-id>/`) |
|
||||
| --- | --- | --- | --- |
|
||||
| 1. `requirements` | `requirement-agent` | `fem-requirements-baseline` | `requirements.md` |
|
||||
| 2. `research` | `research-agent` | `fem-research-evidence` | `research.md` |
|
||||
| 3. `formulation` | `formulation-agent` | `fem-formulation-spec` | `formulation.md` |
|
||||
| 4. `numerical-review` | `numerical-review-agent` | `fem-numerical-review` | `numerical-review.md`, `reference-model.md` |
|
||||
| 5. `io-definition` | `io-definition-agent` | `fem-io-contract` | `io.md` |
|
||||
| 6. `implementation-planning` | `implementation-planning-agent` | `fem-implementation-tdd`, `harness` | `implementation-plan.md` |
|
||||
| 7. `implementation` | `implementation-agent` | `fem-implementation-tdd` | `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
|
||||
| 8. `physics-evaluation` | `physics-evaluation-agent` | `fem-physics-review` | `physics-evaluation.md` |
|
||||
| 9. `release-readiness` | `release-agent` | `fem-release-readiness` | `release.md` |
|
||||
| Specialist | 호출 조건 | Skill |
|
||||
| --- | --- | --- |
|
||||
| `requirement-agent` | 복잡하거나 상충하는 scope·acceptance 정리 | `fem-requirements-baseline` |
|
||||
| `research-agent` | 부족한 이론·benchmark·reference 근거 조사 | `fem-research-evidence` |
|
||||
| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화 | `fem-formulation-spec` |
|
||||
| `numerical-review-agent` | 정식화·주요 수치 변경·수치 불일치의 독립 검토 | `fem-numerical-review` |
|
||||
| `io-definition-agent` | 입력 의미·진단·결과 schema·비교 mapping 정의 | `fem-io-contract` |
|
||||
| `implementation-agent` | 위임할 이점이 있는 구현 묶음 | `fem-implementation-tdd` |
|
||||
| `physics-evaluation-agent` | 평형·물리 타당성·coverage 평가 | `fem-physics-review` |
|
||||
|
||||
- 위 8개 lifecycle skill은 [.codex/skills](.codex/skills)에 있다. Planning은 할당된 `phases/index.json`, `phases/<phase>/index.json`, `stepN.md`도 소유하고, Implementation은 할당된 코드·테스트·build registration을 소유한다.
|
||||
- 보조 skill은 [.agents/skills/harness](.agents/skills/harness/SKILL.md)의 phase 계획·실행, [.agents/skills/review](.agents/skills/review/SKILL.md)의 읽기 전용 diff 검토, [fem-theory-query](.codex/skills/fem-theory-query/SKILL.md)의 configured FEM wiki 근거·coverage gap 조회다. `fem-theory-query`를 모든 FEM 질문에 적용하거나 workstation vault 절대 경로를 commit하지 않는다.
|
||||
- 모든 dispatch/return은 SOLVER_AGENT_DESIGN의 공통 envelope를 사용한다. Workflow outcome은 `pass | return-upstream | retry | blocked-environment | needs-user-decision`만 사용한다. Specialist outcome은 전이 요청이며 Coordinator가 실제 산출물·owner·revision·evidence를 확인한 뒤 상태를 기록한다.
|
||||
- `return-upstream`은 정확한 계약 owner로 반환하고 영향받는 downstream evidence를 stale 처리한다. Numerical Review는 formulation과 reference-model readiness, Implementation은 TDD·전체 build/test·필수 reference comparison 증거가 모두 있어야 통과한다. Release의 `pass`는 내부 readiness일 뿐 push/tag/publish/deploy/package 권한이 아니다.
|
||||
- `correction-agent`는 정규 stage가 아닌 on-demand rework다. Coordinator는 `retry_key = feature_id|failing_gate|normalized_failure_classification|contract_revision`별 correction을 최대 한 번 허용하고 이후 Implementation rerun을 한 번 dispatch한다. 같은 key가 다시 실패하면 두 번째 correction을 금지하고 계약·환경·critical decision owner로 반환한다. 문구만 바꿔 key를 새로 만들지 않으며 `corrections.md`는 실제 correction 때만 작성한다.
|
||||
- 승인된 Feature와 할당된 dispatch 안의 일반 문서·계획 파일 작성 및 bounded local 실행에는 반복적인 사용자 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않으며 Harness 실행은 해당 작업에 실행까지 할당된 경우에만 한다.
|
||||
- Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명, 보안·법률 위험 수용, destructive/remote/release 작업은 SOLVER_AGENT_DESIGN의 critical decision 절차를 따른다. 권한이 필요한 실행을 일반 자율 작업으로 확대하지 않는다.
|
||||
- Harness step은 0부터 연속 번호로 나누고 각 step 안에서 `RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY`를 완료하도록 계획한다. 정확한 입력·소유 파일·명령·제외 범위·중단 조건을 명시하며 필요한 물리·schema·tolerance·reference가 없으면 해당 owner로 반환한다.
|
||||
- Harness step 상태 `pending/completed/error/blocked`는 workflow outcome과 별개다. Implementation은 선택된 step에 `completed`와 비어 있지 않은 `summary`, `error`와 `error_message`, 또는 `blocked`와 `blocked_reason`을 반환한다. Executor가 timestamp와 phase 진행을 관리하며 실패 증거를 지우고 즉시 재실행하지 않는다.
|
||||
- 메인도 `fem-implementation-tdd`로 계획·구현·일반 실패 수정을 수행할 수 있다. 전용 planning/correction profile이나 phase 파일을 요구하지 않는다.
|
||||
- `fem-release-readiness`는 사용자가 별도 감사를 명시 요청할 때만 사용한다. Readiness 권고는 외부 release 권한이 아니다.
|
||||
- [harness](.agents/skills/harness/SKILL.md)는 구성된 build/test의 명시 실행, [review](.agents/skills/review/SKILL.md)는 요청 diff의 읽기 전용 검토, [fem-theory-query](.codex/skills/fem-theory-query/SKILL.md)는 configured FEM wiki 근거·coverage gap 조회에 사용한다. Workstation vault 절대 경로를 commit하지 않는다.
|
||||
- Dispatch는 작업·관련 경로/절·수정 파일·검증 기준, return은 결과·변경 파일·검사 결과·미해결 항목으로 충분하다. 지원되는 도구에서는 `fork_turns="none"`으로 필요한 문맥만 전달하고 연속 수정은 같은 owner에게 보낸다.
|
||||
- Specialist는 할당 범위를 지키고 peer를 재위임하거나 상위 계약을 결과에 맞춰 수정하지 않는다. 계약 문제는 owner·경로·근거와 함께 메인에 전달한다. 독립 검토를 자기 승인으로 대체하지 않는다.
|
||||
- 일반 실패는 현재 구현 owner가 수정한다. 새 근거·변경 없이 같은 명령·agent 호출을 반복하지 않으며 고정 correction/transport 예산을 두지 않는다.
|
||||
- 승인된 범위의 일반 작업과 인계에 반복 승인 gate를 추가하지 않는다. 계획 요청만으로 실행 권한을 추정하지 않는다.
|
||||
- Physics·지원 범위·공개 호환성·acceptance·영속 schema 변경, 해결되지 않은 필수 계약/reference 충돌, 외부 solver 라이선스·자격증명·비용, 중대한 보안·법률 위험, destructive/remote/release 작업은 [SOLVER_AGENT_DESIGN](docs/SOLVER_AGENT_DESIGN.md)의 사용자 결정 경계를 따른다.
|
||||
|
||||
## 최소 검증 진입점
|
||||
|
||||
아래 명령은 해당 구현·검증 작업에만 사용한다. 문서만 수정하는 작업의 정적 검토를 위해
|
||||
build/test를 실행하지 않는다. 실행할 명령은 승인된 step/plan에서 확인하고,
|
||||
`.harness/config.json`, preset·project metadata와 프로젝트 지침에 대조한 뒤에만 기본값을
|
||||
사용한다. Target graph, dependency normalization과 Windows runtime staging은
|
||||
ARCHITECTURE와 실제 CMake 파일을 따른다.
|
||||
아래 명령은 해당 구현·검증 작업에만 사용한다. 현재 작업, `.harness/config.json`,
|
||||
preset·project metadata와 프로젝트 기준을 대조하여 선택한다. 문서 수정에는 실행하지 않는다.
|
||||
|
||||
### Harness Python 검증
|
||||
|
||||
Harness 구현 변경에 필요한 검사는 관련 범위부터 실행하며 전체 검사가 필요할 때는 다음을 사용한다.
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
```
|
||||
|
||||
### Phase 실행
|
||||
### 구성된 전체 build/test
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase-dir>
|
||||
python scripts/execute.py
|
||||
```
|
||||
|
||||
`<phase-dir>`는 할당된 phase로 대체한다. `--push`는 원격 push가 명시적으로 승인된 경우에만 추가한다.
|
||||
Phase 인자나 `--push`·`--approve-danger-full-access`를 추가하지 않는다. 이 인자들은
|
||||
usage error로 거부된다. Exit 의미·설정·이전 방식 변경 안내는 [HARNESS](docs/HARNESS.md)를
|
||||
따른다. 필요한 수치/reference 검증을 runner 성공만으로 대체하지 않는다.
|
||||
|
||||
### CMake/CTest 프로젝트
|
||||
|
||||
@@ -190,7 +182,10 @@ ctest --preset windows-msvc-ninja-debug --show-only=json-v1
|
||||
ctest --preset windows-msvc-ninja-debug --output-on-failure
|
||||
```
|
||||
|
||||
Hook도 이 preset을 사용하게 구성하려면 [.harness/config.example.json](.harness/config.example.json)을
|
||||
참고해 local `.harness/config.json`의 `binaryDir`, `configurePreset`, `buildPreset`, `testPreset`을
|
||||
함께 맞춘다. Preset 파일이 있다는 사실만으로 Stop이 해당 preset을 선택하지는 않는다.
|
||||
FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를 기준으로 한다.
|
||||
Runner에도 이 preset을 적용하려면 [HARNESS](docs/HARNESS.md)의 예시에 따라 개인
|
||||
`.harness/config.json`의 `binaryDir`, `configurePreset`, `buildPreset`, `testPreset`을
|
||||
함께 맞춘다. 현재 [.harness/config.example.json](.harness/config.example.json)은 최소
|
||||
CMake 설정이며 preset 필드가 없다. Preset 파일이 있다는 사실만으로 runner가 이를
|
||||
선택하지 않는다. FESA 제품 검증은 solution-only MSBuild가 아니라 CMake target과 CTest를
|
||||
기준으로 한다. Target graph·dependency·Windows runtime staging은 ARCHITECTURE와 실제
|
||||
CMake 파일을 따른다.
|
||||
|
||||
+66
-4
@@ -23,8 +23,9 @@ FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한
|
||||
- 현재 선택된 toolchain, 외부 형식과 구현별 계약은 [AGENTS.md](../AGENTS.md) 및 승인된
|
||||
설정·Feature 계약을 따른다. 문서 일반화만으로 이를 교체하지 않는다.
|
||||
- 기존 결정 번호는 다른 의미로 재사용하지 않는다. 후속 결정은 마지막 번호 다음으로 추가한다.
|
||||
- ADR-024~027은 현재 agent·skill·Feature 문서 운영 계약을 기록한다. 새 해석 기능이나
|
||||
외부 실행 권한을 승인하는 결정이 아니다.
|
||||
- ADR-024~027은 당시 agent·skill·Feature 문서 운영 계약의 이력이다. 현행 운영은
|
||||
[ADR-028](#adr-028)을 따른다. 대체 안내 아래의 기존 결정 본문과 그 안의 링크는
|
||||
결정 당시 설명으로 읽으며 현행 절차를 요구하는 근거로 사용하지 않는다.
|
||||
|
||||
## 프로젝트 공통 결정
|
||||
|
||||
@@ -36,7 +37,7 @@ FESA는 유한요소법 기반 구조해석 솔버를 단계적으로 구축한
|
||||
**이유**: 개발 자동화의 편의가 물리적 의미, 사용자 요구와 수치 검증을 대신하지 않게 한다.
|
||||
|
||||
**트레이드오프**: Solver의 완료 evidence와 자동화 자체의 correctness를 별도로 관리해야 한다.
|
||||
현재 운영 역할과 검증 범위는 ADR-024·026에서 보완한다.
|
||||
현재 운영 역할과 검증 범위는 ADR-028을 따른다.
|
||||
|
||||
### ADR-002: 구현·검증 환경은 명시된 프로젝트 baseline으로 관리한다
|
||||
|
||||
@@ -47,7 +48,7 @@ backend를 처리할 수 있다는 사실을 FESA 제품 지원으로 간주하
|
||||
**이유**: 개발 환경의 암묵적 차이가 build와 numerical regression 판정을 흐리지 않게 한다.
|
||||
|
||||
**트레이드오프**: 새 환경은 별도의 compatibility와 실행 evidence가 필요하다. 원문의
|
||||
기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-026의 구성 경계를 따른다.
|
||||
기술 선택 이력은 유지하며, 현재 preset·명령 선택은 ADR-028이 유지하는 구성 경계를 따른다.
|
||||
|
||||
### ADR-003: 외부 입력은 승인된 subset의 의미로 지원한다
|
||||
|
||||
@@ -133,6 +134,9 @@ pattern·scatter와 deterministic reduction을 사용한다.
|
||||
|
||||
### ADR-012: 계획, 실행과 Hook 검증의 책임을 분리한다
|
||||
|
||||
> **부분 대체 — ADR-028:** 전용 Planning/Executor/Hook 분업은 폐기한다. 실제 검증
|
||||
> evidence와 테스트 파일 존재의 구분은 유지한다. 아래 본문은 당시 결정의 이력이다.
|
||||
|
||||
**결정**: Planning은 할당된 계획 파일, Executor는 실행 상태와 Git 처리, Hook은 등록된
|
||||
guardrail과 종료 검증을 담당한다. 테스트 파일 존재는 RED 관찰의 증거가 아니다.
|
||||
|
||||
@@ -245,6 +249,9 @@ ADR-014·020의 과거 수치 정책을 대체하지만 artifact 선택·identit
|
||||
|
||||
### ADR-024: Coordinator가 evidence 기반 workflow와 유한 correction을 소유한다
|
||||
|
||||
> **부분 대체 — ADR-028:** 전용 Coordinator·고정 상태 전이·correction/rerun 예산을
|
||||
> 폐기한다. 승인 범위의 자율 작업, 필요한 사용자 결정과 필수 evidence는 유지한다.
|
||||
|
||||
**상태**: 현재 [agent 운영 계약](SOLVER_AGENT_DESIGN.md)의 기록.
|
||||
ADR-012의 계획·실행·검증 계층을 보완하며 specialist의 계약 소유권을 변경하지 않는다.
|
||||
|
||||
@@ -264,6 +271,9 @@ Release readiness가 외부 게시나 배포 권한을 주지는 않는다.
|
||||
|
||||
### ADR-025: 프로젝트 기준과 Feature 문서의 원본·소유권을 분리한다
|
||||
|
||||
> **부분 대체 — ADR-028:** 관리 문서 4개·coordination 상태 원본·필수 requirements
|
||||
> 분리·전체 bundle 인계를 폐기한다. 프로젝트/Feature 경계, 전문 소유권과 원본 구분은 유지한다.
|
||||
|
||||
**상태**: 현재 [Feature 문서 관리](FEATURE_DOCUMENTATION.md) 계약의 기록.
|
||||
|
||||
**결정**: 프로젝트 PRD·ARCHITECTURE·ADR에는 공통 기준만 둔다. Coordinator는
|
||||
@@ -283,6 +293,9 @@ upstream 변경의 영향과 stale evidence를 추적할 수 있다.
|
||||
|
||||
### ADR-026: Harness의 구성, Git 소유권과 검증 범위를 신뢰 경계로 관리한다
|
||||
|
||||
> **부분 대체 — ADR-028:** Executor의 자동 Git·transport·자체 sandbox 통제와 hook
|
||||
> 검증을 폐기한다. Config/command 신뢰 경계, 사용자 변경 보존과 실제 runtime 권한은 유지한다.
|
||||
|
||||
**상태**: 현재 [Harness skill](../.agents/skills/harness/SKILL.md)과
|
||||
[프로젝트 지침](../AGENTS.md)의 실행 계약 기록. ADR-002의 구체적 실행 구성과
|
||||
ADR-012의 운영 설명을 보완한다.
|
||||
@@ -312,6 +325,9 @@ PreToolUse의 파일 존재 검사는 RED evidence가 아니다. Stop의 문서
|
||||
|
||||
### ADR-027: Harness의 Step 결과와 커밋 범위를 명시적 계약으로 검증한다
|
||||
|
||||
> **실행 계약 대체 — ADR-028:** phase Step payload·owned_paths·attempt_history·자동
|
||||
> commit·transport retry는 더 이상 사용하지 않는다. 실패 증거와 사용자 변경 보존은 유지한다.
|
||||
|
||||
**상태**: 사용자 승인된 Harness 보완 계획(실패 상태 보존, 파일 소유권 검증, 환경 오류
|
||||
분류)에 따른 결정. ADR-026의 실행 경계를 보완하며 solver·Hook·sandbox 권한을 변경하지 않는다.
|
||||
|
||||
@@ -334,6 +350,52 @@ Planning은 Step마다 정확한 상대 파일 목록 `owned_paths`를 작성한
|
||||
경로 검사는 filesystem sandbox나 동시 writer에 대한 원자적 격리가 아니다. 구현·metadata
|
||||
커밋도 단일 transaction이 아니므로 뒤쪽 커밋 실패 시 앞선 커밋을 보존하고 오류로 반환한다.
|
||||
|
||||
<a id="adr-028"></a>
|
||||
|
||||
### ADR-028: 메인이 필요한 전문 작업을 조정하고 Harness를 명시적 검증 실행기로 사용한다
|
||||
|
||||
**상태**: Accepted. 2026-09-07 사용자가 승인한
|
||||
[문서 갱신 계획](superpowers/plans/2026-09-07-agent-harness-documentation-update.md)에 따라
|
||||
Agent·Harness 경량화 결정을 공통 운영 문서에 반영한다. 솔버의 제품·물리·수치·입출력
|
||||
계약과 외부 실행 권한은 변경하지 않는다.
|
||||
|
||||
**결정**:
|
||||
|
||||
- 메인 assistant가 작업 분해, 필요한 전문 작업의 위임, 구현 조정과 완료 확인을 맡는다.
|
||||
7개 specialist는 필요한 경우에만 호출한다. 고정 stage 순회와 전용
|
||||
coordinator/planning/correction/release profile은 사용하지 않는다.
|
||||
- Harness는 `python scripts/execute.py`로 구성된 build/test를 한 번 명시 실행한다.
|
||||
내부 LLM·프롬프트 주입, phase 상태기계, 자동 Git·재시도, 파일명 TDD gate와 대화 종료
|
||||
hook은 사용하지 않는다. 기존 phase와 coordination 기록은 이력으로 보존한다.
|
||||
- 동작 변경은 의미 있는 테스트로 검증하고, 버그는 가능한 경우 재현한 뒤 최소 수정한다.
|
||||
개발 중 관련 검사를 수행하며 솔버 기능 완료 시 전체 build/test와 필수 reference 비교를
|
||||
한 번 수행한다. 이후 변경·실패가 없으면 반복하지 않는다. 수식·요소·재료·적분·상태
|
||||
갱신 변경의 독립 수치 검토와 필요한 analytical/invariant·물리 검증은 유지한다.
|
||||
- 관련 입력 경로/절, 작업·수정 범위와 검증 기준만 인계하고 결과·변경 파일·검사·미해결
|
||||
항목을 간결하게 반환한다. 일반 역할은 `medium`, 정식화·수치·물리 역할은 `high`를
|
||||
기본으로 하며 난해한 작업에만 필요한 범위에서 높인다.
|
||||
- Feature를 초기화하면 메인이 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다.
|
||||
현재 checklist와 작은 요구사항의 원본은 PRD에 둔다. 필요한 상세 계약·결과만 분리하여
|
||||
연결하고 간단한 구현·build/test·reference evidence는 하나의 보고서에 기록한다.
|
||||
Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다.
|
||||
|
||||
이 결정은 ADR-012·024~027의 위에 표시한 운영 부분을 대체한다. Config·preset·실행
|
||||
command는 검토해야 할 실행 입력이며 `shell=False`나 경로 검사가 그 side effect를
|
||||
sandbox처럼 격리하지는 않는다. 사용자 변경·reference를 보존하고 미실행·실패·stale
|
||||
evidence를 통과로 표시하지 않는 원칙, 실제 도구 권한과 외부 작업의 명시적 승인은 유지한다.
|
||||
|
||||
**이유**: 반복적인 문맥 주입, 역할 전환, 형식적 보고와 중복 검증을 줄이면서 필요한
|
||||
공학적 판단과 재현 가능한 evidence에 집중한다.
|
||||
|
||||
**트레이드오프**: 고정 상태기계나 자동 Git gate가 완료·변경 범위를 강제하지 않으므로
|
||||
메인이 할당 범위, 필요한 검증과 미해결 항목을 확인한다. 명령 실패의 원인은 현재 구현
|
||||
owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.
|
||||
|
||||
역할과 호출 조건은 [Agent 운영](SOLVER_AGENT_DESIGN.md), skill 적용은
|
||||
[Skill 설계](SOLVER_SKILL_DESIGN.md), 문서 원본과 소유권은
|
||||
[Feature 문서 관리](FEATURE_DOCUMENTATION.md), CLI·설정과 실패 진단은
|
||||
[Harness](HARNESS.md) 및 [동작 과정](HARNESS_WORKFLOW.md)을 따른다.
|
||||
|
||||
## 후속 ADR 작성 기준
|
||||
|
||||
프로젝트 전체의 dependency 방향, 공통 identity·수명·결과 의미, 기술 baseline,
|
||||
|
||||
+32
-40
@@ -37,13 +37,13 @@ Solver runtime
|
||||
└─ numerical backend
|
||||
|
||||
개발 운영 영역
|
||||
사용자 요구 → Coordinator → 담당 specialist → 산출물과 evidence → gate 판정
|
||||
│
|
||||
└─ 할당된 계획 / Harness / 코드·테스트·문서 변경
|
||||
사용자 요구 → 메인 assistant → 필요한 전문 작업·구현 → 검증·결과 확인
|
||||
│
|
||||
└─ 명시적 Harness / 코드·테스트·문서 변경
|
||||
```
|
||||
|
||||
첫 흐름은 해석 데이터의 전달을, 두 번째는 개발 작업과 검증의 흐름을 나타낸다.
|
||||
Agent, prompt, phase 파일과 Harness는 solver runtime API나 물리 모델의 일부가 아니다.
|
||||
Agent, skill과 Harness는 solver runtime API나 물리 모델의 일부가 아니다.
|
||||
개발 운영 영역은 저장소의 변경과 검증을 통제하며 solver가 실행 중 이를 호출하지 않는다.
|
||||
|
||||
## 공통 책임과 의존성
|
||||
@@ -193,8 +193,10 @@ Diagnostic은 실패 단계, 안정된 code와 메시지, 가능한 source locat
|
||||
## 검증과 reference 경계
|
||||
|
||||
검증 coverage와 비교량의 논리적 정의는 Numerical Review, 물리량의 저장·외부 대응은
|
||||
I/O, 실행 evidence는 Implementation, 독립 물리 판단은 Physics Evaluation이 소유한다.
|
||||
각 단계는 상위 계약을 결과에 맞춰 수정하지 않는다.
|
||||
I/O, 실행 evidence는 구현 담당자, 독립 물리 판단은 Physics Evaluation의 전문 책임이다.
|
||||
메인은 작업에 필요한 전문 판단만 배정하며 고정 stage 순회를 요구하지 않는다. 수식·요소·
|
||||
재료·적분·상태 갱신 변경에는 독립 수치 검토와 해당 analytical/invariant 검증을 수행한다.
|
||||
각 담당자는 상위 계약을 결과에 맞춰 수정하지 않는다.
|
||||
|
||||
- Source identity, location과 component 일치 여부를 수치 tolerance보다 먼저 확인한다.
|
||||
- Missing, extra, duplicate와 nonfinite required value를 숨기지 않는다.
|
||||
@@ -208,50 +210,40 @@ Architecture 문서의 그림이나 모듈명이 기능의 완료 증거를 대
|
||||
|
||||
## 개발 운영 인프라
|
||||
|
||||
공통 agent 상태 전이는 [SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill의 역할은
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실제 실행 절차는
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 agent/skill profile을 읽는다.
|
||||
현행 운영은 [ADR-028](ADR.md#adr-028), 역할·인계는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), skill 적용은
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md)을 따른다. 실행 동작은
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)과 현재 source·config에 대조한다.
|
||||
|
||||
| Owner | 책임 |
|
||||
| --- | --- |
|
||||
| Coordinator | Feature 문서 목록·상태, dispatch, evidence gate, revision·retry budget과 closure |
|
||||
| Specialist | 할당된 stage의 전문 판단, 기본·상세 산출물과 공통 handoff |
|
||||
| Planning Agent | 할당된 implementation plan과 phase/index/step 계획 파일 |
|
||||
| Executor | 현재 step 선택, branch, transport attempt, timestamp, path-scoped commit과 phase 진행 |
|
||||
| Implementation Agent | 선택된 step의 코드·테스트·보고서와 result payload |
|
||||
| Hook | 도구 호출 전 guardrail과 설정된 종료 검증; TDD 관찰이나 완전한 sandbox의 대체가 아님 |
|
||||
| 메인 assistant | 범위·작업 분해, 필요한 전문 작업 배정, 직접 계획·구현·수정, Feature context와 완료 evidence 확인 |
|
||||
| Specialist | 할당된 전문 판단·파일과 간결한 결과; 상위 계약 문제를 owner와 메인에 전달 |
|
||||
| 구현 담당자 | 메인 또는 implementation-agent로서 코드·테스트·관련 검증과 필요한 reference evidence 작성 |
|
||||
| Harness runner | 명시 호출 시 config·project·toolchain 선택, adapter 계획 실행과 결과 반환 |
|
||||
| Backend adapter/process | CMake/CTest 또는 MSBuild 명령 구성, argv/cwd·timeout·실패·결과 검사 |
|
||||
|
||||
Coordinator만 workflow를 전이한다. Specialist의 outcome은 전이 요청이고, Harness의
|
||||
step 상태는 별개의 실행 상태다. Executor transport attempt는 최대 2회이며 동일
|
||||
`retry_key`의 correction 1회와 뒤따르는 Implementation rerun은 Coordinator가 관리한다.
|
||||
두 budget을 혼용하거나 실패 문구만 바꿔 반복하지 않는다.
|
||||
Runner는 내부 LLM, phase 상태기계, 자동 Git·retry, 파일명 TDD gate나 대화 종료 hook을
|
||||
사용하지 않는다. 과거 phase/coordination 기록은 이력으로 보존한다. 일반 실패는 현재
|
||||
구현 owner가 수정하며 새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않는다.
|
||||
|
||||
승인된 scope와 할당된 작업 안의 일반 계획·문서·local 실행에는 반복 승인 gate를
|
||||
추가하지 않는다. 계획 요청만으로 실행을 시작하지 않으며 외부 solver, 원격·파괴 작업과
|
||||
sandbox 권한 확대에는 해당 명시적 권한이 필요하다.
|
||||
Project config·preset·command는 검토해야 할 실행 입력이다. Repository 경로 검사,
|
||||
`shell=False`와 timeout이 실행 파일의 side effect를 모두 격리하는 sandbox는 아니다.
|
||||
사용자 변경을 보존하고 실제 도구 권한과 외부 solver·원격·파괴 작업의 명시적 승인을 따른다.
|
||||
승인된 일반 작업에 반복 승인을 추가하지 않으며 계획 요청만으로 실행을 시작하지 않는다.
|
||||
|
||||
Project config, preset과 실행 command는 검토해야 하는 실행 입력이다. Hook 통과나
|
||||
구조화된 argument list만으로 그 side effect가 격리되었다고 간주하지 않는다.
|
||||
Executor는 시작 전 선택된 phase 제어 파일 밖의 변경을 거부하며 모든 pending Step의
|
||||
Planning 소유 `owned_paths`를 검증한다. 매 시도 후와 stage/commit 경계에서 신뢰된 목록과
|
||||
변경·staged 경로를 대조하고 구현 변경과 phase metadata를 분리한다. 범위 밖 변경은
|
||||
보존하고 재시도·커밋·다음 Step을 중단한다. 이 검사는 동시 writer의 원자적 격리나 여러
|
||||
커밋의 단일 transaction을 보장하지 않는다. 실행 중 동시 편집을 피한다.
|
||||
종료 코드와 Step 보고 상태를 함께 판정하며 명시적 실패를 transport 재시도로 덮어쓰지
|
||||
않는다. 실제 wrapper timeout이고 결과 미보고일 때만 최초 포함 최대 두 번 시도한다.
|
||||
환경·실패 진단과 원래 보고는 Executor 소유 `attempt_history`에 남기고 재개 때 보존한다.
|
||||
등록된 Hook을 수동 실행하여 검증 evidence를 대신하지 않는다.
|
||||
|
||||
문서 전용 Stop 생략은 기록된 동일 session/turn의 허용된 편집 대상이 모두 저장소 내부
|
||||
Markdown인 조건에 한정된다. 기록이 없거나 불완전한 읽기 전용 작업과 shell 쓰기까지
|
||||
안전하게 분류한다고 가정하지 않는다. 생략은 build/test 통과가 아니다.
|
||||
사용자가 실행을 제외한 문서 작업은 정적 검토와 미실행 항목을 보고한다.
|
||||
변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 계약상 필수
|
||||
reference 비교를 한 번 수행한다. 요청이나 넓은 영향으로 전체 검증이 필요한 경우에도
|
||||
실행하고 이후 변경·실패가 없으면 반복하지 않는다. 문서 작업은 정적 검토로 확인한다.
|
||||
명령·exit code·판정값과 미실행 항목을 필요한 보고서에 기록하며 Harness 성공만으로
|
||||
물리·수치 correctness나 외부 release readiness를 선언하지 않는다.
|
||||
|
||||
## 문서와 아키텍처의 변경
|
||||
|
||||
프로젝트 공통 원칙의 변경은 공통 ADR로, 구현 항목별 선택은 해당 Feature ADR로
|
||||
기록한다. Feature PRD는 범위와 acceptance 요약을, requirements·formulation·I/O는
|
||||
전문 계약의 원본을 소유한다. 관리 문서와 기본·상세 산출물은
|
||||
기록한다. Feature PRD는 범위·작은 요구사항·acceptance와 현재 checklist의 원본이다.
|
||||
복잡한 requirements·formulation·I/O는 필요한 경우에만 전문 문서로 분리하고 PRD에서
|
||||
참조하여 원본을 중복하지 않는다. 메인이 관리하는 핵심 문서 3개와 선택적 상세 산출물은
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)의 소유권과 링크 규칙을 따른다.
|
||||
|
||||
Public dependency, identity, 수명, result meaning이나 lifecycle 변경은 영향받는
|
||||
|
||||
+12
-10
@@ -4,7 +4,7 @@
|
||||
|
||||
이 문서는 FESA production 및 test C++의 코드 스타일, 객체 설계, 문서화와 검증 규칙을
|
||||
정의하는 project-local source of truth다. 새 C++를 작성하거나 기존 C++를 리팩터링하는
|
||||
사람과 Implementation Agent는 작업 전에 이 문서를 읽어야 한다.
|
||||
메인 assistant와 구현 담당자는 작업에 관련된 규칙을 확인한다.
|
||||
|
||||
[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)를 baseline으로
|
||||
사용한다. 이 문서, `AGENTS.md`, 승인된 feature contract와 architecture/ADR이 Google guide의
|
||||
@@ -217,12 +217,14 @@ contract language는 현재 외부 계약을 유지한다.
|
||||
|
||||
## Test와 변경 관리
|
||||
|
||||
- Production C++ 변경은 관련 C++ test와 같은 patch에 있어야 한다.
|
||||
- Behavior 또는 interface 변경은 `RED -> observed failure -> minimal GREEN -> VERIFY`를
|
||||
따른다.
|
||||
- Production 동작·interface 변경은 해당 의미를 확인하는 테스트를 추가·수정하여 검증한다.
|
||||
- 버그는 가능한 경우 실패를 재현한 뒤 최소 수정하고 관련 검사를 실행한다. 기존 coverage가
|
||||
충분한 rename/refactor에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
- Refactoring test는 base interface 사용, ownership/lifetime, invalid combination,
|
||||
deterministic order와 current numerical result preservation을 검증한다.
|
||||
- Focused test 뒤에 full MSVC x64 Debug build와 CTest를 실행한다.
|
||||
- 개발 중에는 관련 검사를 실행하고, 솔버 기능 완료 시 full MSVC x64 Debug build와 CTest를
|
||||
한 번 수행한다. 요청이나 넓은 변경 영향으로 필요한 경우에도 실행하며 이후 변경·실패가
|
||||
없으면 반복하지 않는다. 문서만 수정할 때는 정적 검토를 수행한다.
|
||||
- B33/MITC4 output 경계를 건드린 변경은 승인된 reference comparison을 다시 실행한다.
|
||||
- Reference artifact, input path와 tolerance를 리팩터링에 맞춰 수정하지 않는다.
|
||||
- Commit은 review 가능한 module slice로 제한하고 Conventional Commits를 사용한다.
|
||||
@@ -243,14 +245,14 @@ doxygen Doxyfile
|
||||
|
||||
Generated Doxygen HTML과 tool cache/build output은 source control에 넣지 않는다.
|
||||
|
||||
## Implementation Agent Checklist
|
||||
## 구현 담당자 Checklist
|
||||
|
||||
Implementation Agent는 C++ Step을 시작하기 전에 다음을 확인한다.
|
||||
메인 또는 구현 agent는 할당된 C++ 작업 전에 다음을 확인한다.
|
||||
|
||||
- 이 문서와 feature implementation plan을 읽었다.
|
||||
- 관련 코딩 규칙·Feature 계약과 필요한 경우의 구현 계획을 확인했다.
|
||||
- 변경할 base/concrete/module owner가 승인 설계와 일치한다.
|
||||
- 관련 test file과 RED condition이 Step에 명시되어 있다.
|
||||
- 변경 동작을 확인할 검사와 가능한 버그 재현 조건을 정했다.
|
||||
- Public API naming과 production Doxygen가 이 문서에 맞는다.
|
||||
- Vendor dependency와 ownership direction이 역전되지 않는다.
|
||||
- Stable identity, numerical order, HDF5와 reference contract가 보존된다.
|
||||
- Formatting, Doxygen, focused/full MSVC/CTest acceptance command가 계획되어 있다.
|
||||
- Formatting, Doxygen와 변경 영향에 맞는 MSVC/CTest·reference 검증 범위 및 명령을 정했다.
|
||||
|
||||
@@ -1,79 +1,82 @@
|
||||
# Feature 문서 관리
|
||||
|
||||
이 규칙은 모든 agent의 Feature 산출물에 적용한다. Coordinator는 요구사항을 받으면
|
||||
`docs/<feature-id>/`를 생성하고 문서 목록, 참조와 workflow 상태를 관리한다.
|
||||
`<feature-id>`는 Coordinator가 정한 안정적인 kebab-case 이름이며 모든 dispatch에서 공유한다.
|
||||
지속할 요구사항·계약·검증 evidence가 필요한 solver Feature에는 `docs/<feature-id>/`를
|
||||
사용한다. 메인 assistant가 안정적인 kebab-case Feature ID를 정하고 context와 문서 목록을
|
||||
관리한다. 작은 수정에는 새 Feature 폴더나 빈 보고서를 만들지 않는다.
|
||||
현재 운영은 [ADR-028](ADR.md#adr-028)과 [Agent 계약](SOLVER_AGENT_DESIGN.md)을 따른다.
|
||||
|
||||
## 시작과 참조
|
||||
|
||||
1. 새 요구사항이면 Feature 폴더를 만들고 아래 관리 문서 4개를 작성한다. 같은 Feature를
|
||||
재개하면 기존 문서와 상태를 읽고 필요한 부분만 갱신한다.
|
||||
2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 읽기 전용
|
||||
기준으로 참조한다. Feature 진행을 위해 본문이나 현재 작업 링크를 추가·수정하지 않는다.
|
||||
3. 각 agent는 dispatch의 Feature 폴더에서 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 읽고
|
||||
자신에게 필요한 계약과 상세 문서만 따라간다. `FEATURED_AGENTS.md`는 자동으로 로드되는
|
||||
`AGENTS.md`가 아니므로 Coordinator가 모든 dispatch와 Harness step의 필수 입력에 명시한다.
|
||||
4. 기존 `docs/features/<feature-id>/` 자료는 이력이므로 자동 이동하거나 복제하지 않는다.
|
||||
재개에 필요한 기존 자료는 새 폴더의 문서 목록에서 경로와 revision으로 참조한다.
|
||||
1. 새 Feature 폴더를 초기화하면 아래 핵심 문서 3개를 실제 요구사항으로 작성한다.
|
||||
재개 시 기존 계약과 evidence를 읽고 필요한 부분만 갱신한다.
|
||||
2. 프로젝트 [AGENTS.md](../AGENTS.md), [PRD.md](PRD.md), [ADR.md](ADR.md)는 일반 Feature
|
||||
작업에서 읽기 전용 기준이다. Feature 진행 링크를 공통 문서에 누적하지 않으며 공통
|
||||
지침 변경은 별도 사용자 요청 범위에서 수행한다.
|
||||
3. Specialist는 할당 작업에 관련된 Feature 문서와 원문의 절만 읽는다.
|
||||
`FEATURED_AGENTS.md`는 자동 로드되는 `AGENTS.md`가 아니므로 필요한 context는
|
||||
메인이 경로·절로 전달한다. 모든 인계에서 핵심 문서 3개를 재독하도록 강제하지 않는다.
|
||||
4. 기존 `docs/features/<feature-id>/`와 `coordination.md`는 이력으로 보존한다.
|
||||
자동 이동·복제하지 않고 재개에 필요한 경로·계약 revision을 참조한다.
|
||||
`coordination.md`를 새로 생성하거나 현재 상태 기록을 위해 갱신하지 않는다.
|
||||
|
||||
이 경로 규칙은 사용자가 요청한 Feature 문서 배치에 적용한다. 프로젝트 `AGENTS.md`의
|
||||
기존 `docs/features/` 표기는 이력 경로로 남기며, 그 밖의 프로젝트 규칙은 계속 따른다.
|
||||
Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 충돌하는 변경은 해당
|
||||
계약 owner에게 반환하고, 필요한 critical decision은 기존 workflow에 따라 처리한다.
|
||||
Feature 문서는 공통 기준을 복사하거나 묵시적으로 덮어쓰지 않는다. 실제 상위 계약 문제는
|
||||
해당 owner와 메인에 evidence를 전달하고 필요한 사용자 결정을 따른다.
|
||||
|
||||
## Coordinator 관리 문서
|
||||
## 메인이 관리하는 핵심 문서
|
||||
|
||||
| 문서 | 필요한 내용 | 참조 기준 |
|
||||
| 문서 | 필요한 내용 | 프로젝트 기준 링크 |
|
||||
| --- | --- | --- |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적, 이 작업에만 적용되는 지침, agent별 소유 산출물, 문서 목록과 현재 상태 문서 링크 | `../../AGENTS.md`, `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md` |
|
||||
| `PRD.md` | 사용자 요구 요약, 범위·제외, acceptance 요약, 검토 상태와 requirement ID별 계약 링크 | `../PRD.md`, `requirements.md`가 작성되면 해당 문서 |
|
||||
| `ADR.md` | Feature 결정 ID, 상태, 결정·이유·영향, 결정 owner와 승인 근거 링크 | `../ADR.md`, 관련 specialist 계약 |
|
||||
| `coordination.md` | 현재 stage·outcome·next owner·contract revision, gate 증거, retry 이력, blocker와 다음 작업 | 공통 handoff envelope와 해당 산출물 |
|
||||
| `FEATURED_AGENTS.md` | Feature ID·목적·지역 지침, 할당된 owner와 유용한 문서 목록. 현재 checklist는 PRD에 연결 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
|
||||
| `PRD.md` | 사용자 요구·범위·제외·acceptance와 현재 checklist. 작은 요구사항의 원본, 필요한 상세 계약 링크 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
|
||||
| `ADR.md` | Feature 결정 ID·상태·결정·이유·영향과 owner·승인 근거. 실제 결정이 없으면 그 사실과 적용 공통 결정 | `../../AGENTS.md`, `../PRD.md`, `../ADR.md` |
|
||||
|
||||
- 각 관리 문서는 현재 Feature ID와 실제 프로젝트 기준 문서에 대한 상대 Markdown 링크를
|
||||
가진다. `FEATURED_AGENTS.md`의 목록은 산출물 경로, owner, revision·검토 상태를 기록한다.
|
||||
현재 stage 등 workflow 상태의 원본은 `coordination.md`이고 목록에서는 이를 참조한다.
|
||||
- 최초 `PRD.md`에는 실제 받은 요구사항과 아직 검토되지 않은 상태를 적는다. `ADR.md`에
|
||||
결정이 없으면 그 사실과 적용할 공통 ADR 참조를 적는다. 승인되지 않은 내용을 승인으로
|
||||
표시하거나 이후 stage의 빈 보고서를 미리 만들지 않는다.
|
||||
- `requirements.md`의 검증 가능한 요구사항과 matrix는 Requirement Agent가 소유한다.
|
||||
Coordinator는 `PRD.md`에 요약과 링크를 반영하며 별도 요구사항 원본을 만들지 않는다.
|
||||
- Coordinator는 각 owner의 반환을 확인한 뒤 목록·상태·`PRD.md`·`ADR.md`의 필요한 참조를
|
||||
갱신한다. 전문 판단을 대신하거나 specialist 본문을 수정하지 않는다.
|
||||
- Feature별 결정은 이 폴더의 `ADR.md`에 기록한다. 프로젝트 전반의 기준 변경은 별도 사용자
|
||||
요청 범위에서 다루며, Feature 작업만으로 프로젝트 기준 문서를 갱신하지 않는다.
|
||||
- 현재 checklist는 PRD 한 곳에서 관리한다. 문서 목록이나 별도 파일에 같은 상태를
|
||||
중복 기록하지 않는다.
|
||||
- 작은 요구사항·acceptance는 PRD에 직접 정의한다. 복잡하여 분리할 필요가 있을 때만
|
||||
`requirements.md`나 상세 verification matrix를 작성하고 PRD에는 요약과 링크를 둔다.
|
||||
분리된 전문 계약은 할당된 owner가 소유한다.
|
||||
- 메인은 관련 반환을 확인하여 목록·링크·checklist를 갱신한다. Specialist는 할당된
|
||||
문서만 수정하며 downstream이 upstream 계약을 결과에 맞춰 변경하지 않는다.
|
||||
- 승인되지 않은 내용이나 아직 실행하지 않은 검증을 승인·완료로 표시하지 않는다.
|
||||
일반 문서 작성·업데이트를 위해 반복적인 승인 gate를 추가하지 않는다.
|
||||
- 각 핵심 문서는 실제 프로젝트 기준을 상대 Markdown 링크로 연결한다. 필요한 운영
|
||||
설명은 `../SOLVER_AGENT_DESIGN.md`, `../FEATURE_DOCUMENTATION.md`를 참조한다.
|
||||
|
||||
## Agent 산출물 작성
|
||||
## 필요한 상세 문서와 evidence
|
||||
|
||||
각 stage의 기본 문서는 다음 순서로 필요한 내용만 작성한다. 해당하지 않는 항목은 생략하되
|
||||
필수 검증을 수행하지 않은 경우에는 미실행 사실과 이유를 남긴다.
|
||||
결과를 지지하는 다음 내용만 필요한 만큼 기록한다.
|
||||
|
||||
1. 식별: Feature ID, owner, 입력 contract revision.
|
||||
2. 핵심 결과: 결정 또는 verdict, 구현·검토에 필요한 계약과 주요 발견.
|
||||
3. 증거: requirement ID, 출처나 산출물 링크, 실제 명령·exit code·test 수와 핵심 판정값.
|
||||
4. 인계: 미해결 항목, 제한·위험, 공통 envelope와 상세 문서 참조.
|
||||
1. 해당 Feature·작업·owner와 적용 계약 또는 관련 revision.
|
||||
2. 판단·결정, 구현·검토에 필요한 정의와 주요 발견.
|
||||
3. 출처·evidence 경로, 실제 명령·exit code·결정적 측정값과 적용 기준.
|
||||
4. 가정, 미지원 범위, 미해결 항목·제한과 다음 작업에 필요한 정보.
|
||||
|
||||
상위 문서의 설명, 이미 정의된 요구사항과 원시 로그를 반복하지 않는다. 적용되는 requirement,
|
||||
수식, schema, tolerance와 acceptance 조건은 짧게 정리하거나 정확한 문서 절로 연결한다.
|
||||
분량을 줄이기 위해 필수 정의나 검증 근거를 없애지 않는다.
|
||||
`research.md`, `formulation.md`, `io.md`, `numerical-review.md`,
|
||||
`reference-model.md`, `implementation-report.md`, `build-test.md`,
|
||||
`reference-comparison.md`, `physics-evaluation.md`는 필요한 경우의 산출물 예시다.
|
||||
간단한 구현·build/test·reference 결과는 하나의 짧은 보고서에 모을 수 있으며 같은 결과를
|
||||
여러 기본 보고서에 반복하지 않는다. Release 보고서는 명시적으로 감사를 요청한 경우에만 작성한다.
|
||||
|
||||
긴 유도, 전체 mapping·검증 matrix, 사례별 계산 또는 상세 실행 분석이 필요하면 같은 폴더에
|
||||
`<산출물-stem>-<주제>.md`로 분리한다. 예를 들어 `formulation-derivation.md`에는 수식 유도를,
|
||||
`io-schema.md`에는 상세 schema를 둔다. 짧은 내용은 기본 문서에 유지한다.
|
||||
긴 유도·전체 schema·mapping·검증 matrix가 필요하면 같은 폴더의
|
||||
`formulation-derivation.md`, `io-schema.md` 같은 문서로 분리하여 관련 본문에서 연결한다.
|
||||
상세 문서는 해당 전문 owner가 소유하고 적용되는 계약과 기본 문서를 명확히 연결한다.
|
||||
반환할 때 판단에 사용한 상세 evidence 경로도 포함한다. 고정 envelope나 모든 산출물의
|
||||
hash·gate 기록은 요구하지 않는다.
|
||||
|
||||
- 상세 문서는 기본 산출물 owner가 작성·수정한다. 이 권한은 해당 stage 범위의 문서에만
|
||||
적용되며 다른 stage의 계약이나 Coordinator 관리 문서 편집 권한을 주지 않는다.
|
||||
- 기본 문서의 관련 항목에서 상대 Markdown 링크와 필요한 절을 연결하고, 상세 문서에서도
|
||||
기본 문서와 동일 Feature ID·입력 revision을 명시한다. 같은 내용을 양쪽에 유지하지 않는다.
|
||||
- 반환 envelope의 `evidence_paths`에는 기본 문서와 새로 작성·갱신하거나 판정에 사용한 상세
|
||||
문서를 포함한다. Coordinator가 실제 파일과 링크를 확인하고 문서 목록에 등록한다.
|
||||
- 모든 agent 보고서는 `docs/<feature-id>/`에 저장한다. 소스·테스트·Harness 제어 파일과
|
||||
기계 생성 로그·결과·read-only reference artifact는 각자의 지정 경로에 유지하고 보고서에서
|
||||
참조한다.
|
||||
짧게 쓰기 위해 필수 수식·identity·units·schema·tolerance·acceptance 정의를 없애지 않는다.
|
||||
문서만 수정할 때 원시 로그나 의미 변화 없는 revision 기록을 추가하지 않는다. 실제 계약이
|
||||
변경되면 관련 evidence가 여전히 유효한지 확인하며 과거 결과를 현재 검증으로 소급하지 않는다.
|
||||
필수 검증을 실행하지 않았다면 미실행 사실과 이유를 남긴다.
|
||||
|
||||
## Gate 확인
|
||||
소스·테스트·기계 생성 로그/결과·read-only reference artifact는 각자의 지정 경로에 유지하고
|
||||
보고서에서 참조한다. 기존 phase 이력은 새 보고서 형식에 맞추어 변경하지 않는다.
|
||||
Reference artifact와 tolerance를 구현 결과에 맞추어 수정하지 않는다.
|
||||
|
||||
Coordinator는 기존 evidence gate에 더해 Feature 폴더, 관리 문서, 소유권과 상대 링크를 확인한다.
|
||||
판정에 사용된 상세 문서는 기본 문서와 같은 revision·stale 판정·상위 계약 변경 규칙을 따른다.
|
||||
필수 상세 근거가 누락되거나 연결이 끊긴 경우 해당 owner에게 반환한다. 요약만으로 상세 근거의
|
||||
검증을 대신하지 않는다.
|
||||
## 언어와 확인
|
||||
|
||||
기본 Feature 문서는 한국어 Markdown으로 작성하고 agent/skill ID, field, requirement ID,
|
||||
경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은 `FEM-REQ-<FEATURE>-###`다.
|
||||
|
||||
메인은 실제 파일·소유권·상대 링크와 판단에 필요한 evidence를 확인한다. 필수 상세 근거가
|
||||
없거나 연결이 끊겼다면 해당 owner와 해결하고 요약만으로 검증을 대신하지 않는다.
|
||||
문서 정리는 정적 검토로 확인하며 solver build나 수치/reference 검증의 통과로 보고하지 않는다.
|
||||
|
||||
+91
-117
@@ -1,84 +1,46 @@
|
||||
# Harness 운영 가이드
|
||||
|
||||
## Requirements
|
||||
## 목적과 준비 환경
|
||||
|
||||
Windows와 Codex CLI가 필요하다. Executor는 Python 3.10 이상을 사용하며, 이 저장소의
|
||||
계약 테스트는 표준 `tomllib`을 사용하므로 검증 환경은 Python 3.11 이상으로 준비한다.
|
||||
Harness는 명시적으로 호출하는 repository build/test 실행기다.
|
||||
[Agent 운영](SOLVER_AGENT_DESIGN.md)과 [Harness skill](../.agents/skills/harness/SKILL.md)에
|
||||
따라 필요한 검증을 수행하며 내부 Codex 호출, phase 관리, 자동 Git 처리와 대화 종료
|
||||
hook을 사용하지 않는다. 현재 운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다.
|
||||
|
||||
Runner에는 Windows와 Python 3.10 이상이 필요하다. 저장소의 `tomllib` 기반 Python 검사는
|
||||
Python 3.11 이상을 사용한다. Runner 자체는 Codex CLI를 필요로 하지 않는다.
|
||||
FESA는 Visual Studio의 Desktop development with C++ 워크로드, CMake/CTest와 Ninja를
|
||||
사용한다. MSVC x64 developer 환경과 dependency 경로는 [AGENTS.md](../AGENTS.md)의
|
||||
최소 검증 진입점을 따른다.
|
||||
사용한다. MSVC x64 developer 환경에서 `FESA_GTEST_SOURCE_DIR`, `MKL_DIR`, `TBB_DIR`,
|
||||
`HDF5_DIR`를 설치된 dependency 경로로 설정한다. 상세 기준은
|
||||
[프로젝트 지침](../AGENTS.md)의 최소 검증 진입점을 따른다.
|
||||
|
||||
역할·승인·상태 전이는 [Agent 계약](SOLVER_AGENT_DESIGN.md)과
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md)을 따른다. 이 문서는 설치·실행 참고이며
|
||||
solver Feature의 9개 stage와 evidence gate를 대신하지 않는다.
|
||||
## 명시적 실행과 설정 선택
|
||||
|
||||
## 프로젝트 자동 감지
|
||||
|
||||
프로젝트 형식은 다음 순서로 결정한다: `.harness/config.json`의 명시적 type, 루트의
|
||||
CMake metadata, 하나의 `.sln`, 하나의 `.vcxproj` 순서다. C/C++가 아닌 저장소는
|
||||
건너뛰며, C/C++ 파일은 있지만 CMake/solution metadata가 없는 orphan-C++ 저장소는
|
||||
오류로 처리한다.
|
||||
|
||||
설정 파일은 선택 사항이다. 기본 자동 감지와 `.harness/build` 경로를 그대로 사용할
|
||||
때는 만들지 않아도 된다. 프로젝트별 override가 필요하면 다음처럼 예시를 복사한다.
|
||||
저장소 루트에서 구성된 전체 검증을 한 번 실행한다.
|
||||
|
||||
```powershell
|
||||
Copy-Item .harness/config.example.json .harness/config.json
|
||||
python scripts/execute.py
|
||||
```
|
||||
|
||||
승인된 Feature와 Coordinator dispatch에 따라 Planning Agent가 할당된 phase 파일을
|
||||
작성한다. 일반 계획 파일 작성에 반복 승인을 요구하지 않는다. 실행까지 할당된 경우에만
|
||||
다음 명령을 사용하며, 계획 작성 요청만으로 Executor를 시작하지 않는다.
|
||||
개발 중 focused check는 선택된 backend의 실제 명령을 직접 실행한다. 솔버 기능 완료 시
|
||||
구성된 전체 build/test와 계약상 필수 reference 비교를 수행하고 이후 변경·실패가 없으면
|
||||
반복하지 않는다. 문서만 변경하는 작업에서는 정적 검토를 하고 build/test를 실행하지 않는다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py <phase-name>
|
||||
```
|
||||
Runner는 자신의 script 위치를 기준으로 저장소 root를 정하고 `.harness/config.json`을
|
||||
읽는다. 설정이 없으면 기본 자동 감지를 사용한다. 선택 순서는 명시한 `projectType`,
|
||||
설정된 CMake source directory의 metadata, root의 단일 `.sln`, 단일 `.vcxproj`다.
|
||||
여러 solution/project로 선택이 모호하면 명시 설정이 필요하다. C++ source 전체를
|
||||
scan하거나 metadata 없는 C++ 파일의 존재로 별도 gate를 적용하지 않는다.
|
||||
|
||||
`--push`는 해당 원격 push를 사용자가 명시적으로 승인했을 때만 추가한다. 실행 전
|
||||
Git top-level은 Harness root와 같고 선택된 phase 제어 파일 밖의 worktree는 clean이어야
|
||||
한다. 실행 중 동시 편집과 커밋 범위의 한계는 [동작 과정](HARNESS_WORKFLOW.md)을 따른다.
|
||||
현재 [config 예시](../.harness/config.example.json)는 `projectType=cmake`와
|
||||
`cmake.sourceDir=.`만 지정한다. 개인 설정이 필요할 때 참고하되 기존 설정을 무조건
|
||||
덮어쓰지 않는다. Preset 없는 기본 binary directory는 `.harness/build`다.
|
||||
|
||||
모든 `pending` Step에는 승인된 정확한 상대 파일 목록인 `owned_paths`가 필요하다.
|
||||
누락된 기존 phase는 Planning의 할당된 준비 작업에서 목록을 보완한 뒤 실행한다.
|
||||
`[]`는 구현 파일 변경이 없음을 뜻하며 완료 이력에는 목록을 소급 추가하지 않는다.
|
||||
Executor는 실행 후와 staging/commit 경계에서 소유권을 검사하며 범위 밖 변경은
|
||||
보존하고 중단한다. 상세 schema와 제한은 [Harness skill](../.agents/skills/harness/SKILL.md)을 따른다.
|
||||
## FESA CMake preset 설정
|
||||
|
||||
Executor가 시작하는 Codex 세션은 기본적으로 `workspace-write` sandbox를 사용한다.
|
||||
Windows native sandbox에서 MSVC compiler-id의 `cl.exe`가 정지하는 것이 재현되고 같은
|
||||
명령이 sandbox 밖에서 정상 완료되는 경우에만, 사용자 승인을 받은 격리된 clean
|
||||
linked Git worktree에서 다음처럼 해당 실행에 한정해 fallback을 지정할 수 있다.
|
||||
|
||||
```powershell
|
||||
$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
|
||||
python scripts/execute.py <phase-name> --approve-danger-full-access
|
||||
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX
|
||||
```
|
||||
|
||||
허용값은 `workspace-write`와 `danger-full-access`뿐이다. 후자는 Codex Step에 workspace
|
||||
밖의 파일 접근 권한도 부여하므로 일반 기본값으로 설정하지 않는다. 어느 모드에서도
|
||||
`.codex/hooks.json`의 등록된 hook을 비활성화하지 않는다. 환경변수만으로 권한이 승인되지
|
||||
않으며 Executor는 승인 flag가 없거나 primary/dirty worktree인 권한 상승 실행을 거부한다.
|
||||
|
||||
Stop은 유효한 동일 session/turn 편집 기록의 대상이 모두 저장소 내부 `.md`일 때만
|
||||
build/test를 생략한다. 기록 누락·손상 또는 비문서 편집은 정상 검증 경로를 따른다.
|
||||
Shell 쓰기나 편집 기록 없는 읽기 전용 요청도 자동 생략을 보장하지 않는다. 문서 작업에서
|
||||
사용자가 실행을 제외하면 수동으로 Hook·build/test를 실행하지 않고 미검증 사실을 보고한다.
|
||||
|
||||
## Harness Python 검증
|
||||
|
||||
이 저장소의 테스트와 최종 acceptance 검증은 pytest를 시스템 Python에 설치하지 않고
|
||||
다음 명령으로 실행한다.
|
||||
|
||||
```powershell
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
```
|
||||
|
||||
## CMake preset 설정
|
||||
|
||||
`projectType`을 `cmake`로 지정하거나 자동 감지를 사용한다. `cmake.sourceDir`,
|
||||
`binaryDir`, `configurePreset`, `buildPreset`, `testPreset`은 preset을 사용할 때 함께
|
||||
지정해야 한다. 빌드 산출물은 저장소의 `.harness/build/`처럼 격리된 경로에 둔다.
|
||||
FESA의 현재 [CMakePresets.json](../CMakePresets.json)을 사용하려면 다음 필드를
|
||||
`.harness/config.json`에 함께 지정한다. Preset 파일의 존재나 config 예시 복사만으로
|
||||
Runner가 preset 이름을 선택하지는 않는다.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -94,6 +56,9 @@ uv run --with pytest python -B -m pytest -v -rs
|
||||
}
|
||||
```
|
||||
|
||||
`configurePreset`, `buildPreset`, `testPreset`, `binaryDir`는 함께 지정해야 한다.
|
||||
이에 대응하는 backend 명령은 다음과 같다.
|
||||
|
||||
```powershell
|
||||
cmake --preset windows-msvc-ninja-debug
|
||||
cmake --build --preset windows-msvc-ninja-debug
|
||||
@@ -101,10 +66,8 @@ ctest --preset windows-msvc-ninja-debug --show-only=json-v1
|
||||
ctest --preset windows-msvc-ninja-debug --output-on-failure
|
||||
```
|
||||
|
||||
위 예시는 현재 [CMakePresets.json](../CMakePresets.json)과
|
||||
[config 예시](../.harness/config.example.json)에 맞춘다. Preset 파일이 존재하는 것만으로
|
||||
Stop이 그 preset을 선택하지는 않는다. 아래는 preset을 쓰지 않는 adapter의 명령 형태이며,
|
||||
FESA에서는 dependency 경로와 승인된 build 구성을 함께 확인한다.
|
||||
아래는 preset 없는 CMake adapter의 기본 명령 형태다. FESA에서는 승인된 MSVC x64 Debug
|
||||
구성과 dependency 경로를 함께 확인한다.
|
||||
|
||||
```powershell
|
||||
cmake -S . -B .harness/build -A x64
|
||||
@@ -113,14 +76,14 @@ ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
Runner는 configure 후 MSVC compiler metadata를 확인하고 CTest discovery가 0개이면
|
||||
실패로 처리한다. Build/test 성공이 물리·수치 correctness나 별도 필수 reference 비교의
|
||||
통과를 대신하지 않는다. Runner는 Feature 문서에서 추가 비교 명령을 추론하지 않는다.
|
||||
|
||||
## 직접 MSBuild 설정
|
||||
|
||||
다음은 재사용 가능한 Harness adapter의 예시다. FESA 제품 검증은 CMake/CTest를 사용하며
|
||||
이 예시로 solution-only MSBuild 검증을 대체 승인하지 않는다.
|
||||
|
||||
`projectType`을 `msbuild`로 설정하면 `msbuild.solution`, `configuration`, `platform`을
|
||||
지정한다. 직접 MSBuild 프로젝트에서는 `msbuild.testCommand`가 필수이며, 테스트 실행
|
||||
파일과 인수를 JSON 배열로 적는다.
|
||||
다음은 재사용 Harness adapter의 예시다. FESA 제품 검증은 CMake/CTest를 사용하며
|
||||
solution-only MSBuild를 승인된 대체 검증으로 간주하지 않는다.
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -135,46 +98,57 @@ ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
}
|
||||
```
|
||||
|
||||
`msbuild.testCommand`는 필수 argv 배열이며 실행 파일은 repository-relative 경로로
|
||||
지정한다. 선택한 solution/project를 build한 뒤 testCommand를 한 번 실행한다.
|
||||
|
||||
## 결과와 실패 진단
|
||||
|
||||
| 상황 | Runner 결과 |
|
||||
| --- | --- |
|
||||
| 구성된 build/test와 결과 검사가 모두 성공 | exit 0, 명령·cwd·exit code와 test 출력 요약 |
|
||||
| 잘못된 config, 모호한 감지, toolchain/adapter 오류, backend 실패·timeout | exit 1 |
|
||||
| 명시한 projectType의 metadata가 없음 | exit 1 |
|
||||
| Non-MSVC compiler 또는 CTest 0개/잘못된 discovery 결과 | exit 1 |
|
||||
| 자동 감지에서 CMake/MSBuild metadata가 없음 | `not configured`, exit 2 |
|
||||
| 지원하지 않는 CLI 인자 | usage error, exit 2; 검증 미시작 |
|
||||
|
||||
Backend nonzero는 실패 진단에 원래 값으로 남지만 runner의 반환값은 1이다.
|
||||
대상 부재나 미실행을 검증 통과로 표시하지 않는다. 실패 시 stage, argv, cwd와 가능한
|
||||
출력 tail을 확인한다. 실패 후 자동 재시도나 후속 단계를 실행하지 않는다.
|
||||
|
||||
- Visual Studio 도구가 없으면 C++ workload와 설치 경로를 확인한다.
|
||||
- Solution/project 선택이 모호하면 `projectType`, `msbuild.solution`을 명시한다.
|
||||
- Compiler가 MSVC가 아니면 선택된 환경과 toolchain 설정을 확인한다.
|
||||
- CTest가 0개이면 `enable_testing()`과 테스트 등록을 확인한다.
|
||||
- MSBuild test command가 없으면 실제 테스트 실행 파일과 인수를 설정한다.
|
||||
- Timeout·실패 원인은 현재 구현 owner가 수정한다. 새 근거나 변경 없이 반복 실행하지 않는다.
|
||||
|
||||
Runner 전체 deadline은 config·discovery·toolchain 탐색을 포함해 1,800초다. 각 명령에는
|
||||
남은 전체 시간과 명령별 timeout 중 짧은 값을 적용한다. 실행·검사 경계는
|
||||
[동작 과정](HARNESS_WORKFLOW.md)을 따른다.
|
||||
|
||||
## 이전 운영 방식에서 달라진 점
|
||||
|
||||
옛 `python scripts/execute.py <phase>` 호출과 `--push`,
|
||||
`--approve-danger-full-access` 인자는 usage error로 거부한다. Phase import나 상태
|
||||
migration은 제공하지 않으며 기존 `phases/` 기록을 읽거나 수정하지 않는다.
|
||||
|
||||
Legacy `tdd` config는 설정 로드 때 폐기 안내를 한 번 출력하고 무시한다.
|
||||
`testRoots`·`testPatterns`·`exclude`에 의한 대응 파일명 gate는 없다. 개인 config는
|
||||
자동 수정하지 않으므로 사용자가 필요할 때 해당 항목을 제거할 수 있다.
|
||||
|
||||
전용 phase executor, 자동 branch/commit/push·retry, PreToolUse/Stop과 자체 sandbox 승인
|
||||
환경변수는 사용하지 않는다. Git 상태를 변경하거나 commit할 권한은 runner 실행에서
|
||||
생기지 않는다. Config·preset·명령은 검토할 실행 입력이며 `shell=False`와 경로 검사는
|
||||
완전한 sandbox가 아니다. 실제 도구 권한과 외부 실행의 명시적 승인 경계는 유지한다.
|
||||
|
||||
## Harness Python 검증
|
||||
|
||||
Harness 구현을 변경하여 Python 검증이 필요할 때 다음 명령을 사용한다. 개발 중에는
|
||||
관련 검사만 선택하고 전체 검사가 필요한 최종 변경 후 한 번 실행한다.
|
||||
|
||||
```powershell
|
||||
MSBuild.exe MyProject.sln /m /p:Configuration=Debug /p:Platform=x64
|
||||
.\build\tests\Debug\MyProjectTests.exe
|
||||
uv run --with pytest python -B -m pytest -v -rs
|
||||
```
|
||||
|
||||
## TDD 확장
|
||||
|
||||
`tdd.testRoots`와 `tdd.testPatterns`로 테스트 위치와 이름을 확장한다. 패턴마다
|
||||
`{stem}`이 필요하다. `main`, 테스트, 외부 의존성, 생성 파일, build directory 같은
|
||||
기본 제외 항목은 Harness가 관리하며, `tdd.exclude`의 사용자 제외 항목은 이를
|
||||
대체하지 않고 추가한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"tdd": {
|
||||
"testRoots": ["tests", "integration-tests"],
|
||||
"testPatterns": ["{stem}_test.cpp", "test_{stem}.cpp"],
|
||||
"exclude": ["legacy/generated/**"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 실패 복구
|
||||
|
||||
Executor는 명시적 `error/blocked`를 비정상 종료에서도 보존하며 자동 재시도하지 않는다.
|
||||
인식된 sandbox helper 환경 오류는 종료 코드 0에서도 Step과 상위 phase를 `blocked`로
|
||||
기록한다. 실제 wrapper timeout으로 결과를 받지 못했을 때만 최초 포함 최대 두 번 시도한다.
|
||||
원인 미분류 nonzero와 `completed`/nonzero 불일치는 `error`다. 환경 차단은 종료 코드 2,
|
||||
일반 실패는 1이며 preflight 실패는 branch/state 변경 전에 반환한다.
|
||||
|
||||
- Visual Studio C++ workload가 없으면 Installer에서 Desktop development with C++를 설치한 뒤 다시 실행한다.
|
||||
- solution 또는 project가 여러 개라서 모호하면 `projectType`과 `msbuild.solution`을 명시한다.
|
||||
- MSVC가 아닌 컴파일러가 감지되면 MSVC Developer Command Prompt에서 실행하거나 toolchain을 MSVC로 전환한다.
|
||||
- CTest가 0개 테스트를 보고하면 `enable_testing()`과 테스트 등록을 확인한다.
|
||||
- 직접 MSBuild 구성에 test command가 없으면 `msbuild.testCommand` 배열을 추가한다.
|
||||
- timeout 또는 명령 실패 시 Stop 응답의 stage, 안전한 argv 배열, 작업 디렉터리,
|
||||
종료 코드와 출력 tail을 확인한다. 실행이 할당된 범위에서만 재현 명령을 수행하며
|
||||
문서 작업의 검증 제외 지시를 덮어쓰지 않는다. Stop은 별도의 빌드 로그 파일을 만들지 않는다.
|
||||
- 실패 분류와 재시작 결정은 Coordinator가 기록한다. Planning Agent는 명시적으로 할당된
|
||||
복구 작업에서만 현재 실패 Step의 status를 `pending`으로 바꾸고, Executor가 재시작 시
|
||||
오래된 outcome 필드와 timestamp를 정리하되 `attempt_history`는 보존한다. 실패 evidence를 먼저 보존하며
|
||||
상세 절차는 [Harness skill](../.agents/skills/harness/SKILL.md)의 Recovery and handoff를 따른다.
|
||||
실제 검사 결과와 미실행 항목을 구분해 보고한다. 문서만 갱신할 때는 이 명령을 실행하지 않는다.
|
||||
|
||||
+80
-666
@@ -1,695 +1,109 @@
|
||||
# Harness Framework 동작 과정
|
||||
# Harness 동작 과정
|
||||
|
||||
이 문서는 자연어 요구사항을 받은 뒤 Harness Framework가 계획을 만들고, 독립된
|
||||
Codex 세션에서 Step을 실행하고, MSVC로 C++ 프로젝트를 검증하는 전체 과정을
|
||||
설명한다. 설치 및 설정 예시는 [Harness 운영 가이드](HARNESS.md)를 참고한다.
|
||||
## 개발 작업과 명시적 검증
|
||||
|
||||
Feature의 9개 정규 stage와 Coordinator의 gate 전이는
|
||||
[Agent 계약](SOLVER_AGENT_DESIGN.md), 역할별 절차는
|
||||
[Harness skill](../.agents/skills/harness/SKILL.md), 문서 소유권은
|
||||
[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다. Harness는 그중 할당된
|
||||
구현 계획·Step 실행을 지원하며, solver workflow 전체를 대신하지 않는다.
|
||||
|
||||
## 1. 핵심 구조
|
||||
|
||||
Harness Framework는 다음 세 계층으로 구성된다.
|
||||
|
||||
1. **계획 계층**: 승인된 요구사항과 Coordinator dispatch를 실행 가능한 Step으로 변환한다.
|
||||
2. **실행 계층**: Step Executor가 Step마다 독립 Codex 세션을 실행하고 상태와 Git
|
||||
커밋을 관리한다.
|
||||
3. **검증 계층**: PreToolUse 훅이 편집 전 정책을 검사하고, Stop 훅이 종료 전 MSVC
|
||||
빌드와 테스트를 실행한다. 유효한 문서 전용 편집 기록이면 조건부로 생략한다.
|
||||
|
||||
전체 흐름은 다음과 같다.
|
||||
메인 assistant가 관련 계약과 변경 범위를 확인하고 필요한 전문 작업만 위임한다.
|
||||
현재 역할과 사용자 결정 경계는 [Agent 운영](SOLVER_AGENT_DESIGN.md),
|
||||
문서 관리는 [Feature 문서 관리](FEATURE_DOCUMENTATION.md),
|
||||
운영 결정은 [ADR-028](ADR.md#adr-028)을 따른다.
|
||||
|
||||
```text
|
||||
사용자 요구사항
|
||||
↓
|
||||
Feature의 선행 계약·gate 확인
|
||||
↓
|
||||
Coordinator의 bounded Planning dispatch
|
||||
↓
|
||||
Planning Agent의 자기완결적 Step 작성
|
||||
↓
|
||||
phases/index.json, task index, stepN.md 생성
|
||||
↓
|
||||
실행까지 할당된 경우 Step Executor 시작
|
||||
↓
|
||||
각 Step을 독립 Codex 세션에서 실행
|
||||
├─ 도구 호출 전: PreToolUse 정책 검사
|
||||
└─ 응답 종료 전: Stop 검증 또는 문서 전용 조건부 생략
|
||||
↓
|
||||
성공: 커밋 후 다음 Step
|
||||
transport 실패: 최초 포함 최대 2회 시도
|
||||
구현 실패·차단: Coordinator로 반환
|
||||
관련 계약·현재 evidence 확인 → 변경 → 관련 test/build → 결과 확인
|
||||
│
|
||||
└─ 기능 완료 시 전체 build/test·필수 reference 비교
|
||||
```
|
||||
|
||||
자연어 요구사항이나 계획 요청만으로 Executor가 자동 시작되지는 않는다. 승인된 Feature와
|
||||
dispatch 안의 일반 계획 파일 작성·할당된 실행에 반복 승인 gate를 추가하지 않는다.
|
||||
권한 상승, 원격·파괴 작업, licensed reference solver 실행은 별도 명시적 승인이 필요하다.
|
||||
동작 변경에는 해당 의미를 확인하는 테스트를 추가·수정한다. 버그는 가능한 경우 실패를
|
||||
재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor에는 형식적인
|
||||
새 테스트를 요구하지 않는다. 계획·소스·테스트·evidence는 할당된 범위 안에서 변경한다.
|
||||
|
||||
## 2. 요구사항 탐색과 구체화
|
||||
개발 중 focused check는 실제 configured backend 명령으로 수행한다.
|
||||
`python scripts/execute.py`는 구성된 전체 build/test를 한 번 실행한다. 사용자가 요청하거나
|
||||
넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되, 이후 변경·실패가 없으면 반복하지
|
||||
않는다. 계획 작성만 요청받은 경우에는 실행하지 않는다.
|
||||
|
||||
예를 들어 사용자가 다음 요구사항을 전달했다고 가정한다.
|
||||
## 변경 종류별 검증
|
||||
|
||||
아래 Calculator 예시는 Harness Step 구조를 설명하기 위한 것으로 FESA 제품 요구사항이나
|
||||
새 기능 구현 지시가 아니다.
|
||||
| 작업 | 수행할 작업과 확인 |
|
||||
| --- | --- |
|
||||
| 문서 수정 | 관련 문서·소스·링크·diff 정적 확인. Solver build, 새 테스트, 별도 specialist 호출을 의무화하지 않음 |
|
||||
| 일반 구현 버그 | 메인 또는 기존 구현 owner가 가능한 실패 재현 → 최소 수정 → 관련 검사. 변경 영향·기능 완료 조건에 따라 전체 검증 |
|
||||
| 새 수치 기능 | 필요한 요구·정식화·I/O 정의, 독립 numerical review → 구현·관련 테스트 → 전체 build/test와 필수 analytical/invariant·물리·reference 검증 |
|
||||
|
||||
> CMake 기반 C++20 라이브러리에 `divide()` 함수를 추가하고, 0으로 나누면 예외를
|
||||
> 발생시키며 GoogleTest 테스트를 작성한다.
|
||||
수식·요소·재료·적분·상태 갱신 변경에는 독립 numerical review를 수행한다. 물리/수치
|
||||
검증은 각 계약에 따라 수행하며 역할이나 보고서 수를 줄였다는 이유로 생략하지 않는다.
|
||||
Release-readiness 감사는 명시적으로 요청할 때만 수행한다.
|
||||
|
||||
계획을 작성하기 전에 다음 자료를 확인한다.
|
||||
## Runner의 실행 순서
|
||||
|
||||
- `AGENTS.md`
|
||||
- `docs/PRD.md`
|
||||
- `docs/ARCHITECTURE.md`
|
||||
- `docs/ADR.md`
|
||||
- Coordinator dispatch와 `docs/<feature-id>/`의 승인된 선행 계약
|
||||
- 해당 Feature의 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`
|
||||
- 관련 제품 코드와 테스트
|
||||
- `.harness/config.json`이 있으면 그 설정, 없으면 preset·metadata·프로젝트 지침과 감지 기본값
|
||||
[Runner](../scripts/execute.py)는 자신의 경로에서 저장소 root를 정한 뒤 아래를 수행한다.
|
||||
|
||||
이 탐색을 통해 다음 조건을 구체화한다.
|
||||
1. [Config](../scripts/msvc_harness/config.py)를 읽고 타입·허용 field·경로·preset 조합을 확인한다.
|
||||
2. [Discovery](../scripts/msvc_harness/discovery.py)가 명시된 projectType 또는 CMake/MSBuild metadata로 backend를 선택한다.
|
||||
3. [Toolchain](../scripts/msvc_harness/toolchain.py)이 필요한 Visual Studio/MSBuild·CMake/CTest 도구를 찾는다.
|
||||
4. 선택된 adapter가 argv·cwd·stage·timeout·결과 검사를 포함한 검증 계획을 만든다.
|
||||
5. [Process](../scripts/msvc_harness/process.py)가 명령을 순서대로 실행하고 각 결과를 검사한다.
|
||||
6. 성공 시 실행한 명령·cwd·exit code와 test 출력 요약을 반환한다. 실패 시 원인 진단과 nonzero를 반환한다.
|
||||
|
||||
- 사용하는 MSVC toolset과 C++ 표준
|
||||
- CMake 프로젝트인지 Visual Studio solution/project인지
|
||||
- 테스트 프레임워크와 테스트 실행 방법
|
||||
- public header와 implementation의 의존성 방향
|
||||
- 수정할 모듈과 범위 밖 항목
|
||||
- 실행 가능한 Acceptance Criteria 명령
|
||||
여기서 검증 계획은 backend 명령 목록이다. Feature phase/index/step 파일이나 LLM
|
||||
프롬프트가 아니다. Runner는 Git branch·HEAD·index를 관리하거나 Feature 문서를
|
||||
해석해 추가 명령을 생성하지 않는다.
|
||||
|
||||
필수 계약이 없으면 Coordinator를 통해 해당 owner로 반환한다. 예외 타입, 수치 타입,
|
||||
public API·ABI처럼 승인된 의미를 바꾸는 선택은 critical decision 기준에 따라 사용자에게
|
||||
올린다. 이미 승인된 계약 안의 파일 배치나 테스트 분해는 담당자가 결정한다.
|
||||
### Backend별 실행
|
||||
|
||||
## 3. 요구사항을 Step으로 분해
|
||||
| Backend | 실행과 결과 검사 |
|
||||
| --- | --- |
|
||||
| CMake/CTest | configure → compiler metadata의 MSVC 확인 → build → CTest JSON discovery/0개 거부 → test |
|
||||
| MSBuild | 선택된 solution/project build → 명시된 repository-relative testCommand 실행 |
|
||||
|
||||
사용자가 구현 계획 작성을 요청하면 요구사항을 작은 Step으로 나눈다. Step 설계
|
||||
규칙은 [Harness Workflow](../.agents/skills/harness/SKILL.md)에 정의되어 있다.
|
||||
FESA는 CMake/MSVC x64/Debug와 CTest를 제품 검증 기준으로 사용한다.
|
||||
MSBuild adapter가 있다는 사실이 solution-only 검증을 대체 승인하지 않는다.
|
||||
Preset 선택과 정확한 명령·설정 예시는 [Harness 운영 가이드](HARNESS.md)를 따른다.
|
||||
|
||||
각 Step은 다음 조건을 만족해야 한다.
|
||||
## 실행 경계와 실패 처리
|
||||
|
||||
- 하나의 모듈 또는 명확한 한 가지 책임만 다룬다.
|
||||
- 다른 대화 내용을 참조하지 않아도 실행할 수 있도록 자기완결적으로 작성한다.
|
||||
- 먼저 읽을 문서와 이전 Step의 관련 파일을 명시한다.
|
||||
- Feature 관리 문서와 승인된 선행 계약의 정확한 경로·revision을 명시한다.
|
||||
- 클래스와 함수 시그니처 수준으로 작업 범위를 설명한다.
|
||||
- 수정할 소스·테스트·보고서 파일과 수정하지 않을 upstream 파일을 명시한다.
|
||||
- 실제 실행 가능한 빌드·테스트 명령을 Acceptance Criteria로 사용한다.
|
||||
- 성공, 오류, 사용자 개입 필요 상태의 판정 기준을 적는다.
|
||||
- 범위 밖 기능과 기존 테스트 회귀를 명시적으로 금지한다.
|
||||
Config의 경로와 명령 cwd는 repository 범위 안인지 확인한다. MSBuild testCommand의
|
||||
실행 파일도 repository-relative 경로여야 한다. Subprocess는 argv 배열과 `shell=False`로
|
||||
실행하며 stdout/stderr를 수집한다. Config·preset·실행 파일 자체의 side effect까지 격리하는
|
||||
sandbox는 아니므로 실제 실행 입력과 도구 권한을 확인한다.
|
||||
|
||||
예시 Step은 다음과 같은 내용을 포함할 수 있다.
|
||||
전체 deadline은 시작부터 1,800초다. 각 명령의 timeout은 남은 전체 시간과 명령별 제한 중
|
||||
짧은 값이며, 실행 전 남은 시간이 없으면 실패한다. Backend nonzero, timeout, MSVC 확인
|
||||
실패나 CTest 0개 등 결과 검사 실패가 발생하면 후속 단계를 실행하지 않는다.
|
||||
|
||||
```text
|
||||
Step 0: division-api
|
||||
명령 실패 진단에는 stage·argv·cwd, 가능한 원래 exit code와 출력 tail이 포함된다.
|
||||
현재 구현 owner가 원인을 확인하고 필요한 수정 또는 환경 조치 후 관련 검사를 수행한다.
|
||||
새 근거나 변경 없이 같은 명령·agent 호출을 반복하지 않으며 자동 transport retry나
|
||||
별도 correction 예산은 없다.
|
||||
|
||||
읽어야 할 파일
|
||||
- AGENTS.md
|
||||
- include/calculator.hpp
|
||||
- src/calculator.cpp
|
||||
- tests/calculator_test.cpp
|
||||
Runner는 성공 시 exit 0, config/toolchain/backend 등 실행 실패 시 exit 1을 반환한다.
|
||||
자동 감지에서 metadata가 없거나 CLI 인자가 잘못되면 exit 2다. 명시된 projectType에 필요한
|
||||
metadata가 없는 경우는 exit 1이다. Backend 원래 nonzero와 runner exit를 구분한다.
|
||||
전체 목록은 [결과와 실패 진단](HARNESS.md#결과와-실패-진단)을 참조한다.
|
||||
|
||||
작업
|
||||
- divide(double lhs, double rhs)의 실패 테스트를 먼저 추가한다.
|
||||
- rhs가 0이면 std::invalid_argument가 발생하도록 최소 구현한다.
|
||||
## 수치 evidence와 완료 확인
|
||||
|
||||
Acceptance Criteria
|
||||
- CMake/MSBuild 빌드가 성공한다.
|
||||
- 전체 테스트가 성공한다.
|
||||
- 새로운 컴파일러 경고가 없다.
|
||||
```
|
||||
Harness 성공은 build/test 실행 결과다. 필요한 reference comparison을 자동 탐색하거나
|
||||
솔버 correctness 전체를 판정하지 않는다. 메인·구현 담당자는 계약이 요구하는 다음
|
||||
검증을 별도로 확인한다.
|
||||
|
||||
### TDD와 Step 경계
|
||||
- Unit·coordinate·부호·DOF/component·source identity와 결과 위치의 일치
|
||||
- Analytical solution, invariant·equilibrium·energy·convergence 등 적용되는 검증
|
||||
- Missing·extra·duplicate·nonfinite required row를 tolerance 전에 거부하는 비교
|
||||
- [TOLERANCE](TOLERANCE.md)와 승인된 Feature의 비교량·판정 구분
|
||||
- Trial/committed state·실패 보존·결정론과 필요한 독립 물리 판단
|
||||
|
||||
프로젝트 규칙은 실패하는 테스트를 먼저 요구하지만 Stop 훅은 Codex가 Step을 종료할
|
||||
때 전체 테스트 성공을 요구한다. 따라서 다음처럼 실패 상태를 Step 사이에 남겨둘 수
|
||||
없다.
|
||||
Reference artifact와 tolerance를 통과에 맞춰 수정하지 않는다. 명령·exit code와 결정적
|
||||
판정값은 필요한 보고서에 한 번 기록하고 원시 로그는 원본 경로로 연결한다. 실패·미실행·
|
||||
stale evidence와 미해결 항목을 명확히 남기며 검사를 생략한 사실을 통과로 보고하지 않는다.
|
||||
|
||||
```text
|
||||
Step 0: 실패하는 테스트만 추가하고 종료
|
||||
Step 1: 제품 코드를 구현해 테스트 통과
|
||||
```
|
||||
## 과거 phase·hook·Git 처리
|
||||
|
||||
실제 red-green 순서는 하나의 Codex 실행 안에서 완료되어야 한다.
|
||||
현재 runner는 내부 Codex 세션, phase 상태기계·result payload, `owned_paths`·
|
||||
`attempt_history`, 자동 branch/commit/push, PreToolUse/Stop을 사용하지 않는다.
|
||||
`coordination.md`와 기존 phase·hook 기록은 이력으로 보존하고 새 실행 입력으로 만들지 않는다.
|
||||
|
||||
```text
|
||||
테스트 작성
|
||||
→ 테스트 실패 확인
|
||||
→ 최소 제품 코드 구현
|
||||
→ 테스트 성공 확인
|
||||
→ Step 종료
|
||||
```
|
||||
|
||||
즉, 테스트가 구현보다 먼저 작성되는 순서는 지키되 각 Step은 최종적으로 green
|
||||
상태여야 한다.
|
||||
|
||||
## 4. 할당된 계획 산출물
|
||||
|
||||
Planning Agent는 Coordinator가 할당한 다음 파일을 생성한다. 기존 산출물을 재개할 때는
|
||||
덮어쓰지 않고 승인된 변경 범위만 갱신한다. Step 번호는 0부터 연속으로 둔다.
|
||||
|
||||
```text
|
||||
phases/
|
||||
├── index.json
|
||||
└── add-division/
|
||||
├── index.json
|
||||
├── step0.md
|
||||
├── step1.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 4.1 Top-level index
|
||||
|
||||
`phases/index.json`은 여러 task의 상태를 관리한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"phases": [
|
||||
{
|
||||
"dir": "add-division",
|
||||
"status": "pending"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Task index
|
||||
|
||||
`phases/add-division/index.json`은 task 내부 Step의 상태를 관리한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"project": "Calculator",
|
||||
"phase": "add-division",
|
||||
"steps": [
|
||||
{
|
||||
"step": 0,
|
||||
"name": "division-api",
|
||||
"status": "pending",
|
||||
"owned_paths": ["include/calculator.hpp", "src/calculator.cpp", "tests/calculator_test.cpp"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
상태별 기록은 다음과 같이 나뉜다.
|
||||
|
||||
`owned_paths`는 Planning이 작성하는 정확한 저장소 상대 파일 목록이다. Step 본문의 소유
|
||||
파일과 일치해야 하며 source/header/test/build/report를 필요한 만큼 명시한다. 디렉터리,
|
||||
glob, 절대 경로, 경로 이탈, Git 내부와 `phases/` 제어 경로는 허용하지 않는다. 연결된
|
||||
파일·디렉터리 경로도 지원하지 않는다. `[]`는 구현 파일 변경 없음이며 누락과 다르다.
|
||||
기존 완료 Step은 필드 없이 읽을 수 있지만 모든 pending Step은 실행 전에 목록이 필요하다.
|
||||
기존 phase를 일괄 변환하거나 Markdown에서 파일 권한을 자동 추출하지 않는다.
|
||||
|
||||
| 상태 | Codex가 기록 | Executor가 기록 |
|
||||
|---|---|---|
|
||||
| `completed` | `summary` | `completed_at` |
|
||||
| `error` | `error_message` | `failed_at` |
|
||||
| `blocked` | `blocked_reason` | `blocked_at` |
|
||||
|
||||
Executor는 task의 `created_at`과 Step의 `started_at`, `attempt_history`도 기록한다.
|
||||
History에는 단조 증가하는 `attempt`, `recorded_at`, `exit_code`(프로세스 미기동은 null),
|
||||
`reported_status`, `reported_reason`, 로컬 `classification`·판정 `reason`과 `diagnostic`을 보존한다.
|
||||
진단은 stderr 우선, 없으면 stdout의 마지막 4,000자이며 raw output 전체의 대체가 아니다.
|
||||
Implementation은 `owned_paths`·history·timestamp를 수정할 수 없다. `summary`는 다음
|
||||
독립 Codex 세션이 이전 Step의 핵심 산출물과 결정을 이해할 수 있도록 한 줄로
|
||||
작성한다.
|
||||
|
||||
### 4.3 Step 파일
|
||||
|
||||
각 `stepN.md`에는 다음 내용이 들어간다.
|
||||
|
||||
- 읽어야 할 파일
|
||||
- 작업 범위와 인터페이스
|
||||
- 핵심 동작 및 불변 조건
|
||||
- Acceptance Criteria 명령
|
||||
- 아키텍처·ADR·CRITICAL 규칙 확인 절차
|
||||
- 성공, 오류, 차단 상태 기록 방법
|
||||
- 범위 밖 변경 금지사항
|
||||
|
||||
Step은 독립 Codex 실행의 전체 작업 지시서이므로 이전 대화만 참조하는 표현을 넣지
|
||||
않는다.
|
||||
|
||||
## 5. Step Executor 시작
|
||||
|
||||
계획 파일이 준비되고 실행까지 할당된 경우 다음 명령으로 실행한다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py add-division
|
||||
```
|
||||
|
||||
완료된 브랜치의 원격 push를 사용자가 명시적으로 승인한 경우에만 `--push`를 추가한다.
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py add-division --push
|
||||
```
|
||||
|
||||
[Step Executor](../scripts/execute.py)는 시작할 때 다음 작업을 수행한다.
|
||||
|
||||
1. phase 경로와 top-level/phase index schema, Step 번호·이름·상태를 검사한다.
|
||||
2. 현재 첫 미완료 Step이 `error` 또는 `blocked`이면 복구 결정 전까지 중단한다.
|
||||
3. 모든 pending Step의 `owned_paths`, Implementation Agent profile, Git top-level,
|
||||
sandbox 승인 조건과 clean 상태를 검사한다.
|
||||
기본 모드는 선택된 phase 제어 파일 allowlist 밖의 변경을 허용하지 않는다.
|
||||
4. `feat-{phase-name}` 브랜치를 생성하거나 checkout한다.
|
||||
5. `AGENTS.md`와 `docs/*.md`를 guardrail로 읽는다.
|
||||
6. task/Step timestamp와 재개 상태를 정리하고 첫 번째 `pending` Step부터 순차 실행한다.
|
||||
|
||||
`AGENTS.md`와 모든 `docs/*.md` 내용은 각 Codex 프롬프트에 직접 삽입된다. 따라서
|
||||
이 문서들도 실행 입력에 포함된다. 역할·승인·상태 전이에서는 Agent 계약과 Harness skill의
|
||||
권한 경계를 따르며, 설치 예시를 Feature의 요구사항으로 사용하지 않는다. Feature 관리
|
||||
문서는 자동으로 로드되지 않으므로 dispatch와 Step의 필수 입력 경로에 명시해야 한다.
|
||||
|
||||
## 6. Step마다 독립 Codex 세션 실행
|
||||
|
||||
Executor는 각 Step을 다음 형태의 독립 프로세스로 실행한다.
|
||||
|
||||
```text
|
||||
codex exec
|
||||
--disable unified_exec
|
||||
--json
|
||||
--model <implementation-agent profile model>
|
||||
--config model_reasoning_effort="<profile effort>"
|
||||
--sandbox <workspace-write|danger-full-access>
|
||||
--dangerously-bypass-hook-trust
|
||||
--cd <repository-root>
|
||||
-
|
||||
```
|
||||
|
||||
기본값은 `workspace-write`다. `FEM_HARNESS_CODEX_SANDBOX` 환경 변수는
|
||||
`workspace-write` 또는 `danger-full-access`만 허용한다. Windows native sandbox에서
|
||||
MSVC compiler-id의 `cl.exe` 정지가 재현되고 동일 명령이 sandbox 밖에서 통과하는
|
||||
환경에서는, 해당 실행 직전 사용자 승인을 받은 clean linked Git worktree 실행에 한해서
|
||||
`danger-full-access` fallback을 사용할 수 있다. Executor의
|
||||
`--approve-danger-full-access` flag도 필요하며 환경변수만으로 승인되지 않는다.
|
||||
이 override는 등록된 hook을 비활성화하지 않는다.
|
||||
|
||||
Codex에 전달하는 프롬프트는 다음 내용의 조합이다.
|
||||
|
||||
```text
|
||||
Implementation Agent profile의 역할·수정 경계
|
||||
+ AGENTS.md와 docs 문서
|
||||
+ 이전에 완료된 Step의 summary
|
||||
+ 이전 시도의 오류(재시도인 경우)
|
||||
+ Executor 공통 작업 규칙
|
||||
+ 현재 stepN.md
|
||||
```
|
||||
|
||||
이전 Step의 전체 대화나 Codex 세션은 전달하지 않는다. task index에 기록한
|
||||
`summary`만 다음 Step에 누적한다.
|
||||
|
||||
Codex 실행 결과의 exit code, stdout, stderr는 다음 파일에 저장한다.
|
||||
|
||||
```text
|
||||
phases/{task-name}/step{N}-output.json
|
||||
```
|
||||
|
||||
## 7. 도구 호출 전 PreToolUse 검사
|
||||
|
||||
[`.codex/hooks.json`](../.codex/hooks.json)은 shell 및 파일 편집 도구에
|
||||
[PreToolUse 훅](../scripts/hooks/pre_tool_use.py)을 등록한다. Codex가 실제 명령이나
|
||||
편집을 수행하기 전에 이 훅이 요청을 검사한다.
|
||||
|
||||
### 7.1 위험 명령 차단
|
||||
|
||||
다음 유형의 명령은 요구사항과 관계없이 차단한다.
|
||||
|
||||
- `git reset --hard`
|
||||
- `git push --force` 또는 `--force-with-lease`
|
||||
- `rm -rf`
|
||||
- `Remove-Item -Recurse -Force`
|
||||
- `rmdir /s /q`
|
||||
- `DROP TABLE`
|
||||
|
||||
위험 패턴이 발견되면 훅은 차단 이유를 stderr로 출력하고 종료 코드 2를 반환한다.
|
||||
그러면 해당 도구 호출은 실행되지 않는다.
|
||||
|
||||
### 7.2 C++ TDD 검사
|
||||
|
||||
`apply_patch`, `Edit`, `MultiEdit`, `Write`로 다음 C/C++ 확장자의 파일을 편집하려
|
||||
하면 [TDD 정책](../scripts/msvc_harness/tdd_policy.py)을 검사한다.
|
||||
|
||||
```text
|
||||
.c .cc .cpp .cxx .h .hpp .hxx
|
||||
```
|
||||
|
||||
일반 제품 코드를 수정하려면 대응되는 테스트 파일이 먼저 존재해야 한다. 예를 들어
|
||||
`src/calculator.cpp`의 기본 대응 테스트 이름은 다음과 같다.
|
||||
|
||||
```text
|
||||
calculator_test.cpp
|
||||
calculator_tests.cpp
|
||||
test_calculator.cpp
|
||||
calculator.test.cpp
|
||||
```
|
||||
|
||||
테스트는 다음 위치에서 검색한다.
|
||||
|
||||
- `.harness/config.json`의 `tdd.testRoots`
|
||||
- 제품 파일과 같은 디렉터리 아래 `tests/`
|
||||
- 제품 파일과 같은 디렉터리 아래 `test/`
|
||||
|
||||
다음 파일과 디렉터리는 대응 테스트 존재 검사가 면제된다.
|
||||
|
||||
- 테스트 파일 자체
|
||||
- `main.cpp`
|
||||
- `.harness/build/**`, `build/**`, `out/**`
|
||||
- `cmake-build-*/**`
|
||||
- `third_party/**`, `external/**`, `vendor/**`
|
||||
- `generated/**`
|
||||
- `tdd.exclude`에 추가한 경로
|
||||
|
||||
`tdd.exclude`는 기본 제외 항목을 대체하지 않고 추가한다.
|
||||
|
||||
### 7.3 TDD 검사가 보장하는 범위
|
||||
|
||||
현재 TDD 훅이 직접 보장하는 것은 대응되는 이름의 테스트 파일이 존재한다는
|
||||
사실이다. 다음 항목까지 증명하지는 않는다.
|
||||
|
||||
- 테스트가 이번 요구사항을 실제로 검증하는가
|
||||
- 구현 전에 테스트가 실제로 실패했는가
|
||||
- 테스트의 assertion과 경계 조건이 충분한가
|
||||
- 기존 테스트 파일을 이번 변경과 함께 수정했는가
|
||||
|
||||
또한 shell 명령의 리다이렉션 등으로 C++ 파일을 쓰는 경우 shell 위험 패턴 검사는
|
||||
적용되지만 경로 기반 TDD 검사는 적용되지 않는다. 따라서 이 훅은 완전한 TDD
|
||||
증명기가 아니라 테스트 우선 편집을 유도하는 guardrail이다.
|
||||
|
||||
PreToolUse는 허용된 편집 도구의 대상 경로를 `.harness/hook-state/`에 기록한다.
|
||||
이 ignored 기록은 Stop의 문서 전용 판정 입력일 뿐 RED나 실제 편집 성공의 증거가 아니다.
|
||||
|
||||
## 8. Codex 종료 전 Stop 검증
|
||||
|
||||
Codex가 Step 작업을 끝내고 응답을 종료하려 하면
|
||||
[Stop 훅](../scripts/hooks/stop_validation.py)이 실행된다. 유효한 동일 session/turn 기록에서
|
||||
편집 대상이 모두 저장소 내부 `.md`이면 build/test를 생략한다. 기록 누락·손상 또는 비문서
|
||||
편집이면 정상 검증 경로에서 발견된 C/C++ 프로젝트 전체를 빌드하고 테스트한다.
|
||||
|
||||
Shell 쓰기는 완전히 추적되지 않으며, 편집 기록 없는 읽기 전용 요청도 자동 생략을
|
||||
보장하지 않는다. 사용자가 문서 작업의 실행을 제외하면 수동 Hook·build/test를 실행하지
|
||||
않고 정적 검토 범위와 미실행 항목을 보고한다. Hook state를 조작해 생략을 만들지 않는다.
|
||||
|
||||
### 8.1 저장소 루트와 재진입 방지
|
||||
|
||||
Stop 훅은 `git rev-parse --show-toplevel`로 프로젝트 루트를 결정한다. Git 저장소를
|
||||
찾을 수 없으면 현재 디렉터리를 사용한다.
|
||||
|
||||
빌드나 테스트의 자식 프로세스에는 `CODEX_STOP_VALIDATION_ACTIVE=1`을 전달한다.
|
||||
같은 훅이 자식 프로세스에서 다시 진입하면 즉시 성공 처리하여 검증 재귀를 막는다.
|
||||
|
||||
### 8.2 설정 로드
|
||||
|
||||
[설정 로더](../scripts/msvc_harness/config.py)는 `.harness/config.json`을 읽는다.
|
||||
파일이 없으면 다음 기본값을 사용한다.
|
||||
|
||||
- `version`: 1
|
||||
- `projectType`: `auto`
|
||||
- CMake source: 저장소 루트
|
||||
- preset 미사용 시 binary directory: `.harness/build`
|
||||
- configuration: `Debug`
|
||||
- platform: `x64`
|
||||
- 테스트 루트: `tests`, `test`
|
||||
- 기본 테스트 이름 패턴 네 개
|
||||
|
||||
설정은 다음 조건을 엄격하게 검사한다.
|
||||
|
||||
- 알 수 없는 필드를 거부한다.
|
||||
- `version`은 숫자 1만 허용한다.
|
||||
- `projectType`은 `auto`, `cmake`, `msbuild`만 허용한다.
|
||||
- 저장소 상대 경로만 허용한다.
|
||||
- 저장소 밖으로 해석되는 경로를 거부한다.
|
||||
- CMake preset을 사용하면 `configurePreset`, `buildPreset`, `testPreset`,
|
||||
`binaryDir`를 모두 요구한다.
|
||||
- 모든 `tdd.testPatterns`에 `{stem}`을 요구한다.
|
||||
|
||||
### 8.3 프로젝트 자동 감지
|
||||
|
||||
[프로젝트 탐색기](../scripts/msvc_harness/discovery.py)는 다음 순서로 프로젝트를
|
||||
선택한다.
|
||||
|
||||
1. `projectType: cmake` 또는 `projectType: msbuild` 명시 설정
|
||||
2. 루트의 `CMakePresets.json`
|
||||
3. 루트의 `CMakeUserPresets.json`
|
||||
4. 루트의 `CMakeLists.txt`
|
||||
5. 루트의 단일 `.sln`
|
||||
6. 루트의 단일 `.vcxproj`
|
||||
|
||||
자동 감지 결과는 다음처럼 처리한다.
|
||||
|
||||
| 저장소 상태 | 결과 |
|
||||
|---|---|
|
||||
| CMake metadata가 있음 | CMake 프로젝트 선택 |
|
||||
| 하나의 `.sln` 또는 `.vcxproj`가 있음 | MSBuild 프로젝트 선택 |
|
||||
| 여러 solution/project가 있음 | 설정으로 하나를 지정하라는 오류 |
|
||||
| C/C++ 파일과 build metadata가 모두 없음 | 검증할 프로젝트가 없으므로 통과 |
|
||||
| C/C++ 파일은 있지만 build metadata가 없음 | orphan C++ 프로젝트 오류 |
|
||||
|
||||
### 8.4 MSVC 도구 탐색
|
||||
|
||||
[도구 탐색기](../scripts/msvc_harness/toolchain.py)는 `vswhere.exe`로 다음을
|
||||
확인한다.
|
||||
|
||||
- Visual Studio 설치 경로
|
||||
- Desktop development with C++ workload
|
||||
- `MSBuild.exe`
|
||||
|
||||
CMake 프로젝트에서는 다음 우선순위로 CMake와 CTest를 선택한다.
|
||||
|
||||
1. PATH에서 발견한 독립 `cmake.exe`와 `ctest.exe`
|
||||
2. Visual Studio에 번들된 CMake와 CTest
|
||||
|
||||
따라서 새로 설치한 CMake의 `bin` 디렉터리가 PATH에 반영되어 있으면 독립 CMake를
|
||||
우선 사용한다.
|
||||
|
||||
## 9. 빌드 시스템별 검증 계획
|
||||
|
||||
### 9.1 CMake preset 미사용
|
||||
|
||||
[CMake adapter](../scripts/msvc_harness/adapters/cmake.py)는 다음 검증 계획을 만든다.
|
||||
|
||||
```powershell
|
||||
cmake -S <source> -B .harness/build -A x64
|
||||
cmake --build .harness/build --config Debug
|
||||
ctest --test-dir .harness/build -C Debug --show-only=json-v1
|
||||
ctest --test-dir .harness/build -C Debug --output-on-failure
|
||||
```
|
||||
|
||||
명령 성공 외에 다음 결과도 검사한다.
|
||||
|
||||
- 생성된 CMake compiler metadata의 `CMAKE_CXX_COMPILER_ID`가 `MSVC`인가
|
||||
- CTest JSON에 한 개 이상의 테스트가 있는가
|
||||
|
||||
따라서 빌드가 성공해도 MinGW 등 다른 컴파일러를 사용했거나 CTest가 테스트를 한
|
||||
개도 발견하지 못하면 실패한다.
|
||||
|
||||
### 9.2 CMake preset 사용
|
||||
|
||||
`.harness/config.json`에 preset을 완전히 지정하면 다음 형태로 실행한다.
|
||||
|
||||
```powershell
|
||||
cmake --preset <configurePreset>
|
||||
cmake --build --preset <buildPreset>
|
||||
ctest --preset <testPreset> --show-only=json-v1
|
||||
ctest --preset <testPreset> --output-on-failure
|
||||
```
|
||||
|
||||
이 경우 모든 명령은 `cmake.sourceDir`에서 실행하고 compiler metadata 검사는 설정한
|
||||
`binaryDir`에서 수행한다.
|
||||
|
||||
### 9.3 직접 MSBuild
|
||||
|
||||
[MSBuild adapter](../scripts/msvc_harness/adapters/msbuild.py)는 다음 순서로 실행한다.
|
||||
|
||||
```powershell
|
||||
MSBuild.exe <solution-or-vcxproj> /m /nologo `
|
||||
/p:Configuration=<configuration> `
|
||||
/p:Platform=<platform>
|
||||
|
||||
<msbuild.testCommand>
|
||||
```
|
||||
|
||||
직접 MSBuild 프로젝트는 표준 테스트 탐색 명령이 없으므로
|
||||
`.harness/config.json`의 `msbuild.testCommand`가 반드시 필요하다. 이 값이 없으면
|
||||
Stop 검증이 실패한다.
|
||||
|
||||
## 10. 명령 실행 안전성과 제한시간
|
||||
|
||||
[검증 실행기](../scripts/msvc_harness/process.py)는 다음 안전 규칙을 적용한다.
|
||||
|
||||
- 명령을 shell 문자열이 아닌 argv 배열로 실행한다.
|
||||
- `shell=False`를 사용한다.
|
||||
- 각 명령의 working directory가 저장소 내부인지 검사한다.
|
||||
- 명령별 제한시간과 Stop 전체 제한시간 중 더 짧은 값을 적용한다.
|
||||
- 종료 코드가 0이 아니면 즉시 해당 stage를 실패 처리한다.
|
||||
|
||||
Stop 훅의 shared 전체 제한시간은 저장소 탐색, toolchain 탐색, configure, build,
|
||||
test discovery, test를 모두 포함해 7,200초다. 각 command는 자체 제한시간과 남은
|
||||
shared deadline 중 더 짧은 값을 사용한다. `.codex/hooks.json`의 Stop command timeout은
|
||||
진단 여유를 포함해 7,500초다.
|
||||
|
||||
실패 메시지에는 다음 진단 정보를 포함한다.
|
||||
|
||||
- 실패 stage
|
||||
- 안전하게 표현한 argv 배열
|
||||
- working directory
|
||||
- 종료 코드
|
||||
- stdout과 stderr의 마지막 8,000자
|
||||
|
||||
Harness는 별도 빌드 로그 파일을 생성하지 않는다.
|
||||
|
||||
## 11. 성공, 실패, 차단 처리
|
||||
|
||||
### 11.1 Stop 검증 성공
|
||||
|
||||
빌드와 테스트가 모두 성공하거나 문서 전용 생략 조건을 충족하면 Stop 훅은 출력 없이
|
||||
종료한다. 생략은 build/test 통과 evidence가 아니다. Codex가 정상 종료하면 Executor는
|
||||
branch/HEAD, 제어 파일과 현재 Step 외 상태의 변경 여부를 검사하고 task index를 읽는다.
|
||||
Codex 종료 코드가 0이 아니면 `completed` 기록만으로 성공 처리하지 않는다.
|
||||
|
||||
Codex가 Step을 다음처럼 기록한 경우:
|
||||
|
||||
```json
|
||||
{
|
||||
"step": 0,
|
||||
"name": "division-api",
|
||||
"status": "completed",
|
||||
"owned_paths": ["include/calculator.hpp", "src/calculator.cpp", "tests/calculator_test.cpp"],
|
||||
"summary": "divide API와 0 나누기 테스트를 추가함"
|
||||
}
|
||||
```
|
||||
|
||||
Executor는 `completed_at`을 기록하고 변경사항을 커밋한 뒤 다음 `pending` Step을
|
||||
실행한다.
|
||||
|
||||
### 11.2 Stop 검증 실패
|
||||
|
||||
Stop 훅은 Codex hook protocol에 따라 다음 형태의 응답을 출력한다.
|
||||
|
||||
```json
|
||||
{
|
||||
"decision": "block",
|
||||
"reason": "build failed ..."
|
||||
}
|
||||
```
|
||||
|
||||
훅 자체의 종료 코드는 0이지만 `decision: block`이 종료 차단 이유를 전달한다.
|
||||
수정은 할당된 역할·Step·retry budget 안에서만 수행하며, Hook 실패가 상위 계약 변경이나
|
||||
무제한 반복 권한을 주지 않는다.
|
||||
|
||||
### 11.3 Executor 재시도
|
||||
|
||||
Executor는 branch/HEAD·제어 파일·결과 형식과 변경 경로의 소유권을 먼저 검증한 뒤
|
||||
Step 보고와 프로세스 종료 코드를 함께 판정한다.
|
||||
|
||||
| 결과 | 처리 | 자동 재시도 |
|
||||
| --- | --- | --- |
|
||||
| 인식된 sandbox helper 환경 오류(종료 코드 무관), CLI 미설치 | Step과 상위 phase `blocked`, 종료 2 | 없음 |
|
||||
| 명시적 `blocked` 또는 `error`(종료 코드 무관) | 원래 사유 보존, 각각 종료 2 또는 1 | 없음 |
|
||||
| `completed` + 종료 0 | 소유권·staged 경로 검증 후 커밋 | 없음 |
|
||||
| `completed` + nonzero | `error`, 종료 1 | 없음 |
|
||||
| 결과 미보고 + Executor wrapper의 실제 `TimeoutExpired` | transport timeout | 최초 포함 최대 2회 |
|
||||
| 결과 미보고 + 종료 0, 원인 미분류 nonzero | `error`, 종료 1 | 없음 |
|
||||
|
||||
종료 코드 124만으로 timeout을 추정하지 않는다. Wrapper가 실제 timeout을 관찰했을 때만
|
||||
raw output에 `transportFailure: "timeout"`을 기록한다. 제어·소유권 위반은 이 재시도보다
|
||||
우선하여 중단한다. 실패 결과를 `pending`으로 덮어쓰지 않고 원래 보고와 프로세스 진단을
|
||||
Executor 소유 history에 구분해 남긴다.
|
||||
|
||||
```text
|
||||
첫 번째 transport 시도 실패
|
||||
→ 오류를 다음 프롬프트에 삽입
|
||||
→ 두 번째 독립 Codex 실행
|
||||
→ 두 번째도 실패하면 error 기록 후 종료
|
||||
```
|
||||
|
||||
Coordinator의 workflow correction은 별도 budget이다. 정규화된
|
||||
`feature_id|failing_gate|failure_classification|contract_revision`별로 Correction을 최대
|
||||
한 번, 그 뒤 Implementation rerun을 한 번만 허용한다. 계약·환경·물리 실패를 transport
|
||||
재시도로 숨기거나 문구만 바꾸어 새 retry key를 만들지 않는다.
|
||||
|
||||
### 11.4 사용자 개입 필요
|
||||
|
||||
인증, API 키, 수동 설치처럼 Codex가 자동으로 해결할 수 없는 문제가 있으면 Step을
|
||||
`blocked`로 기록한다. Executor는 `blocked_at`과 top-level 상태를 갱신하고 종료 코드
|
||||
2로 중단한다.
|
||||
|
||||
재개 전 Coordinator가 원인 분류, 실패 evidence, retry key와 허용된 다음 작업을
|
||||
`coordination.md`에 보존한다. Coordinator는 phase 파일을 직접 편집하지 않는다.
|
||||
명시적으로 할당받은 Planning Agent가 Executor가 중단된 상태에서 phase index의 현재
|
||||
실패/차단 Step status만 `pending`으로 변경한다. 다른 Step, top-level 상태와 timestamp는
|
||||
변경하지 않는다. Executor가 재시작 시 오래된 outcome 필드·timestamp를 정리하되
|
||||
`attempt_history`는 유지한다. 기존 Step에 `owned_paths`가 없으면 승인 목록을 작성하는
|
||||
별도 Planning 할당이 필요하며 status 복구 권한만으로 목록을 추가·확대하지 않는다.
|
||||
이는 할당된 파일 편집 절차이며 자동 복구 명령이나 추가 correction 허용이 아니다.
|
||||
|
||||
## 12. Git 커밋과 phase 완료
|
||||
|
||||
Step이 성공하면 제품 변경과 Harness metadata를 분리해 다음 형식으로 커밋한다.
|
||||
|
||||
```text
|
||||
feat(add-division): step 0 - division-api
|
||||
chore(add-division): step 0 output
|
||||
```
|
||||
|
||||
두 번째 커밋의 `output`은 task index의 Step 상태와 summary 같은 Harness metadata를
|
||||
뜻한다. 원시 Codex 실행 기록인 `stepN-output.json`은 `.gitignore` 대상이며 커밋에
|
||||
포함되지 않는다.
|
||||
|
||||
모든 Step이 완료되면 Executor는 다음 작업을 수행한다.
|
||||
|
||||
- task의 `completed_at` 기록
|
||||
- `phases/index.json`의 task 상태를 `completed`로 변경
|
||||
- 최종 metadata 커밋
|
||||
- `--push` 사용 시 `origin/feat-{phase-name}`으로 push
|
||||
|
||||
Executor는 신뢰된 `owned_paths` snapshot으로 매 시도 후와 staging 직전의 변경 경로를
|
||||
검사한다. tracked/untracked, staged/unstaged, 생성·수정·삭제와 rename 양쪽 경로가 대상이다.
|
||||
Windows 경로 구분자·대소문자 alias를 정규화하며 디렉터리·링크 대체도 다시 검사한다.
|
||||
범위 밖 변경이 있으면 index를 정리하기 전에 중단하고 해당 경로와 사용자 파일을 보존한다.
|
||||
|
||||
검사 후 검증된 경로 snapshot에 한정해 index만 정리하고
|
||||
`git --literal-pathspecs add -A -- <선택 경로>`를 사용한다. 저장소 전체 index를 reset하지 않는다.
|
||||
Commit 직전에는 `git diff --cached --name-only --no-renames -z`의 실제 staged 경로도
|
||||
선택된 커밋 그룹과 대조한다. 구현 커밋에 phase metadata가 섞이는 것도 거부한다.
|
||||
범위 위반 시 추가 stage/commit·재시도·다음 Step을 중단하며 파일을 되돌리거나 allowlist를
|
||||
자동 확대하지 않는다. staging 후 발견한 위반은 당시 index를 남기므로 재개 전 검토가 필요하다.
|
||||
|
||||
동시 writer에 대한 원자적 격리는 보장하지 않으므로 실행 중 동시 편집을 피한다. 구현·metadata
|
||||
커밋도 단일 transaction이 아니다. 구현 커밋 후 metadata 커밋이 실패하면 기존 커밋을
|
||||
되돌리지 않고 Step을 `error`로 기록해 Coordinator에 반환한다.
|
||||
|
||||
## 13. 요구사항 종류별 동작
|
||||
|
||||
| 받은 요구사항 또는 변경 | PreToolUse 동작 | Stop 동작 |
|
||||
|---|---|---|
|
||||
| 새 C++ 제품 파일 추가 | 대응 테스트가 먼저 없으면 차단 | 전체 빌드·테스트 |
|
||||
| 기존 C++ 구현 또는 header 수정 | 대응 테스트 파일 존재 여부 검사 | 전체 빌드·테스트 |
|
||||
| 테스트 파일 추가 | TDD 차단 없이 허용 | 모든 테스트가 성공해야 종료 |
|
||||
| `main.cpp` 수정 | TDD 대응 테스트 검사 면제 | 전체 빌드·테스트 |
|
||||
| 유효한 동일 session/turn 기록의 내부 `.md` 편집만 있음 | C++ TDD 검사 없이 경로 기록 | build/test 생략, 통과 evidence 아님 |
|
||||
| JSON, Python 또는 다른 비문서 편집 | C++ TDD 검사 없음 | C++ 프로젝트가 있으면 전체 검증 |
|
||||
| 편집 기록 없음·손상 또는 shell 쓰기 | 완전한 편집 추적을 보장하지 않음 | 문서 전용 자동 생략을 보장하지 않음 |
|
||||
| 위험한 Git 또는 삭제 명령 | 즉시 차단 | 도달하지 않음 |
|
||||
| C++ 파일은 있지만 build metadata 없음 | 편집은 허용될 수 있음 | orphan 프로젝트 오류 |
|
||||
| 직접 MSBuild인데 `testCommand` 없음 | 편집은 허용될 수 있음 | 설정 오류로 종료 차단 |
|
||||
| C/C++가 전혀 없는 저장소 | 관련 편집 검사 없음 | 검증할 프로젝트가 없어 통과 |
|
||||
|
||||
## 14. 적용 전 준비사항
|
||||
|
||||
FESA는 실제 구조해석 솔버 프로젝트이며 Harness는 재사용 가능한 개발 운영 인프라다.
|
||||
일반 Feature 실행 전에 다음을 확인한다.
|
||||
|
||||
1. `AGENTS.md`, 공통 PRD·ARCHITECTURE·ADR와 승인된 Feature 범위를 읽는다.
|
||||
2. Feature 관리 문서·선행 계약·revision과 Planning/Implementation dispatch를 확인한다.
|
||||
일반 Feature 작업에서 프로젝트 공통 문서를 템플릿처럼 다시 작성하지 않는다.
|
||||
3. 기본 자동 감지로 충분하지 않을 때만 `.harness/config.example.json`을 참고해
|
||||
`.harness/config.json`을 만든다.
|
||||
4. FESA의 CMake/MSVC x64 Debug·CTest 명령과 dependency 경로를 확인한다. 다른 저장소에
|
||||
Harness를 적용할 때만 그 프로젝트의 승인된 adapter를 선택한다.
|
||||
5. phase 파일이 없다면 Planning Agent가 할당된 파일을 작성한다. 실행 권한은 별도로 확인한다.
|
||||
6. 시작 전 clean 범위와 실행 중 동시 편집 여부를 확인한다. 권한 상승은 clean linked
|
||||
worktree, native sandbox 실패 증거와 해당 실행 직전 승인·flag가 모두 필요하다.
|
||||
|
||||
특히 `AGENTS.md`와 `docs/*.md`는 각 Codex 실행에 그대로 주입된다. C++ 프로젝트에서
|
||||
TypeScript 예시나 미완성 placeholder가 남아 있으면 실제 작업 지시와 충돌할 수 있다.
|
||||
옛 phase/push/권한 상승 CLI와 legacy `tdd` 설정의 처리는
|
||||
[이전 운영 방식 안내](HARNESS.md#이전-운영-방식에서-달라진-점)를 따른다.
|
||||
사용자 config와 이력을 자동 migration하거나 실패 evidence를 지우지 않는다.
|
||||
로컬 검증은 commit·push·tag·release 또는 외부 solver 실행 권한을 부여하지 않는다.
|
||||
|
||||
+19
-16
@@ -41,15 +41,15 @@ Harness와 agent·skill은 이 목표를 달성하기 위한 개발 운영 인
|
||||
| 이 PRD | 제품 목적, 공통 요구사항, 품질 속성과 완료 기준 |
|
||||
| [ARCHITECTURE](ARCHITECTURE.md) | 공통 책임, 의존성, 수명과 확장 경계 |
|
||||
| [ADR](ADR.md) | 프로젝트 전반의 설계 결정과 변경 이력 |
|
||||
| Feature `PRD.md` | 해당 요구의 목적·범위·제외·acceptance 요약과 상세 요구사항 링크 |
|
||||
| Feature `requirements.md` | Requirement Agent가 소유하는 검증 가능한 요구사항과 verification matrix |
|
||||
| Feature `PRD.md` | 목적·범위·제외, 작은 요구사항·acceptance의 원본, 현재 checklist와 상세 계약 링크 |
|
||||
| Feature `requirements.md` | 복잡한 요구사항을 분리할 때만 작성하는 상세 요구사항과 verification matrix |
|
||||
| Feature `ADR.md` | 해당 Feature의 결정·이유·영향·owner와 승인 근거 |
|
||||
| Feature 전문 산출물 | 연구, 정식화, 수치/reference 검토, I/O, 구현·검증, 물리 검토와 release evidence |
|
||||
|
||||
Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분리는
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. Feature PRD가
|
||||
`requirements.md`와 별도의 요구사항 원본을 만들거나 공통 기준을 묵시적으로 덮어쓰지 않는다.
|
||||
공통 기준 자체의 변경은 별도로 승인된 프로젝트 문서 작업으로 다룬다.
|
||||
Feature 문서의 생성·재개, 메인이 관리하는 핵심 문서 3개와 선택적 상세 문서는
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 작은 요구사항은 Feature
|
||||
PRD에 정의하고, 상세 요구사항을 분리하면 PRD에는 요약과 링크만 남겨 원본을 중복하지 않는다.
|
||||
공통 기준을 묵시적으로 덮어쓰지 않으며 기준 자체의 변경은 별도로 승인된 문서 작업으로 다룬다.
|
||||
|
||||
## 공통 기능 요구사항
|
||||
|
||||
@@ -69,9 +69,9 @@ Feature 문서의 생성·재개, Coordinator 관리 문서와 상세 문서 분
|
||||
| FESA-PRD-GEN-007 | 결과의 물리량, location, units, coordinates, component, entity와 step/frame 의미를 식별할 수 있어야 한다. | I/O·result schema 계약과 mapping 검증 |
|
||||
| FESA-PRD-GEN-008 | 실패한 candidate가 유효한 state나 최종 결과를 부분적으로 오염시키지 않도록 계약된 보존 범위를 지켜야 한다. | State commit·복구·출력 실패 검증 |
|
||||
| FESA-PRD-GEN-009 | 외부 형식과 vendor/OS API를 adapter 뒤에 격리하고 solver core에 노출하지 않아야 한다. | Public dependency와 adapter 경계 검토 |
|
||||
| FESA-PRD-GEN-010 | Production 동작 변경은 관련 테스트의 기대 실패를 관찰한 뒤 구현하고 지정된 검증 evidence를 남겨야 한다. | RED/GREEN, focused/full 검증 명령과 실제 결과 |
|
||||
| FESA-PRD-GEN-010 | Production 동작 변경은 해당 동작을 확인하는 테스트로 검증하고, 버그는 가능한 경우 실패를 재현한 뒤 최소 수정해야 한다. | 변경 영향에 맞는 검사, 가능한 버그 재현, 기능 완료 시 전체 검증 명령과 실제 결과 |
|
||||
| FESA-PRD-GEN-011 | 기능에 필요한 독립 검증과 reference 비교를 수행하고 승인된 identity·수치 정책을 유지해야 한다. | 검증 matrix, 사전검사, reference 또는 명시적 N/A와 대체 근거 |
|
||||
| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 요구사항부터 물리 검토·release readiness까지의 gate 기록 |
|
||||
| FESA-PRD-GEN-012 | 기능 완료는 같은 계약 revision의 필수 evidence와 미해결 항목을 추적하여 판정해야 한다. | 해당 계약을 지지하는 검증 결과, 적용 범위·제한과 미해결 항목 |
|
||||
|
||||
요구사항 단계는 acceptance intent와 필요한 물리적 관찰을 정한다. Numerical Review는
|
||||
기존 승인 정책 안에서 논리적 비교량·identity/component·판정 구분을 구체화하고, I/O는 이를
|
||||
@@ -109,19 +109,22 @@ unit, analytical/benchmark, integration, convergence, invariant 및 외부 refer
|
||||
- 실패·미실행·stale evidence를 통과로 표시하지 않는다. 과거 통과 기록을 현재 검증으로
|
||||
소급 적용하지 않는다.
|
||||
|
||||
정규 Feature workflow는 다음과 같다.
|
||||
메인 assistant가 범위를 파악하고 필요한 전문 작업을 선택하여 구현·검증·결과 확인을
|
||||
조정한다. 수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review와
|
||||
해당 analytical/invariant 검증을 수행한다. 필요한 물리 검토와 reference 비교도 유지한다.
|
||||
|
||||
`requirements → research → formulation → numerical-review → io-definition →
|
||||
implementation-planning → implementation → physics-evaluation → release-readiness`
|
||||
변경 중에는 관련 검사를 수행하고, 솔버 기능 완료 시 구성된 전체 build/test와 계약상 필수
|
||||
reference 비교를 한 번 수행한다. 요청되거나 영향이 넓어 전체 검증이 필요한 경우에도
|
||||
실행한다. 이후 변경·실패가 없으면 같은 검증을 반복하지 않는다. 기존 coverage가 충분한
|
||||
rename/refactor에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
|
||||
구현 gate는 TDD, 지정된 전체 build/test와 필수 reference evidence가 갖추어졌을 때
|
||||
통과한다. Feature closure에는 그 뒤의 독립 물리 검토와 release-readiness 감사도 필요하다.
|
||||
Release readiness는 내부 완료 권고이며 외부 publish, push, tag, deploy 또는 package 권한이 아니다.
|
||||
Release-readiness 감사는 사용자가 명시적으로 요청할 때만 수행한다. Readiness 권고는
|
||||
외부 publish, push, tag, deploy 또는 package 권한이 아니다. 메인은 필수 evidence와
|
||||
미해결 항목을 확인하여 완료 여부를 판단하며, 문서 수정에는 정적 검토를 적용한다.
|
||||
|
||||
Owner, 공통 handoff, outcome, stale 처리와 유한 correction은
|
||||
현재 운영 결정은 [ADR-028](ADR.md#adr-028), 역할과 인계·실패 처리는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md)을 따른다. Skill의 적용 경계는
|
||||
[SOLVER_SKILL_DESIGN](SOLVER_SKILL_DESIGN.md), 실행 절차는 각 현재 `SKILL.md`를 따른다.
|
||||
문서만 수정하는 작업을 solver Feature 전체 workflow로 확대하지 않는다.
|
||||
|
||||
## 단계적 확장과 비목표
|
||||
|
||||
|
||||
+97
-182
@@ -1,220 +1,135 @@
|
||||
# Structural FEM Solver Agent Design
|
||||
|
||||
## 1. 목적
|
||||
## 목적
|
||||
|
||||
이 문서는 범용 유한요소 구조해석 솔버를 개발하는 agent들의 공통 운영 계약을 정의한다.
|
||||
`coordinator-agent`만 workflow 상태를 전이하며, specialist agent는 할당된 단계의 판단과
|
||||
산출물만 소유한다. 기능별 문서는 `docs/<feature-id>/`에 보존한다.
|
||||
폴더 생성, 공통 문서 참조, 간결한 본문과 상세 문서 분리는
|
||||
[Feature 문서 관리](FEATURE_DOCUMENTATION.md)를 따른다.
|
||||
메인 assistant가 작업 분해, 필요한 specialist 선택, 구현 조정과 완료 확인을 담당한다.
|
||||
작은 문서·구현·일상 결함은 직접 처리한다. Specialist는 전문 판단이나 독립 검토가
|
||||
필요한 bounded task에 사용하며 고정 lifecycle을 순회하기 위해 호출하지 않는다.
|
||||
|
||||
이 계약의 목표는 다음과 같다.
|
||||
현재 운영 결정은 [ADR-028](ADR.md#adr-028), Feature 폴더와 산출물 관리는
|
||||
[FEATURE_DOCUMENTATION](FEATURE_DOCUMENTATION.md)을 따른다. 필요한 계약과 검증은
|
||||
유지하면서 문맥 재독, 형식적 인계와 같은 결과의 반복 검토를 줄인다.
|
||||
|
||||
- 수치적·물리적 책임을 명확히 분리한다.
|
||||
- 저장소 안에서 되돌릴 수 있는 일반 작업은 agent가 자율적으로 완료한다.
|
||||
- 사용자 승인은 제품 의미나 acceptance boundary가 바뀌는 결정에만 사용한다.
|
||||
- 모든 gate 전이를 경로가 확인되는 증거로 재현할 수 있게 한다.
|
||||
- 실패 재시도를 유한하게 제한하고 계약 문제를 구현 수정으로 숨기지 않는다.
|
||||
|
||||
## 2. 권한과 판단 기준
|
||||
## 권한과 판단 기준
|
||||
|
||||
충돌하는 정보는 다음 우선순위로 판단한다.
|
||||
|
||||
1. 사용자가 승인한 feature contract와 critical decision
|
||||
2. 지배 방정식, 수학적 일관성, 적용되는 표준과 검증된 1차 문헌
|
||||
3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 verification 사례
|
||||
4. `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`, `docs/TOLERANCE.md`와 기존 승인 계약
|
||||
1. 현재 사용자 요청의 범위·권한과 승인된 Feature contract·critical decision
|
||||
2. 지배 방정식, 수학적 일관성, 적용 표준과 검증된 1차 문헌
|
||||
3. Abaqus 공식 공개 문서의 관찰 가능한 입력 syntax·semantics, 출력 정의와 검증 사례
|
||||
4. 프로젝트 지침, architecture, ADR, tolerance와 기존 승인 계약
|
||||
5. 저장소 관례에 맞는 가장 단순하고 결정적인 구현
|
||||
|
||||
Abaqus는 외부 reference convention이다. Agent는 지원하기로 한 공개 입력의 의미, 해석
|
||||
절차, 출력량 정의 및 검증 사례를 참고할 수 있지만 Abaqus의 비공개 알고리즘, 내부 자료
|
||||
구조, 수렴 제어 구현 또는 결과 생성 방식을 추정하거나 내부 동등성을 주장하면 안 된다.
|
||||
관찰 가능한 호환성을 말할 때도 지원 subset과 차이를 명시한다.
|
||||
Abaqus는 외부 reference convention이다. 지원 subset의 공개 입력 의미와 승인된 비교량을
|
||||
참고하되 비공개 알고리즘·내부 상태·결과 생성 절차를 추정하거나 내부 동등성을 주장하지
|
||||
않는다. 수치 결과의 exact equality는 허용되지만 내부 동등성의 evidence가 아니다.
|
||||
의미상 무해하다고 계약된 항목만 명시적 warning/no-op으로 처리하고 그 밖의 미지원
|
||||
semantics는 fail-closed로 진단한다.
|
||||
|
||||
공개 의미가 불분명하거나 지원하지 않는 keyword를 임의로 해석하지 않는다. 의미상 무해함이
|
||||
입증된 항목만 명시적 warning 정책을 사용할 수 있고, 그 밖의 미지원 semantics는 fail-closed로
|
||||
진단한다. 이것이 지원 범위나 공개 호환성을 바꾸는 경우에만 사용자 결정을 요청한다.
|
||||
## 메인의 작업 조정
|
||||
|
||||
## 3. 계층과 단독 상태 전이
|
||||
메인은 관련 계약과 현재 evidence를 확인하여 작업·수정 파일·검증 기준을 정한다.
|
||||
새 Feature에 지속할 계약이나 근거가 필요하면 `docs/<feature-id>/`를 초기화하고
|
||||
`FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`를 관리한다. 작은 수정에는 새 Feature 폴더나
|
||||
빈 보고서를 만들지 않는다. 현재 checklist는 PRD 한 곳에 둔다.
|
||||
|
||||
`coordinator-agent`는 유일한 main agent이며 다음 loop를 소유한다.
|
||||
메인은 계획·구현·일반 실패 수정을 직접 수행하거나 필요한 구현 묶음을 위임할 수 있다.
|
||||
Specialist는 할당된 판단과 파일만 소유하며 다른 계약을 수정하거나 peer를 재위임하지
|
||||
않는다. 메인은 결과를 확인하되 독립 검토가 필요한 판단을 작성자의 자기 승인으로 대체하지
|
||||
않는다. 누락된 evidence는 통과가 아니다.
|
||||
|
||||
```text
|
||||
INTAKE -> STATE AUDIT -> DISPATCH -> EVIDENCE CHECK -> TRANSITION -> RECORD
|
||||
```
|
||||
## Specialist 선택
|
||||
|
||||
- Coordinator는 요구사항 접수 시 Feature 폴더와 `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`,
|
||||
`coordination.md`를 생성하고 문서 목록과 참조를 관리한다. 프로젝트 기준 문서는 보존한다.
|
||||
- Coordinator만 `docs/<feature-id>/coordination.md`의 현재 stage, outcome과 next owner를 바꾼다.
|
||||
- Coordinator는 다음 eligible owner에게 한 번에 하나의 bounded task만 dispatch한다.
|
||||
- Specialist는 peer를 호출하거나 workflow를 전이하거나 자신의 산출물을 최종 승인하지 않는다.
|
||||
- Specialist가 반환하는 `outcome`은 전이 요청이다. 실제 전이는 Coordinator가 증거를 확인한
|
||||
후 기록한다.
|
||||
- Coordinator는 specialist의 수식, 코드, 검증 또는 release 판단을 대신하지 않는다.
|
||||
- 누락된 증거는 통과로 간주하지 않는다.
|
||||
현재 profile은 [`.codex/agents`](../.codex/agents)에 있다.
|
||||
|
||||
## 4. 단계와 소유권
|
||||
|
||||
| Stage | Owner | Owned outputs |
|
||||
| Specialist | 호출할 때 | 기본 추론 강도 |
|
||||
| --- | --- | --- |
|
||||
| intake / coordination | `coordinator-agent` | `FEATURED_AGENTS.md`, `PRD.md`, `ADR.md`, `coordination.md` |
|
||||
| `requirements` | `requirement-agent` | `requirements.md` |
|
||||
| `research` | `research-agent` | `research.md` |
|
||||
| `formulation` | `formulation-agent` | `formulation.md` |
|
||||
| `numerical-review` | `numerical-review-agent` | `numerical-review.md`, `reference-model.md` |
|
||||
| `io-definition` | `io-definition-agent` | `io.md` |
|
||||
| `implementation-planning` | `implementation-planning-agent` | `implementation-plan.md`, assigned Harness phase files |
|
||||
| `implementation` | `implementation-agent` | implementation files, tests, build registration, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
|
||||
| `physics-evaluation` | `physics-evaluation-agent` | `physics-evaluation.md` |
|
||||
| `release-readiness` | `release-agent` | `release.md` |
|
||||
| `requirement-agent` | 범위·acceptance가 복잡하거나 상충하여 별도 계약 정리가 필요 | `medium` |
|
||||
| `research-agent` | 사용할 이론·benchmark·reference 근거가 부족 | `medium` |
|
||||
| `formulation-agent` | 새 수식·요소·재료·해석 알고리즘 정식화가 필요 | `high` |
|
||||
| `numerical-review-agent` | 새 정식화·주요 수치 변경·원인 불명의 수치 불일치를 독립 검토 | `high` |
|
||||
| `io-definition-agent` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경 | `medium` |
|
||||
| `implementation-agent` | 메인이 직접 수행하기보다 위임할 이점이 있는 구현 묶음 | `medium` |
|
||||
| `physics-evaluation-agent` | 새 해석 기능이나 결과의 평형·물리적 타당성·coverage 평가가 필요 | `high` |
|
||||
|
||||
`correction-agent`는 정규 stage가 아니다. Coordinator가 허용한 한 번의 correction에서만
|
||||
implementation-owned 파일과 `corrections.md`를 수정한다.
|
||||
수식·요소·재료·적분·상태 갱신을 추가하거나 변경하면 독립 numerical review를 수행한다.
|
||||
역할의 조건부 호출은 해당 analytical/invariant 검증이나 계약상 필수 물리·reference
|
||||
검증을 생략할 근거가 아니다. Release-readiness 감사는 사용자 명시 요청 시에만
|
||||
`fem-release-readiness`로 수행하며 전용 release profile이나 필수 종료 stage를 두지 않는다.
|
||||
|
||||
문서 경로는 모두 `docs/<feature-id>/` 기준이다. 각 specialist는 자신의 기본 산출물에
|
||||
연결하는 상세 문서도 소유한다. Coordinator의 전체 문서 관리는 목록·참조·상태 관리이며
|
||||
specialist 본문의 편집 권한을 뜻하지 않는다.
|
||||
모델과 역할별 강도는 현재 profile을 따른다. 난해한 정식화·수렴 문제에만 필요한 범위에서
|
||||
강도를 높인다. Profile 변경만으로 이미 실행 중인 session의 설정이 갱신되었다고 가정하지
|
||||
않는다. 불필요한 진행 확인·보고서 재작성·같은 결과의 재검토를 위해 agent를 호출하지 않는다.
|
||||
|
||||
각 owner의 결정권은 해당 산출물에만 적용된다. Downstream agent는 upstream 계약을 편집하거나
|
||||
재해석해서 gate를 통과할 수 없다. 문제가 upstream 계약에 있으면 `return-upstream`과 정확한
|
||||
`next_owner`를 반환한다. Workspace write 권한은 역할의 수정 경계를 넓히지 않는다.
|
||||
## 작업 인계와 반환
|
||||
|
||||
## 5. 공통 handoff envelope
|
||||
Dispatch에는 다음 정보만 필요한 만큼 전달한다.
|
||||
|
||||
모든 dispatch와 return은 다음 필드를 사용한다. 추가 세부정보는 소유 산출물에 기록하고
|
||||
envelope에는 전이에 필요한 요약만 둔다.
|
||||
- 수행할 작업과 결정할 문제
|
||||
- 관련 계약·원문의 경로와 절, 필요한 Feature context
|
||||
- 수정할 정확한 파일과 제외 범위
|
||||
- 검증 기준과 완료에 필요한 evidence
|
||||
|
||||
```yaml
|
||||
feature_id: <stable feature id>
|
||||
stage: requirements | research | formulation | numerical-review | io-definition |
|
||||
implementation-planning | implementation | correction | physics-evaluation |
|
||||
release-readiness
|
||||
outcome: pass | return-upstream | retry | blocked-environment | needs-user-decision
|
||||
next_owner: <agent id or null>
|
||||
evidence_paths: [<repository-relative path>]
|
||||
evidence_digest: <commands, exit codes, decisive findings, artifact hashes when relevant>
|
||||
failure_classification: <normalized class or null>
|
||||
retry_key: <feature-id|failing-gate|classification|contract-revision or null>
|
||||
attempt: <nonnegative integer>
|
||||
escalation_class: <critical class or null>
|
||||
blocker: <actionable blocker or null>
|
||||
```
|
||||
새 agent는 도구가 지원하면 `fork_turns="none"`으로 시작하여 필요한 문맥만 전달한다.
|
||||
연속 수정은 기존 agent에 짧은 후속 작업으로 보낸다. 같은 문맥에서 읽은 변경 없는 자료를
|
||||
다시 읽거나 모든 Feature 문서를 매번 주입하지 않는다.
|
||||
|
||||
필드 규칙은 다음과 같다.
|
||||
Return은 결과·판단, 변경 파일, 실행한 명령·exit code·결정적 결과, 미해결 항목·제한을
|
||||
간결하게 전달한다. 고정 envelope, outcome enum, retry signature나 artifact hash를 모든
|
||||
작업에 요구하지 않는다. 추적에 필요한 계약 revision과 실제 evidence 경로는 남기고,
|
||||
긴 로그·유도·schema는 원본을 연결한다.
|
||||
|
||||
- `evidence_paths`는 실제 존재하며 현재 stage가 소유하거나 읽도록 허용된 경로여야 한다.
|
||||
- `evidence_digest`는 원시 로그 전체가 아니라 명령, 종료 코드, 판정값과 잔여 위험을 담는다.
|
||||
- 실패가 없으면 `failure_classification`과 `retry_key`는 `null`이다.
|
||||
- `needs-user-decision`은 `escalation_class`와 선택 가능한 대안 및 영향을 산출물에 기록해야 한다.
|
||||
- `blocked-environment`는 필요한 환경 변화와 재개 조건을 기록한다.
|
||||
- `attempt`는 같은 `retry_key`에 대한 실행 횟수이며 Coordinator가 관리한다.
|
||||
- Dispatch는 `docs/<feature-id>/`와 Feature 관리 문서 3개를 필수 입력으로 명시한다.
|
||||
기본·상세 산출물의 owner를 지정하고 반환된 상세 문서도 `evidence_paths`로 확인한다.
|
||||
## 구현·검증과 완료
|
||||
|
||||
## 6. Outcome과 전이 규칙
|
||||
동작 변경에는 그 동작을 확인하는 테스트를 추가·수정하고, 버그는 가능한 경우 실패를
|
||||
재현한 뒤 최소 수정한다. 충분한 기존 coverage가 있는 rename/refactor나 문서 수정에는
|
||||
형식적인 새 테스트를 요구하지 않는다.
|
||||
|
||||
| Outcome | 의미 | Coordinator action |
|
||||
| --- | --- | --- |
|
||||
| `pass` | 현재 owner의 gate evidence가 완전함 | 다음 정규 stage로 전이 |
|
||||
| `return-upstream` | 선행 계약의 수정이 필요함 | `next_owner`로 되돌리고 영향받은 downstream gate를 stale 처리 |
|
||||
| `retry` | 계약을 바꾸지 않는 bounded rerun이 가능함 | retry 정책 안에서 지정 owner를 재호출 |
|
||||
| `blocked-environment` | 도구·권한·의존성·라이선스 문제로 신뢰성 있는 진행 불가 | 상태를 보존하고 환경 수정 전까지 중단 |
|
||||
| `needs-user-decision` | 아래 critical decision이 필요함 | 하나의 결정 묶음으로 사용자에게 요청 |
|
||||
변경 중에는 관련 검사를 실행한다. 솔버 기능 완료 시, 사용자가 요청한 경우 또는 영향이
|
||||
넓어 필요한 경우 구성된 전체 build/test를 한 번 수행한다. 기능 완료에 필요한 reference
|
||||
비교도 수행하며 이후 변경·실패가 없으면 같은 검사를 반복하지 않는다. 문서 작업은 정적
|
||||
검토로 확인하고 build/test를 실행하지 않는다.
|
||||
|
||||
`blocked`, `approved`, `ready-for-*`, `pass-for-*`, `needs-*` 같은 별도 return status를 만들지
|
||||
않는다. 문서 내부 review verdict가 필요하면 설명으로 기록하되 workflow 전이는 위 다섯 outcome만
|
||||
사용한다.
|
||||
메인은 완료를 판단할 때 다음을 확인한다.
|
||||
|
||||
정규 통과 순서는 다음과 같다.
|
||||
- 해당 요구와 계약을 지지하는 실제 결과가 있고 stale/missing evidence가 아님
|
||||
- 수치 변경에 필요한 독립 검토, analytical/invariant와 물리 검증이 있음
|
||||
- Reference quantity, unit, coordinate/component와 source identity가 대응함
|
||||
- Missing, extra, duplicate와 nonfinite required value를 tolerance 전에 거부함
|
||||
- [TOLERANCE](TOLERANCE.md)와 승인된 Feature 판정 기준을 유지함
|
||||
- 실제 명령·exit code·판정값과 가정·미지원 범위·잔여 위험을 재현 가능하게 기록함
|
||||
|
||||
```text
|
||||
requirements -> research -> formulation -> numerical-review -> io-definition
|
||||
-> implementation-planning -> implementation -> physics-evaluation
|
||||
-> release-readiness -> completed
|
||||
```
|
||||
Reference artifact와 상위 계약을 구현 결과에 맞춰 생성·보정하거나 tolerance를 완화하지
|
||||
않는다. 실패·미실행 검사를 통과로 표시하지 않으며 과거 통과를 현재 검증으로 소급하지 않는다.
|
||||
|
||||
Numerical review는 formulation correctness와 reference-model readiness가 모두 확보되어야
|
||||
`pass`할 수 있다. Implementation은 TDD evidence, 전체 build/test와 feature가 요구하는
|
||||
reference comparison이 모두 통과해야 `pass`할 수 있다. Release의 `pass`는 내부 readiness
|
||||
closure일 뿐 publish, deploy, push, tag 또는 package 권한이 아니다.
|
||||
## 실패 처리와 사용자 결정
|
||||
|
||||
## 7. 자율 진행과 사용자 escalation
|
||||
일반 구현 실패는 현재 구현 owner가 재현·수정하고 관련 검사를 수행한다. 새 근거나 변경
|
||||
없이 같은 명령·agent 호출을 반복하지 않는다. 다른 관점이 필요할 때만 원인과 관련 evidence를
|
||||
전문가에게 전달한다. 고정 correction 횟수나 transport 재시도 예산을 두지 않는다.
|
||||
|
||||
Agent는 다음과 같은 저장소 내부의 되돌릴 수 있는 일반 결정을 자율적으로 수행한다.
|
||||
상위 계약 결함은 정확한 계약 owner와 경로를 메인에 알린다. Downstream이 요구사항·수식·
|
||||
schema·tolerance·reference를 바꾸어 실패를 숨기지 않는다. 실제 계약 변경은 영향받은
|
||||
evidence를 다시 확인하고, 환경 문제는 필요한 환경 변화와 재개 조건을 기록한다.
|
||||
|
||||
- 승인 계약을 구현하는 파일 배치, private API와 내부 자료구조 선택
|
||||
- 기존 규칙에 따른 테스트 분해, config-selected build/test backend 등록, 진단 문구와 오류 처리
|
||||
- 문서·계획·evidence report의 생성 및 갱신
|
||||
- 명백한 compile, link, test, parser와 implementation defect의 최소 수정
|
||||
- Numerical Review가 `docs/TOLERANCE.md`와 feature evidence에 따라 선택하는 비교 quantity,
|
||||
identity/component, metric, scale, blocking/diagnostic 구분과 수치 tolerance
|
||||
- 공식 문서와 저장소 관례가 하나의 의미를 정하는 secondary convention
|
||||
- 안전한 read-only 조사, local build/test와 저장된 reference artifact 비교
|
||||
승인된 범위 안의 되돌릴 수 있는 저장소 작업에는 반복적인 중간 승인 절차를 추가하지 않는다.
|
||||
계획 요청만으로 실행 권한을 추정하지 않으며 다음 결정이 실제로 필요할 때 사용자에게
|
||||
대안·권고·영향을 함께 제시한다.
|
||||
|
||||
다음 항목만 `needs-user-decision`으로 escalation한다.
|
||||
- 지원 physics·제품 범위·공개 호환성의 변경
|
||||
- 지배 방정식·정식화·재료 모델 등 물리적 의미의 선택
|
||||
- 합격/불합격이나 공개 정확도 약속을 바꾸는 acceptance·tolerance 선택
|
||||
- Authoritative 입력·영속 결과 schema의 비호환 변경이나 해결되지 않은 필수 계약/reference 충돌
|
||||
- 외부 solver의 라이선스·자격증명·비공개 자료·비용 또는 외부 협조
|
||||
- 중대한 보안·신뢰 경계 변경이나 해결되지 않은 보안·법률·라이선스 위험 수용
|
||||
- 파괴적 Git/파일 작업, push·tag·publish·deploy·package·release
|
||||
|
||||
- feature scope, 지원 해석 유형 또는 공개 호환성의 변경
|
||||
- 지배 방정식, 요소 정식화, 재료 모델, 접촉·동역학 등 물리적 의미의 선택
|
||||
- 합리적인 두 acceptance 기준이 동일 evidence를 pass와 fail로 나누고 그 선택이 제품
|
||||
acceptance 의미나 공개 정확도 약속을 바꾸는 경우
|
||||
- authoritative input/output schema나 영속 public contract의 비호환 변경
|
||||
- authoritative requirement와 reference evidence가 충돌하고 기술 evidence로 우선순위를
|
||||
결정할 수 없는 경우
|
||||
- 외부 solver 실행에 필요한 라이선스·자격증명·비공개 자료
|
||||
- 보안·신뢰 경계 또는 credential 처리의 중대한 변경, 해결되지 않은 보안·법률·라이선스
|
||||
위험의 수용
|
||||
- destructive Git 작업, 외부 게시, push, tag, deploy, package 또는 release
|
||||
내부 검증 또는 readiness 권고는 외부 실행 권한이 아니다. 이미 승인된 작업의 일반 문서
|
||||
작성·로컬 실행·인계마다 승인을 다시 요구하지 않는다.
|
||||
|
||||
질문은 결정 가능한 대안, downstream 영향과 권고안을 하나로 묶는다. 단순 진행 확인,
|
||||
일반 문서 승인, 계획 승인 또는 agent 간 handoff 승인을 반복해서 요청하지 않는다.
|
||||
## 언어와 기록
|
||||
|
||||
## 8. 실패 분류와 유한 correction
|
||||
|
||||
실패 분류는 최소한 다음 값을 정규화해 사용한다.
|
||||
|
||||
```text
|
||||
configure | compile | link | test | reference-comparison | harness |
|
||||
environment | upstream-contract | physics | evidence
|
||||
```
|
||||
|
||||
Coordinator는 다음 요소로 retry signature를 만든다.
|
||||
|
||||
```text
|
||||
retry_key = feature_id | failing_gate | normalized_failure_classification | contract_revision
|
||||
```
|
||||
|
||||
동일 `retry_key`에 대한 Correction loop는 한 번만 허용한다.
|
||||
|
||||
1. Implementation Agent가 실패를 분류하고 명백한 implementation-owned defect를 최소 수정·재검증한다.
|
||||
2. 반복되거나 원인이 불명확하면 Coordinator가 해당 key의 correction 사용 이력을 확인한다.
|
||||
3. 사용 이력이 없을 때만 Correction Agent를 한 번 dispatch한다.
|
||||
4. Correction Agent는 `retry`로 Implementation rerun을 요청하고 Coordinator가 rerun을 dispatch한다.
|
||||
5. 같은 key가 다시 실패하면 두 번째 correction을 금지한다. 계약 문제는 `return-upstream`,
|
||||
환경 문제는 `blocked-environment`, 실제 critical choice만 `needs-user-decision`으로 전환한다.
|
||||
|
||||
문구만 바꾸거나 동일 계약 revision을 새 key로 가장하면 안 된다. Upstream 계약이 승인된 방식으로
|
||||
변경된 경우에만 `contract_revision`을 올리고 새 signature를 만든다.
|
||||
|
||||
## 9. Evidence gate
|
||||
|
||||
Coordinator는 `pass` 전에 다음을 확인한다.
|
||||
|
||||
- 요구되는 산출물이 존재하고 owner가 명시되어 있다.
|
||||
- 선행 artifact와 revision이 일치하며 stale evidence가 아니다.
|
||||
- 실행 증거에는 실제 명령, 종료 코드, 핵심 결과가 있다.
|
||||
- 수치 비교에는 quantity, unit, coordinate/component, matching rule과 적용 tolerance가 있다.
|
||||
- reference row의 missing, extra, duplicate와 nonfinite 값은 tolerance 판정 전에 검출된다.
|
||||
- 가정, 미지원 범위와 잔여 위험이 기록되어 있다.
|
||||
- specialist owner의 결론을 Coordinator나 downstream agent가 대신 만들지 않았다.
|
||||
- Feature 문서 목록과 기본·상세 문서 링크가 유효하고 필수 상세 근거까지 검토되었다.
|
||||
|
||||
Reference input과 결과 artifact는 명시적으로 소유 agent가 아닌 한 read-only다. 저장된 외부
|
||||
reference 결과를 임의로 생성·보정하거나 통과하도록 수치를 변경해서는 안 된다.
|
||||
|
||||
## 10. 언어와 기록
|
||||
|
||||
- 기능 문서는 사용자가 다른 언어를 요청하지 않는 한 한국어 Markdown으로 작성한다.
|
||||
- Agent id, field name, outcome, failure classification, requirement id, path와 command는 English를 유지한다.
|
||||
- Requirement id 기본 형식은 `FEM-REQ-<FEATURE>-###`이다.
|
||||
- Placeholder artifact는 만들지 않는다. Correction이 실제 발생할 때만 `corrections.md`를 만든다.
|
||||
- 모든 stage는 자신이 변경한 경로와 변경하지 않은 upstream contract를 명확히 기록한다.
|
||||
기능 문서는 기본적으로 한국어 Markdown으로 작성한다. Agent/skill ID, field,
|
||||
requirement ID, 경로와 명령은 English를 유지한다. 새 requirement ID 기본 형식은
|
||||
`FEM-REQ-<FEATURE>-###`이다. 보고서는 실제 결정과 evidence를 한 번만 기록하고,
|
||||
기존 phase·coordination·실패 기록은 이력으로 보존한다.
|
||||
|
||||
+68
-141
@@ -1,165 +1,92 @@
|
||||
# Structural FEM Solver Skill Design
|
||||
|
||||
## 1. 목적
|
||||
## 목적과 적용 원칙
|
||||
|
||||
Project-local skill은 범용 유한요소 구조해석 solver feature를 요구사항부터 release readiness까지
|
||||
일관되게 처리하는 재사용 절차다. Agent가 stage의 책임과 write boundary를 소유하고, skill은
|
||||
그 stage에서 필요한 판단 방법, evidence와 output contract를 제공한다.
|
||||
Project-local skill은 필요한 FEM 판단과 검증 방법을 제공한다. 고정 lifecycle의 모든
|
||||
skill을 순회하지 않는다. 메인 assistant 또는 할당된 specialist는 현재 작업에 필요한
|
||||
skill과 직접 영향받는 계약만 읽는다.
|
||||
|
||||
실행 지침의 source of truth는 각 `.codex/skills/<skill-name>/SKILL.md`다. 공통 workflow와
|
||||
상태 전이는 `docs/SOLVER_AGENT_DESIGN.md`, 수치 비교 정책은 `docs/TOLERANCE.md`가 소유한다.
|
||||
Skill entrypoint는 이 공통 규칙을 반복하지 않고 역할에 필요한 차이만 제공한다.
|
||||
실행 지침의 원본은 각 `SKILL.md`다. 역할·인계는
|
||||
[SOLVER_AGENT_DESIGN](SOLVER_AGENT_DESIGN.md), 공통 운영 결정은
|
||||
[ADR-028](ADR.md#adr-028), 수치 비교 정책은 [TOLERANCE](TOLERANCE.md)를 따른다.
|
||||
|
||||
## 2. 설계 원칙
|
||||
- 이름과 description은 실제 사용할 조건을 구분한다.
|
||||
- `SKILL.md`에는 목적·필요 입력·판단 규칙·결과·수정 경계를 둔다.
|
||||
- 긴 유도나 toolchain·해석 계열별 절차는 `references/`에서 필요할 때만 읽는다.
|
||||
- 같은 문맥에서 읽은 변경 없는 자료를 재독하거나 모든 Feature 문서를 인계에 넣지 않는다.
|
||||
- Skill은 승인된 작업 범위나 외부 실행 권한을 넓히지 않는다.
|
||||
- FESA가 선택한 MSVC, Abaqus 입력 subset, HDF5 출력과 수치 계약은 유지한다.
|
||||
- 필요한 산출물만 [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 작성한다.
|
||||
빈 보고서, 고정 envelope·outcome, 자동 commit이나 workflow 상태 파일을 요구하지 않는다.
|
||||
|
||||
- 이름과 description은 실제 activation boundary를 구분할 수 있어야 한다.
|
||||
- `SKILL.md`에는 목적, 필요한 입력, 핵심 workflow, output/evidence와 hard boundary만 둔다.
|
||||
- 해석 유형별 상세 checklist, toolchain 절차처럼 조건부 정보는 `references/`에서 필요한
|
||||
경우에만 읽는다.
|
||||
- Skill은 승인된 user/project scope를 확장하거나 외부 실행 권한을 암시하지 않는다.
|
||||
- 산출물은 Coordinator가 생성·관리하는 `docs/<feature-id>/`의 공통 feature bundle에 둔다.
|
||||
- [Feature 문서 관리](FEATURE_DOCUMENTATION.md)에 따라 핵심 결과만 본문에 두고 필요한
|
||||
상세 내용은 같은 폴더의 별도 문서로 분리해 참조한다. Feature 관리 문서에서 공통 기준과
|
||||
현재 작업을 연결하며 프로젝트 `AGENTS.md`, `docs/PRD.md`, `docs/ADR.md`는 보존한다.
|
||||
- 모든 stage는 공통 handoff envelope와 다섯 outcome을 사용한다.
|
||||
- Input, result container, tabular comparison format, compiler와 build adapter는 project/feature
|
||||
contract가 선택한다. 특정 형식을 solver identity로 고정하지 않는다.
|
||||
- Read-only 조사와 reversible in-repository 판단은 자율 수행한다. Critical decision만
|
||||
`needs-user-decision`으로 반환한다.
|
||||
## FEM skill inventory
|
||||
|
||||
## 3. Workflow skill inventory
|
||||
다음 8개 skill은 [`.codex/skills`](../.codex/skills)에 있다. 대표 산출물은 필요한
|
||||
경우의 예시이며 모든 작업에 별도 파일을 생성하라는 요구가 아니다.
|
||||
|
||||
| Stage | Skill | 대표 산출물 |
|
||||
| Skill | 사용할 때와 필요한 입력 | 결과와 경계 |
|
||||
| --- | --- | --- |
|
||||
| Requirements | `fem-requirements-baseline` | `requirements.md` |
|
||||
| Research | `fem-research-evidence` | `research.md` |
|
||||
| Formulation | `fem-formulation-spec` | `formulation.md` |
|
||||
| Numerical review | `fem-numerical-review` | `numerical-review.md`, `reference-model.md` |
|
||||
| I/O definition | `fem-io-contract` | `io.md` |
|
||||
| Planning/implementation/correction | `fem-implementation-tdd` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md`, 필요 시 `corrections.md` |
|
||||
| Physics evaluation | `fem-physics-review` | `physics-evaluation.md` |
|
||||
| Release readiness | `fem-release-readiness` | `release.md` |
|
||||
| `fem-requirements-baseline` | 지속할 scope·acceptance 계약이 필요할 때 사용자 요구와 관련 기존 계약 확인 | 검증 가능한 요구·acceptance; 복잡하면 `requirements.md`와 matrix로 분리. 수식·schema·수치 기준을 선결정하지 않음 |
|
||||
| `fem-research-evidence` | 이론·benchmark 근거가 부족할 때 구체적인 solver 질문과 관련 원문 확인 | 출처 있는 연구 근거·적용 한계·gap. 사실과 추론을 구분하고 정식화 결론을 대신하지 않음 |
|
||||
| `fem-formulation-spec` | 새 수학 모델이나 변경된 정식화가 필요할 때 관련 요구·근거 확인 | DOF/kinematics, residual/tangent, integration, state update와 recovery 계약. 구현이나 자기 승인을 하지 않음 |
|
||||
| `fem-numerical-review` | 정식화·안정성·검증 범위의 독립 검토가 필요할 때 수식과 evidence 확인 | 수치 위험·analytical/invariant 검증·reference-model 준비 판단. 비교량·identity·location·units를 정의하고 저장 layout은 I/O에 남김 |
|
||||
| `fem-io-contract` | 입력 의미·진단·결과 schema·comparison mapping이 새로 생기거나 변경될 때 관련 계약 확인 | 지원 subset, fail-closed 진단, 결과 의미와 저장·비교 mapping. 공개 compatibility를 임의 확대하지 않음 |
|
||||
| `fem-implementation-tdd` | 솔버 계획·구현·수정 시 할당 작업, 영향받는 계약과 build 설정 확인 | 최소 코드·의미 있는 테스트·필요한 계획과 검증 evidence. 상위 계약·reference·tolerance를 결과에 맞추어 수정하지 않음 |
|
||||
| `fem-physics-review` | 결과의 평형·부호·대칭·energy·mode·coverage 평가가 필요할 때 결과와 승인 기준 확인 | 물리적 타당성과 적용 한계. 새 acceptance를 즉석에서 만들거나 코드·계약을 수정하지 않음 |
|
||||
| `fem-release-readiness` | 사용자가 release-readiness 감사를 명시 요청할 때 해당 Feature 계약·결과·제한 확인 | 필수 evidence와 잔여 위험에 대한 내부 권고. 필수 lifecycle stage나 외부 release 권한이 아님 |
|
||||
|
||||
위 8개가 lifecycle workflow skill이다. 폴더명, frontmatter `name`, agent prompt와
|
||||
`agents/openai.yaml` invocation name은 항상 동일해야 한다.
|
||||
수식·요소·재료·적분·상태 갱신 변경의 독립 numerical review와 해당 analytical/invariant
|
||||
검증은 유지한다. 메인은 `fem-implementation-tdd`를 직접 사용하여 계획·구현·일반 실패
|
||||
수정을 수행할 수 있다. 별도 planning/correction profile이나 Harness phase 파일이 필요하지 않다.
|
||||
|
||||
## 4. Stage별 책임 분리
|
||||
## Supporting skill
|
||||
|
||||
### Requirements
|
||||
|
||||
`fem-requirements-baseline`은 scope, observable requirement, acceptance intent와
|
||||
requirement-verification matrix를 정의한다. Formulation, tolerance 값, API와 storage schema를
|
||||
선결정하지 않는다.
|
||||
|
||||
### Research
|
||||
|
||||
`fem-research-evidence`는 governing theory, primary source, benchmark와 reference convention의
|
||||
신뢰성·적용 한계를 정리한다. 사실, 계산, 추론과 evidence gap을 구분하며 formulation 결론을
|
||||
대신 만들지 않는다.
|
||||
|
||||
### Formulation
|
||||
|
||||
`fem-formulation-spec`은 strong/weak form, variables/DOF, kinematics, constitutive update,
|
||||
residual/tangent, integration, state와 recovery를 implementation-neutral 수학 계약으로 만든다.
|
||||
선택된 linear/nonlinear/dynamic/eigen/contact/material family의 reference만 읽는다.
|
||||
|
||||
### Numerical review
|
||||
|
||||
`fem-numerical-review`는 formulation을 독립 검토하고 requirement를 falsify할 verification
|
||||
coverage를 정의한다. Logical quantity, identity, location, units와 tolerance 근거까지 소유하지만
|
||||
physical dataset/file layout은 I/O stage에 남긴다.
|
||||
|
||||
### I/O definition
|
||||
|
||||
`fem-io-contract`은 선택된 external syntax와 semantic model, versioned result schema 및
|
||||
comparison identity 사이를 mapping한다. 미지원 semantic construct, validation과 diagnostic을
|
||||
명시한다. Subset 지원을 full compatibility로 표현하지 않는다.
|
||||
|
||||
### Planning, implementation와 correction
|
||||
|
||||
`fem-implementation-tdd`는 approved upstream bundle을 작은 RED/GREEN step으로 계획하고 C++
|
||||
변경, configured build/test와 필요한 reference comparison evidence를 만든다. Implementation은
|
||||
upstream contract, tolerance 또는 reference artifact를 결과에 맞춰 고치지 않는다.
|
||||
|
||||
Executor의 process/session 재시도는 transport attempt이며 Coordinator의 normalized
|
||||
failure/correction budget과 별개다. 동일 `retry_key`의 correction은 한 번만 허용한다.
|
||||
|
||||
### Physics evaluation
|
||||
|
||||
`fem-physics-review`는 numerically passing result가 문서화된 equilibrium, sign, symmetry,
|
||||
energy, mode와 model coverage 기대를 만족하는지 독립 검토한다. 새 acceptance를 즉석에서
|
||||
만들지 않는다.
|
||||
|
||||
### Release readiness
|
||||
|
||||
`fem-release-readiness`는 동일 feature/contract revision의 traceability, gate evidence,
|
||||
limitations와 release-note draft를 감사한다. Readiness verdict는 publish, tag, deploy 또는
|
||||
external release 권한이 아니다.
|
||||
|
||||
## 5. Supporting skill
|
||||
|
||||
| Skill | 적용 조건 |
|
||||
| Skill | 적용 조건과 경계 |
|
||||
| --- | --- |
|
||||
| `fem-theory-query` | 사용자가 configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때 |
|
||||
| `harness` | implementation phase를 만들거나 bounded Executor 작업을 수행할 때 |
|
||||
| `review` | repository diff를 architecture, numerical, test와 evidence 기준으로 읽기 전용 검토할 때 |
|
||||
| `fem-theory-query` | configured FEM wiki 근거를 요청하거나 vault coverage gap을 조사할 때. 일반 FEM 질문 전체에 적용하지 않음 |
|
||||
| `harness` | 구성된 build/test를 명시적으로 실행할 때. `python scripts/execute.py` 사용; phase 계획·agent 호출·Git 관리 기능 없음 |
|
||||
| `review` | 요청된 diff와 영향받는 계약·correctness·검증·범위를 읽기 전용 검토할 때. 수정 요청 없이 finding을 고치지 않음 |
|
||||
|
||||
`fem-theory-query`는 일반 FEM 질문 전체를 가로채지 않는다. Vault path는 environment,
|
||||
project instruction 또는 untracked local override에서 해석하며 workstation 절대 경로를
|
||||
commit하지 않는다. External research나 vault write는 해당 요청과 권한이 있을 때만 수행한다.
|
||||
`fem-theory-query`의 vault resolution과 citation 규칙을 유지한다. Workstation 절대 경로는
|
||||
untracked local override 등에 두고 commit하지 않는다. 외부 조사나 vault 수정에는 해당
|
||||
요청과 권한이 필요하다. Harness는 수치·물리·reference 검증이나 외부 solver 권한을 대신하지
|
||||
않으며 명령과 설정은 [HARNESS](HARNESS.md)를 따른다.
|
||||
|
||||
Harness skill은 build/test command authority와 Executor/runtime ownership을 정의한다. Hook은
|
||||
guardrail이며 RED observation이나 complete sandbox를 대신하지 않는다.
|
||||
## 결과와 evidence
|
||||
|
||||
## 6. 공통 evidence
|
||||
결과에는 작업을 지지하는 판단·가정, 변경 파일, 실제 명령·exit code·결정적 판정값,
|
||||
evidence 경로와 미해결 항목·제한만 필요한 만큼 기록한다. 수치 비교는 quantity,
|
||||
identity/component, units, metric과 승인된 tolerance source를 확인한다.
|
||||
|
||||
Skill output은 해당 stage에 필요한 부분만 작성하되 handoff에는 다음을 포함한다.
|
||||
실행하지 않았거나 실패한 검사, missing/stale blocking evidence를 통과로 표시하지 않는다.
|
||||
긴 로그와 이미 정의된 수식을 여러 보고서에 복사하거나 의미 변화 없는 문서 편집마다
|
||||
revision/hash·gate 기록을 새로 만들지 않는다. 실제 계약이 변경되면 영향받은 evidence의
|
||||
유효성을 다시 확인한다.
|
||||
|
||||
- `feature_id`, `stage`, `outcome`, `next_owner`
|
||||
- `evidence_paths`, current contract revision과 artifact identity/hash
|
||||
- decisive finding, command, exit code, duration과 test count
|
||||
- comparison quantity, identity, units, metric와 tolerance source
|
||||
- `failure_classification`, `retry_key`, `attempt`
|
||||
- `escalation_class`, actionable blocker와 residual risk
|
||||
동작 변경은 해당 테스트로 검증하고 버그는 가능한 경우 실패를 재현한다. 변경 중에는 관련
|
||||
검사를 실행하며 솔버 기능 완료 시 구성된 전체 build/test와 필수 reference 비교를 한 번
|
||||
수행한다. 요청이나 넓은 변경 영향으로 전체 검증이 필요한 경우에도 실행하되 이후 변경·
|
||||
실패가 없으면 반복하지 않는다. 충분한 기존 coverage가 있는 refactor에는 형식적인 새
|
||||
테스트를 요구하지 않는다.
|
||||
|
||||
필요한 명령이 실패했거나 실행되지 않았고 blocking evidence가 stale/missing이면 `pass`를
|
||||
반환하지 않는다. Raw log 전체를 모든 skill 문서에 복사하지 않고 재현 가능한 digest와 원본
|
||||
artifact path를 남긴다.
|
||||
## Reference와 사용자 결정 경계
|
||||
|
||||
## 7. Abaqus reference policy
|
||||
Abaqus의 공개 입력 의미·출력 정의·검증 사례는 승인된 범위의 reference로 사용한다.
|
||||
비공개 내부 알고리즘·상태·결과 생성 절차의 동등성이나 full compatibility를 주장하지
|
||||
않는다. 수치적 exact equality는 내부 동등성의 evidence가 아니다.
|
||||
|
||||
Abaqus는 project가 선택한 경우 다음 공개 observable convention의 기준으로 사용한다.
|
||||
저장된 artifact의 읽기와 외부 Abaqus 실행은 다른 권한이다. Reference 생성·수정·복원은
|
||||
명시적으로 승인된 범위에서만 다루며 구현 통과를 위해 값을 보정하지 않는다. Numerical
|
||||
Review는 공통 TOLERANCE 안에서 기능별 비교량·identity·판정 구분을 정의하며 임의로
|
||||
수치 기준을 완화하지 않는다.
|
||||
|
||||
- input keyword와 option의 문서화된 syntax/semantics
|
||||
- model data와 history/step data의 구분
|
||||
- element formulation, integration과 output location 정의
|
||||
- analysis procedure와 convergence 개념
|
||||
- verification guide의 benchmark 구성과 expected physical behavior
|
||||
지원 physics·공개 호환성·authoritative schema·acceptance 변경, 해결되지 않은 필수
|
||||
계약/reference 충돌, 외부 권한이나 파괴적·원격·release 작업은 사용자 결정 경계를 따른다.
|
||||
이미 승인된 범위의 일반 작업과 skill 인계에 반복 승인을 추가하지 않는다.
|
||||
|
||||
Skill은 비공개 내부 구현을 추정하지 않고 full compatibility나 solver equivalence를 주장하지
|
||||
않는다. External Abaqus execution은 저장된 artifact를 읽는 것과 다른 권한이며 라이선스,
|
||||
자격증명, 비용과 명시된 command scope가 확보된 경우에만 수행한다.
|
||||
## Skill 변경의 확인
|
||||
|
||||
## 8. Autonomous decision boundary
|
||||
|
||||
Skill은 approved contract 안의 내부 naming/layout, test 분해, diagnostic, 문서 형식, 기술
|
||||
근거가 유일한 convention과 명백한 결함 수정을 자율적으로 처리한다. Numerical Review는
|
||||
`docs/TOLERANCE.md`와 evidence로 feature-specific metric/tolerance를 결정할 수 있다.
|
||||
|
||||
지원 physics/범위, 공개 compatibility, authoritative schema, product acceptance를 바꾸는
|
||||
tolerance, 상충하는 필수 reference evidence, 외부 권한 또는 destructive/release 작업만
|
||||
사용자 결정이 필요하다. “계속할까요?” 같은 routine approval을 stage 사이에 추가하지 않는다.
|
||||
|
||||
## 9. Validation
|
||||
|
||||
Skill 변경 후 다음을 검증한다.
|
||||
|
||||
- lifecycle skill 8개와 supporting skill의 frontmatter parse
|
||||
- 폴더명, `name`, `openai.yaml` invocation과 agent 참조 일치
|
||||
- relative reference link의 존재와 repository containment
|
||||
- canonical output path와 common outcome vocabulary
|
||||
- product-specific legacy name과 machine-specific absolute path 부재
|
||||
- realistic requests를 이용한 최소 forward-test
|
||||
|
||||
Project에 validator가 제공되면 해당 validator와 repository pytest suite를 모두 실행한다.
|
||||
Validator 부재 또는 미실행을 성공으로 간주하지 않는다.
|
||||
Skill 자체를 변경할 때 영향받는 frontmatter, 폴더명·invocation·agent 참조, 상대 링크와
|
||||
조건부 reference를 확인한다. 변경된 동작에 필요한 최소 검사를 선택하며 제공되는
|
||||
validator나 관련 repository 검사가 필요하면 실행한다. 문서 설명만 수정하는 작업에
|
||||
전체 pytest나 solver build를 강제하지 않는다. 정적 검토와 실제 실행 여부를 구분해 기록한다.
|
||||
|
||||
@@ -0,0 +1,282 @@
|
||||
# Agent·Harness 경량화 문서 갱신 Implementation Plan
|
||||
|
||||
> **For agentic workers:** 후속 실행에는 `superpowers:executing-plans`를 적용하되 아래 문서 작업을 메인이 직접 수행한다. 고정 solver stage, task별 새 subagent·reviewer, 자동 commit을 추가하지 않는다.
|
||||
|
||||
**Goal:** 승인된 Agent·Harness 경량화를 FESA의 공통 문서 10개에 반영하여 현재 운영 지침과 구현의 불일치를 없앤다.
|
||||
|
||||
**Architecture:** `docs2/agent-harness-simplification`의 승인된 운영 변경을 현재 `.agents`, `.codex`, `scripts`에 대조하여 반영한다. FESA 제품·수치·입출력·C++ 계약은 유지하고, 공통 ADR에는 기존 결정과 구분되는 후속 결정을 기록한다.
|
||||
|
||||
**Tech Stack:** 한국어 Markdown, PowerShell 기반 정적 확인. 문서에 설명할 검증 환경은 기존 CMake/MSVC x64/Debug, CTest, Python Harness다.
|
||||
|
||||
**Spec:** [경량화 PRD](../../../docs2/agent-harness-simplification/PRD.md), [AH-01~05 결정](../../../docs2/agent-harness-simplification/ADR.md), [승인 계획 보존본](../../../docs2/agent-harness-simplification/implementation-details.md), [기존 구현 보고서](../../../docs2/agent-harness-simplification/implementation-report.md).
|
||||
|
||||
작성일: 2026-09-07. 상태: **문서 갱신 계획안**. 이번 요청에서는 이 계획만 작성하며 대상 문서를 수정하거나 Harness를 실행하지 않는다. 아래 checkbox는 후속 문서 작업의 완료 조건이다.
|
||||
|
||||
## 1. 범위와 기준
|
||||
|
||||
### Global Constraints
|
||||
|
||||
- 후속 수정 범위는 사용자가 지정한 `AGENTS.md`와 `docs/` 문서 9개로 제한한다. 정확한 목록은 §3을 따른다.
|
||||
- 현재 사용자의 `.agents`, `.codex`, `.harness`, `scripts`, `docs2` 변경을 보존한다. 이 계획으로 구현·테스트·설정·phase 이력을 수정하지 않는다.
|
||||
- FESA의 C++17 이상, CMake/MSVC/x64/Debug, MKL/TBB/HDF5와 승인된 Abaqus 입력 subset을 유지한다.
|
||||
- HDF5 `<stem>_results.h5`의 lexical sibling 경로, source identity, 결정론, state/output 보존, 기존 B33/MITC4 비교량·판정 구분을 유지한다.
|
||||
- [TOLERANCE](../../TOLERANCE.md), reference artifact와 solver 구현은 수정 대상이 아니다. 수치 검토와 필요한 analytical/invariant·reference 검증을 유지한다.
|
||||
- 운영 간소화를 이유로 물리 의미, 공개 schema, 지원 범위, tolerance, 외부 실행·원격·파괴 작업 권한을 확대하지 않는다.
|
||||
- 작은 문서 작업에는 solver Feature 폴더·관리 문서·stage 보고서를 새로 만들지 않는다. 이 계획도 별도 solver Feature workflow를 시작하지 않는다.
|
||||
- 문서만 갱신하므로 새 테스트, pytest, Harness, CMake/CTest, 수동 hook을 실행하지 않는다. 확인 범위는 문서·링크·설정·소스의 정적 대조다.
|
||||
- 기존 문서의 언어·구성을 가능한 한 유지한다. 문서 전체 복사나 요청과 무관한 코딩 규약 정리는 하지 않는다.
|
||||
|
||||
### 근거의 적용 순서
|
||||
|
||||
1. 현재 사용자가 요청한 문서 갱신 범위와 경량화 목적.
|
||||
2. `docs2/agent-harness-simplification`에 기록된 AH-01~05의 운영 변경과 유지할 acceptance.
|
||||
3. 현재 저장소의 실제 agent/skill profile, runner, config/discovery/adapter/process 구현.
|
||||
4. 기존 FESA 제품·수치·아키텍처 계약과 현재 preset. 구현이 이 계약을 변경할 권한은 없다.
|
||||
|
||||
`docs2`의 공통 문서는 문안 참고 자료다. 기존 FESA 문서를 통째로 대체하는 원본으로 사용하지 않는다. 승인 설명과 현재 구현이 다르면 운영 의도와 관찰된 동작을 구분하고, 문서로 미구현 기능이나 검증 통과를 선언하지 않는다.
|
||||
|
||||
## 2. 현재 확인한 차이와 반영 판단
|
||||
|
||||
| 근거 | 확인한 내용 | 문서 반영 판단 |
|
||||
| --- | --- | --- |
|
||||
| [현재 profiles](../../../.codex/agents) | 7개 specialist만 남고 일반 역할은 `medium`, 정식화·수치·물리 역할은 `high`다. Implementation profile의 모델은 `gpt-5.6-terra`다. | 삭제된 4개 전용 역할과 일괄 `xhigh` 요구를 제거한다. 모델 선택은 profile로 연결하고 runtime 적용을 검증했다고 주장하지 않는다. |
|
||||
| [runner](../../../scripts/execute.py), [harness skill](../../../.agents/skills/harness/SKILL.md) | 인자 없는 명시적 검증 실행기다. 내부 LLM, phase 상태 처리, 자동 Git·retry가 없다. | 새 CLI와 현재 exit 의미를 설명한다. 옛 CLI는 폐기 안내에서만 보여 준다. |
|
||||
| [config](../../../scripts/msvc_harness/config.py), [discovery](../../../scripts/msvc_harness/discovery.py) | legacy `tdd`는 설정 로드 시 안내 후 무시한다. C++ 전체 scan과 orphan-C++ gate가 없다. | 현재 없는 TDD pattern 설정·C++ 파일 scan·자동 skip 설명을 삭제한다. |
|
||||
| [config 예시](../../../.harness/config.example.json), [presets](../../../CMakePresets.json) | 예시는 `projectType=cmake`, `sourceDir=.`만 지정한다. FESA Ninja preset은 별도로 존재한다. | 예시 복사만으로 Ninja preset을 선택한다고 쓰지 않는다. 명시적 preset 설정 예시를 유지한다. |
|
||||
| `docs2`의 PRD·ARCHITECTURE·구현 보고서 | solver/build metadata가 없는 framework checkout을 전제로 한다. | 현재 [CMakeLists](../../../CMakeLists.txt), [solver target](../../../src/fesa/CMakeLists.txt), [test target](../../../tests/CMakeLists.txt)이 있으므로 해당 현황 설명은 옮기지 않는다. |
|
||||
| `docs2`와 현재 공통 ADR | 같은 ADR 번호가 다른 결정을 뜻한다. `docs2` ADR-013은 신뢰 경계이고, 현재 ADR-013은 선형 보 해석 범위다. | 번호를 복사하지 않는다. 현재 문서의 마지막 ID 다음인 ADR-028에서 실제 대체 대상을 명시한다. |
|
||||
| `docs2`의 구현 보고서와 현재 `tests/` | 보고서의 `test_executor.py` 등과 현재 테스트 파일 구성이 다르며, 현재에는 삭제된 executor/hook을 기대하는 테스트가 남아 있다. | 과거 29건 통과를 현재 checkout의 검증 결과로 사용하지 않는다. 테스트 정합성은 §7의 별도 후속 항목으로 기록한다. |
|
||||
|
||||
`docs2/agent-harness-simplification/ADR.md`의 “프로젝트 PRD·ADR 원문 보존”은 이전 구현 범위의 기록이다. 현재 요청은 두 문서의 운영 조항 갱신을 명시적으로 포함하므로 계획에서 제외하지 않는다. 기존 제품 계약과 ADR 결정 본문은 보존하면서 현행 규칙과 대체 관계를 명료하게 만든다.
|
||||
|
||||
## 3. 파일별 수정 계획
|
||||
|
||||
| 대상 | 변경할 절과 내용 | 보존·확인 기준 |
|
||||
| --- | --- | --- |
|
||||
| [AGENTS.md](../../../AGENTS.md) | `문서 기준과 Feature 관리`, `개발 운영 인프라`, `개발 프로세스`, `Agent/Skill Workflow`, `최소 검증 진입점`을 갱신한다. 메인 직접 조정, 조건부 specialist, 핵심 문서 3개·PRD checklist, 간결한 인계, 명시적 검증을 요약한다. 소유권 절의 매 변경 RED·대응 C++ test 강제를 동작 중심 검증으로 바꾸고, reference 변경 권한의 “요청된 phase”를 “명시적으로 요청된 작업 범위”로 고친다. | 제품 정체성, FESA 기술 스택, 수치·선형 정적 불변식, reference 무결성, 사용자 변경 보존을 유지한다. 상세 CLI·workflow를 중복 복사하지 않고 전담 문서에 연결한다. |
|
||||
| [docs/ADR.md](../../ADR.md) | ADR-028을 추가하고 ADR-012·024~027에 대체/부분 대체 안내를 붙인다. 머리말의 현행 운영 ADR 범위와 ADR-001·002 등의 현행 운영 참조를 확인한다. | 기존 ID와 결정 본문을 소급 재작성하지 않는다. 실제 ADR-013 및 다른 solver 결정은 변경하지 않는다. §4의 대체 범위를 사용한다. |
|
||||
| [docs/ARCHITECTURE.md](../../ARCHITECTURE.md) | `Solver runtime과 개발 운영 영역`의 개발 흐름, `개발 운영 인프라`의 owner 표·실행 책임, 끝의 Feature 요구사항 원본 설명을 수정한다. 메인, specialist, 명시적 runner, backend adapter/process의 책임을 구분한다. `검증과 reference 경계`의 전문 책임을 필수 agent 순회로 읽히지 않게 정리한다. | Solver runtime 그림·모듈 책임·Domain/AnalysisModel/DofManager·의존성·수명·해석 lifecycle·출력 계약은 보존한다. Runner를 보안 sandbox나 solver correctness 판정기로 표현하지 않는다. |
|
||||
| [docs/PRD.md](../../PRD.md) | 문서 역할 표의 Feature PRD를 작은 요구사항의 원본으로, `requirements.md`를 필요 시 분리하는 상세 계약으로 바꾼다. `FESA-PRD-GEN-010`은 동작 중심 테스트·가능한 버그 재현과 영향별 검증으로 수정한다. `FESA-PRD-GEN-012`의 evidence를 필수 stage/gate 기록에서 해당 계약의 검증·제한·미해결 항목으로 수정한다. `검증과 완료 기준`의 9단계 순회와 필수 release audit를 제거한다. | GEN-001~009·011과 제품 정의·품질 속성·비목표의 물리/수치 의미를 보존한다. 필요한 독립 수치 검토·물리 검증·reference 비교, 같은 계약을 지지하는 evidence와 stale 판정을 유지한다. |
|
||||
| [docs/SOLVER_AGENT_DESIGN.md](../../SOLVER_AGENT_DESIGN.md) | 고정 stage·Coordinator 전용 전이·12필드 envelope·5개 outcome 강제·correction signature/budget을 제거한다. 메인의 작업 선택, 7개 specialist 호출 조건/수정 경계/기본 강도, 간단한 dispatch·return, 구현 owner의 실패 수정, 완료 evidence와 사용자 결정 경계를 정의한다. | 새 수식·요소·재료·적분·상태 갱신의 독립 numerical review를 유지한다. 상위 계약 문제의 owner 반환, 무근거 반복 금지, specialist의 범위 제한을 유지한다. |
|
||||
| [docs/SOLVER_SKILL_DESIGN.md](../../SOLVER_SKILL_DESIGN.md) | `Stage` 중심 inventory를 `사용할 때 / 필요한 입력 / 결과` 중심으로 바꾼다. 8개 FEM skill과 supporting skill을 현재 `SKILL.md`에 맞춘다. implementation skill은 메인도 계획·구현·수정에 사용하고, release skill은 사용자 명시 요청 시에만 사용한다. | `fem-theory-query`의 configured vault 범위, read-only review, tolerance·reference·외부 권한 경계를 유지한다. 모든 문서 재독·공통 outcome/hash·전체 pytest를 문서 편집의 필수 절차로 강제하지 않는다. |
|
||||
| [docs/HARNESS_WORKFLOW.md](../../HARNESS_WORKFLOW.md) | 요구사항→phase/index/step→Codex→hook→자동 commit 흐름을 관련 계약 확인→변경→관련 검사→기능 완료 시 전체 검사 흐름으로 재구성한다. 현행 runner의 config→discovery→toolchain→adapter→execute_plan 순서와 실패 중단을 설명한다. 문서·일반 버그·새 수치 기능의 3개 사례를 둔다. | 현행 config/경로 검사, MSVC 확인, CTest discovery, timeout·실패 진단은 보존한다. 폐기한 phase schema·출력 JSON·owned_paths·attempt_history를 새 절차에 요구하지 않는다. |
|
||||
| [docs/HARNESS.md](../../HARNESS.md) | 설치·설정·명령·진단에 집중한다. Harness 실행의 Codex CLI 의존 설명을 제거한다. 인자 없는 CLI, 자동 감지, exit 0/1/2, preset 설정, legacy `tdd`와 옛 CLI 안내를 §5대로 작성한다. hook·sandbox 환경변수·자동 Git·phase 복구·TDD 확장 절을 정리한다. | Windows/MSVC·CMake/CTest·dependency 준비, Python 요구와 재사용 MSBuild adapter 안내를 유지한다. FESA 제품 검증은 CMake/CTest라는 구분을 보존한다. |
|
||||
| [docs/CODINGSTYLE.md](../../CODINGSTYLE.md) | `Test와 변경 관리` 및 `Implementation Agent Checklist`를 메인/구현 담당자 공통 지침으로 바꾼다. 모든 C++ 변경의 test-file 동반·Step별 RED/full 강제를 영향별 테스트와 검증으로 바꾼다. 충분한 기존 coverage가 있는 rename/refactor에는 형식적 새 테스트를 요구하지 않는다. | PascalCase, include guard, 2-space/80-column, production Doxygen, vendor 경계, 신규 warning 금지 등을 유지한다. B33/MITC4 output 변경의 필수 reference 재검증을 유지한다. |
|
||||
| [docs/FEATURE_DOCUMENTATION.md](../../FEATURE_DOCUMENTATION.md) | 새 Feature가 필요한 조건과 메인 소유 핵심 문서 3개를 명시한다. 현재 checklist는 PRD 한 곳, 작은 요구사항도 PRD 원본, 별도 requirements/matrix·상세 보고서는 필요한 경우만 생성하도록 바꾼다. 간단한 구현·build/test·reference evidence는 한 보고서에 합칠 수 있게 한다. | `FEATURED_AGENTS.md`의 비자동 로드 성격, 상대 링크, specialist의 할당 문서 소유권과 필수 근거를 유지한다. 기존 `coordination.md`, `docs/features/` 자료는 이력으로 보존하고 신규 상태기계나 일괄 이관을 만들지 않는다. |
|
||||
|
||||
## 4. ADR-028에 기록할 결정
|
||||
|
||||
제안 제목: **ADR-028: 메인이 필요한 전문 작업을 조정하고 Harness를 명시적 검증 실행기로 사용한다**.
|
||||
|
||||
근거는 현재 사용자 요청, 경량화 Feature의 AH-01~05와 실제 source다. 이 계획에서 ADR-028을 이미 작성·승인된 문서처럼 표시하지 않는다. 후속 반영 시 기존 경량화 승인과 이번 문서 동기화 근거를 구분해 연결한다.
|
||||
|
||||
| 기존 ADR | 대체할 운영 부분 | 유지되는 부분 |
|
||||
| --- | --- | --- |
|
||||
| ADR-012 | 전용 Planning/Executor/Hook 분업과 hook 기반 강제 검증 | 실제 테스트 실행과 단순 파일 존재의 구분, 검증 evidence의 필요성 |
|
||||
| ADR-024 | 전용 Coordinator, 고정 상태 전이, correction 1회/rerun 1회, 필수 release stage | 승인 범위 안의 자율 작업, 필요한 사용자 결정, 미실행·실패를 통과로 표시하지 않음, 외부 권한 분리 |
|
||||
| ADR-025 | 관리 문서 4개, `coordination.md` 상태 원본, 모든 요구의 `requirements.md` 분리, 매 dispatch의 전체 bundle 필수화 | 프로젝트/Feature 계약 구분, 전문 문서 소유권, 상대 링크와 중복 방지, 실제 계약 변경에 따른 evidence 영향 확인 |
|
||||
| ADR-026 | Executor의 Git·transport 관리, hook TDD/Stop, 자체 sandbox 승인 장치 | config/preset/command의 신뢰 경계, 사용자 변경 보존, 실제 runtime 권한, 검증 범위와 미실행의 명확한 보고 |
|
||||
| ADR-027 | phase Step payload, `owned_paths`, `attempt_history`, 자동 commit 경계와 transport 재시도 계약 | 실패 증거와 사용자 변경을 보존하고 범위 밖 작업을 하지 않는 일반 원칙 |
|
||||
|
||||
ADR-028 본문에는 AH-01~05의 효과를 한 번만 기록한다: 메인 orchestration, 명시적 runner, 영향에 맞는 검사, 필요한 문맥만 전달, 핵심 문서 3개와 선택적 상세 기록. 상세 명령과 산출물 형식은 각각 HARNESS·FEATURE_DOCUMENTATION으로 연결한다. 과거 본문의 폐기된 역할/명령 검색 결과는 이력임을 분명히 표시한다.
|
||||
|
||||
## 5. 현행 Harness 설명에 넣을 정확한 계약
|
||||
|
||||
### 명령과 설정
|
||||
|
||||
```powershell
|
||||
python scripts/execute.py
|
||||
```
|
||||
|
||||
이 명령은 명시적으로 선택/발견한 backend의 전체 검증을 한 번 수행한다. Focused check는 실제 configured backend 명령으로 직접 실행한다. Runner가 Feature 문서에서 reference 명령을 찾아 추가 실행하거나 `phases/`를 읽고 갱신한다고 설명하지 않는다.
|
||||
|
||||
FESA Ninja preset을 사용하려면 기존 개인 설정을 보존하면서 다음 필드를 함께 맞춘다. 이번 문서 작업에서 개인 설정은 편집하지 않는다.
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"projectType": "cmake",
|
||||
"cmake": {
|
||||
"sourceDir": ".",
|
||||
"binaryDir": ".harness/build-ninja-msvc-debug",
|
||||
"configurePreset": "windows-msvc-ninja-debug",
|
||||
"buildPreset": "windows-msvc-ninja-debug",
|
||||
"testPreset": "windows-msvc-ninja-debug"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
현재 `.harness/config.example.json`에는 preset 필드가 없다. `CMakePresets.json`이 존재하거나 예시 설정을 복사했다는 사실만으로 preset이 선택되지는 않는다. Preset 없는 adapter 기본값과 FESA preset 사용법을 구분하여 설명한다.
|
||||
|
||||
### 결과와 보장 범위
|
||||
|
||||
| 조건 | 현재 동작 |
|
||||
| --- | --- |
|
||||
| 구성된 검증이 모두 성공 | runner exit 0, 실행 명령·cwd·exit와 test 출력 요약 |
|
||||
| config/discovery/toolchain/adapter 오류, backend 실패·timeout, non-MSVC, CTest 0개 등 | runner exit 1. Backend의 원래 nonzero는 진단에 남지만 runner가 같은 숫자를 그대로 반환하는 것은 아님 |
|
||||
| 자동 감지에서 build metadata 없음 | `not configured`와 exit 2. 검증 통과나 조용한 skip이 아님 |
|
||||
| 명시한 projectType에 필요한 metadata가 없음 | 잘못된 명시 설정 경로의 실패로 exit 1 |
|
||||
| 옛 `<phase>`, `--push`, `--approve-danger-full-access` 인자 | argparse usage error, exit 2. 검증을 시작하지 않음 |
|
||||
| legacy `tdd` 항목 | `load_config` 호출 시 폐기 안내를 내고 무시. Config를 자동 수정하지 않음 |
|
||||
| CMake 경로 | configure → MSVC 확인 → build → CTest discovery/0개 거부 → test |
|
||||
| MSBuild adapter 경로 | build → 명시된 testCommand. FESA의 solution-only 검증을 승인하는 의미가 아님 |
|
||||
|
||||
명령은 `shell=False`로 실행하며 repository-relative 설정 경로와 cwd 범위, timeout을 검사한다. 전체 deadline은 현재 1,800초이고 각 명령에는 남은 시간과 명령 timeout 중 짧은 값이 적용된다. 실패 후 후속 단계나 자동 재시도를 실행하지 않는다. Config·preset·실행 파일 자체의 side effect를 sandbox처럼 격리하는 기능은 아니다.
|
||||
|
||||
내부 Codex 호출·프롬프트 주입, phase 상태기계, branch/commit/push, 대응 파일명 TDD gate, 등록된 PreToolUse/Stop과 자체 sandbox 승인은 제거되었다. 실제 도구·runtime 권한은 계속 따른다. 기존 phase·hook 기록은 이력으로 남기며 새 runner의 입력이나 필수 정리 대상으로 삼지 않는다.
|
||||
|
||||
## 6. 실행 순서와 문서별 완료 확인
|
||||
|
||||
### Task 1: 공통 운영 결정과 제품 완료 기준
|
||||
|
||||
**Modify:** `docs/ADR.md`, `docs/PRD.md`.
|
||||
|
||||
**입력:** AH-01~05, 현재 공통 ADR-012·024~027, GEN-010·012. **결과:** 나머지 문서가 참조할 단일 현행 운영 결정과 완료 기준.
|
||||
|
||||
- [ ] ADR-028과 §4의 대체 안내를 작성하고 기존 결정 본문·번호를 보존한다.
|
||||
- [ ] PRD의 문서 역할, GEN-010·012, 검증·완료 절을 §3대로 수정한다.
|
||||
- [ ] 새 수치 변경의 독립 검토, 필요한 물리/수치/reference evidence가 여전히 필수인지 확인한다. Release audit는 명시 요청일 때만 수행하도록 맞춘다.
|
||||
- [ ] 두 문서의 diff를 읽어 운영 이외 제품 요구가 변경되지 않았고, 현재 FESA의 ADR-013에 경량화 신뢰 경계를 덮어쓰지 않았는지 확인한다.
|
||||
|
||||
### Task 2: Agent·Skill·Feature 문서 운영
|
||||
|
||||
**Modify:** `docs/SOLVER_AGENT_DESIGN.md`, `docs/SOLVER_SKILL_DESIGN.md`, `docs/FEATURE_DOCUMENTATION.md`.
|
||||
|
||||
**입력:** Task 1, 현재 profile·SKILL.md. **결과:** 조건부 역할 선택, 최소 인계, 핵심 문서 3개의 일관된 계약.
|
||||
|
||||
- [ ] 7개 역할을 호출 조건과 기본 강도로 설명하고 메인의 직접 계획·구현·수정 책임을 명시한다.
|
||||
- [ ] 고정 stage/envelope/outcome/retry budget을 제거한다. Dispatch는 작업·관련 경로/절·수정 파일·검증 기준, return은 결과·변경 파일·검사 결과·미해결 항목으로 정리한다.
|
||||
- [ ] 필요한 문서만 읽고 연속 수정은 같은 owner가 수행하도록 정리한다. 지원되는 경우 `fork_turns="none"`을 사용하되 실제 도구·역할 설정이 기준임을 유지한다.
|
||||
- [ ] PRD checklist·선택적 requirements 및 상세 보고서, 기존 coordination 이력 보존을 세 문서에서 일치시킨다.
|
||||
- [ ] 기존 numerical/reference/physics 검토의 실질적 내용이 단순 역할 삭제와 함께 사라지지 않았는지 확인한다.
|
||||
|
||||
### Task 3: Harness 사용법과 실행 흐름
|
||||
|
||||
**Modify:** `docs/HARNESS.md`, `docs/HARNESS_WORKFLOW.md`.
|
||||
|
||||
**입력:** Task 1~2, runner/config/discovery/adapter/process, 현재 preset. **결과:** §5와 일치하는 사용법과 영향별 검증 사례.
|
||||
|
||||
- [ ] HARNESS에는 설치·설정·정확한 CLI·exit·이전 방식 변경 안내를 둔다. 기존 설정을 무조건 덮어쓰는 복사 안내는 피한다.
|
||||
- [ ] HARNESS_WORKFLOW는 메인의 개발 흐름과 runner 내부 실행 순서로 재작성한다. 설치/JSON 예시는 HARNESS에 연결하여 중복을 줄인다.
|
||||
- [ ] 문서만 변경하면 정적 검토, 일반 버그는 재현·관련 검사, 새 수치 기능은 필요한 정식화·독립 검토·구현·물리/reference 검사로 분기하는 표를 작성한다.
|
||||
- [ ] 도움말·usage·backend 결과는 소스로 대조한다. 문서 갱신 확인을 위해 실제 runner나 pytest를 실행하지 않는다.
|
||||
|
||||
### Task 4: 루트 지침·아키텍처·코딩 지침 동기화
|
||||
|
||||
**Modify:** `AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/CODINGSTYLE.md`.
|
||||
|
||||
**입력:** Task 1~3의 현행 계약. **결과:** 다음 작업부터 적용되는 짧고 모순 없는 루트 지침.
|
||||
|
||||
- [ ] AGENTS의 운영·Feature 관리·검증 절을 갱신하고 상세 전담 문서에 링크한다. 모든 문서·모든 stage를 매 작업마다 읽으라는 의무를 제거한다.
|
||||
- [ ] ARCHITECTURE의 개발 흐름과 owner 표를 바꾸고 solver runtime 책임과 물리/수치 계약을 보존한다.
|
||||
- [ ] CODINGSTYLE의 동작 검증·refactor 예외·전체 검증 시점·담당자 checklist만 수정한다. Doxygen/naming/formatting 요구는 유지한다.
|
||||
- [ ] “agent profile 제거”와 “해당 전문 skill/검증 제거”를 혼동한 문장이 없는지 확인한다.
|
||||
|
||||
### Task 5: 통합 정적 확인과 인계
|
||||
|
||||
**Modify:** 앞선 10개 문서의 발견된 모순만 수정한다. 새 자동화·테스트 파일을 추가하지 않는다.
|
||||
|
||||
- [ ] AH-01은 AGENTS/AGENT_DESIGN/ARCHITECTURE, AH-02는 HARNESS/WORKFLOW, AH-03은 PRD/CODINGSTYLE, AH-04는 AGENT_DESIGN/SKILL_DESIGN, AH-05는 FEATURE_DOCUMENTATION/PRD에 반영됐는지 확인한다. 공통 근거는 ADR-028로 연결한다.
|
||||
- [ ] 아래 검색 결과를 현행 규칙, 폐기 안내, 과거 ADR 본문으로 분류한다. 폐기한 기능을 현행 의무로 설명하는 결과가 없어야 한다.
|
||||
- [ ] 변경 문서의 상대 링크·절 링크·agent/skill 이름·CLI·preset 값을 확인한다. 삭제된 profile/hook 경로는 현재 파일 링크로 두지 않는다.
|
||||
- [ ] root AGENTS의 byte 크기를 확인한다. 내용을 줄이되 필수 FESA 계약을 제거하여 분량만 맞추지 않는다.
|
||||
- [ ] 최종 diff가 요청한 10개 문서에 한정되는지 확인하고 기존 사용자 변경은 보존한다. 문서 정합성과 미실행 검사를 구분하여 보고한다.
|
||||
|
||||
정적 검색·diff 예시(PowerShell, 저장소 루트):
|
||||
|
||||
```powershell
|
||||
$docTargets = @(
|
||||
'AGENTS.md', 'docs/ADR.md', 'docs/ARCHITECTURE.md', 'docs/PRD.md',
|
||||
'docs/SOLVER_AGENT_DESIGN.md', 'docs/SOLVER_SKILL_DESIGN.md',
|
||||
'docs/HARNESS_WORKFLOW.md', 'docs/HARNESS.md', 'docs/CODINGSTYLE.md',
|
||||
'docs/FEATURE_DOCUMENTATION.md'
|
||||
)
|
||||
rg -n 'coordinator-agent|implementation-planning-agent|correction-agent|release-agent|xhigh|coordination\.md|owned_paths|attempt_history|retry_key|PreToolUse|Stop|hooks\.json|FEM_HARNESS_CODEX_SANDBOX|approve-danger-full-access|--push|9개|정규 stage' @docTargets
|
||||
rg -n 'execute\.py|GEN-010|GEN-012|ADR-028|medium|high|reference|TOLERANCE' @docTargets
|
||||
git diff --check -- $docTargets
|
||||
git diff --stat -- $docTargets
|
||||
git diff -- $docTargets
|
||||
(Get-Item -LiteralPath 'AGENTS.md').Length
|
||||
```
|
||||
|
||||
검색어를 전부 없애는 것이 합격 조건은 아니다. ADR 이력과 명시적인 폐기 안내는 허용하며, solver의 해석 step/state/retry 의미를 개발 phase와 혼동하여 삭제하지 않는다. UTF-8과 기존 개행을 보존하며 링크와 의미는 사람이 함께 확인한다. 자동 문자열·heading 맞춤 테스트를 만들지 않는다.
|
||||
|
||||
## 7. 범위 밖 후속 정합성 항목
|
||||
|
||||
다음은 현재 파일을 읽어 확인한 불일치다. 테스트를 실행하여 얻은 실패 결과는 아니며, 이번 문서 수정의 코드/테스트 작업으로 편입하지 않는다.
|
||||
|
||||
| 파일 | 현재 남아 있는 기대 | 후속 작업의 방향 |
|
||||
| --- | --- | --- |
|
||||
| [tests/test_execute.py](../../../tests/test_execute.py), [tests/test_execute_ownership.py](../../../tests/test_execute_ownership.py) | 삭제된 `StepExecutor`, phase·Git·owned_paths·retry 처리 | 별도 구현 작업에서 새 runner의 성공·실패·timeout·Git 무변경 동작에 맞는 coverage로 정리 |
|
||||
| [tests/test_hook_validation_scope.py](../../../tests/test_hook_validation_scope.py) | 삭제된 `scripts.hooks` import와 Stop 동작 | 폐기된 hook 검사와 유지할 실행기 검증을 구분 |
|
||||
| [tests/test_agent_skill_workflow_contract.py](../../../tests/test_agent_skill_workflow_contract.py) | 전용 Coordinator, 9단계, `xhigh`, phase 예시 preflight | 실제 7개 profile과 조건부 skill 계약에 맞추되 문구 강제를 새로운 합격 기준으로 만들지 않음 |
|
||||
| [tests/test_harness_preset_contract.py](../../../tests/test_harness_preset_contract.py) | tracked config 예시가 Ninja preset 필드를 모두 포함한다고 기대 | 간소화된 예시와 FESA 명시 preset 지원을 구분하여 검증 |
|
||||
|
||||
문서 10개를 갱신하는 일은 이 불일치의 해결과 별개로 완료할 수 있다. 다만 저장소 전체 Python 검사, 실제 C++ build/test, 수치/reference 검증이 통과했다고 보고할 수는 없다. 이번 계획과 후속 문서 작업에는 이 실행들을 포함하지 않는다.
|
||||
|
||||
## 8. AGENTS.md Quality Report
|
||||
|
||||
### Summary
|
||||
|
||||
- Files found: `AGENTS.md`, `docs2/AGENTS.md`의 2개. 수정·평가 대상은 요청된 루트 파일 1개다.
|
||||
- Active project chain at `C:/git/FESADev`: `AGENTS.md`. 프로젝트 내 override는 발견되지 않았다.
|
||||
- `docs2/AGENTS.md`는 별도 subtree에만 적용되는 참고 자료다. 루트 체인에 합산하지 않으며 전역 사용자 지침은 이번 audit 범위 밖이다.
|
||||
- Average score: **60/100**. Files needing update in scope: **1**.
|
||||
- Combined selected project-chain size: **24,487 bytes**; 기본 비교 한도 32 KiB 이내다. 전역 지침을 포함한 runtime 실제 주입량을 측정한 값은 아니다.
|
||||
|
||||
### File-by-File Assessment
|
||||
|
||||
#### 1. AGENTS.md (project root; active)
|
||||
|
||||
**Score: 60/100 (Grade: C)**. 점수는 문서 정합성 평가이며 솔버 품질 평가가 아니다.
|
||||
|
||||
| Criterion | Score | Evidence |
|
||||
| --- | ---: | --- |
|
||||
| Commands and workflows | 10/20 | CMake/CTest 진입점은 남아 있으나 phase CLI·hook·전용 Coordinator workflow는 현재 구현과 다름 |
|
||||
| Repository map and instruction scope | 15/20 | FESA runtime/Feature 경계는 유효하나 삭제한 profile·hook 경로를 현행 지침으로 참조 |
|
||||
| Non-obvious constraints and gotchas | 15/15 | Source identity, 수치/물리 검증, reference 무결성, state·HDF5 보존의 구체적 제약 유지 |
|
||||
| Conciseness and duplication | 5/15 | stage·handoff·retry·hook의 상세 의무를 여러 전담 문서와 중복 유지 |
|
||||
| Currency against the codebase | 5/15 | 7개 profile·medium/high·인자 없는 runner·hook 삭제를 아직 반영하지 않음 |
|
||||
| Actionability and verifiability | 10/15 | 검증 명령과 경계는 구체적이나 현재 수행할 수 없는 절차를 의무화 |
|
||||
|
||||
**Issues:** 삭제된 운영 기능을 요구하고, 간소화된 skill보다 더 강한 상태기계·파일명 TDD·전체 검증 반복을 지시한다.
|
||||
|
||||
**Recommended changes:** §3의 AGENTS 수정 범위만 반영한다. 상세 기술·수치 규칙은 유지하고 전담 문서와의 중복 운영 설명을 줄인다.
|
||||
|
||||
### Update: AGENTS.md
|
||||
|
||||
**Why:** AH-01~05와 실제 profile/runner/skill에 맞게 현행 지침을 바꾼다. 아래는 핵심 문구의 제안 diff이며 전체 적용 범위는 §3·Task 4를 따른다. 이 계획 작성 중에는 적용하지 않는다.
|
||||
|
||||
```diff
|
||||
- CRITICAL: 새 기능 또는 동작 변경은 테스트를 먼저 작성하고 실패를 확인한 뒤 구현한다.
|
||||
- CRITICAL: C++ production file을 바꿀 때는 관련 C++ test file이 있어야 한다.
|
||||
+ 동작 추가·수정은 해당 동작을 확인하는 테스트로 검증한다. 버그는 가능한 경우 실패를 재현한 뒤 최소 수정한다.
|
||||
+ 기존 coverage가 충분한 rename·refactor나 문서 수정에는 형식적인 새 테스트를 요구하지 않는다.
|
||||
```
|
||||
|
||||
```diff
|
||||
- Codex custom agent의 `model_reasoning_effort`는 `xhigh`이며, 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
|
||||
+ 일반 specialist의 기본 추론 강도는 `medium`, 정식화·수치·물리 검토는 `high`다. 모델과 역할별 설정은 [.codex/agents](.codex/agents)의 현재 profile을 따른다.
|
||||
```
|
||||
|
||||
```diff
|
||||
- 기능 개발은 아래 `Agent/Skill Workflow`의 9개 정규 stage를 순서대로 통과한다.
|
||||
+ 메인 assistant가 범위를 파악하고 필요한 전문 작업만 위임하며 구현·검증·결과 확인을 조정한다.
|
||||
+ 수식·요소·재료·적분·상태 갱신 변경의 독립 numerical review와 필요한 analytical/invariant·reference 검증은 유지한다.
|
||||
+ 변경 중에는 관련 검사를, 솔버 기능 완료 시에는 구성된 전체 build/test와 필수 reference 비교를 한 번 수행한다. 이후 변경·실패가 없으면 반복하지 않는다.
|
||||
```
|
||||
|
||||
```diff
|
||||
- python scripts/execute.py <phase-dir>
|
||||
+ python scripts/execute.py
|
||||
```
|
||||
|
||||
새 CLI 한 줄 교체만으로 완료하지 않는다. 기존 phase 인자·push·sandbox·hook 설명을 §5에 맞게 함께 갱신하고, 관리 문서 표에서 신규 `coordination.md` 요구를 제거하여 PRD checklist로 연결한다.
|
||||
|
||||
## 9. 최종 산출물과 완료 기준
|
||||
|
||||
- 요청된 문서 10개의 검토 가능한 diff와 ADR-028의 명확한 대체 관계.
|
||||
- 현재 역할·skill·CLI·설정·검증 시점이 일치하고 폐기 기능을 현행 필수 절차로 요구하지 않음.
|
||||
- FESA 제품·수치·입출력·코딩 계약과 필요한 독립 검증이 보존됨.
|
||||
- 상대 링크·소스 대조·diff/공백 검사를 정적으로 확인하고, 과거 evidence와 현재 미실행 항목을 구분해 보고함.
|
||||
- 사용자 구현 변경·테스트·개인 설정·기존 phase/Feature 이력은 보존됨. 저장소 전체 검증 완료나 commit/push 완료로 확대하여 보고하지 않음.
|
||||
+45
-1385
File diff suppressed because it is too large
Load Diff
@@ -1,158 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Codex PreToolUse 정책: 위험 명령과 테스트 없는 구현 파일 수정을 차단한다."""
|
||||
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
SCRIPTS_DIR = Path(__file__).resolve().parents[1]
|
||||
if str(SCRIPTS_DIR) not in sys.path:
|
||||
sys.path.insert(0, str(SCRIPTS_DIR))
|
||||
|
||||
from msvc_harness.config import ConfigError, load_config
|
||||
from msvc_harness.tdd_policy import CPP_SUFFIXES, evaluate_paths
|
||||
from hooks.validation_scope import EDIT_TOOL_NAMES, record_edit_scope
|
||||
|
||||
|
||||
DANGEROUS_PATTERNS = (
|
||||
re.compile(r"\bgit\s+reset\s+--hard\b", re.IGNORECASE),
|
||||
re.compile(r"\bgit\s+push\b[^\n]*--force(?:-with-lease)?\b", re.IGNORECASE),
|
||||
re.compile(r"\brm\s+-rf\b", re.IGNORECASE),
|
||||
re.compile(
|
||||
r"\bRemove-Item\b(?=[^\n]*-Recurse\b)(?=[^\n]*-Force\b)",
|
||||
re.IGNORECASE,
|
||||
),
|
||||
re.compile(
|
||||
r"\b(?:rmdir|rd)\b(?=[^\n]*/s\b)(?=[^\n]*/q\b)",
|
||||
re.IGNORECASE,
|
||||
),
|
||||
re.compile(r"\bDROP\s+TABLE\b", re.IGNORECASE),
|
||||
)
|
||||
EXECUTOR_OWNED_GIT = re.compile(
|
||||
r"\bgit(?:\.exe)?\b[^\r\n;&|]*\b(?:commit|push|switch|checkout|branch|tag|"
|
||||
r"merge|rebase|reset|cherry-pick|revert|stash|clean|update-ref|symbolic-ref|"
|
||||
r"worktree|fetch|pull)\b",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
PATCH_PATH = re.compile(
|
||||
r"^\*\*\* (?:(?:Add|Update|Delete) File:|Move to:) (?P<path>.+?)\s*$",
|
||||
re.MULTILINE,
|
||||
)
|
||||
|
||||
|
||||
class HookInputError(ValueError):
|
||||
pass
|
||||
|
||||
|
||||
def _tool_input(payload: dict[str, Any]) -> dict[str, Any]:
|
||||
value = payload.get("tool_input")
|
||||
if not isinstance(value, dict):
|
||||
raise HookInputError("hook tool_input must be an object")
|
||||
return value
|
||||
|
||||
|
||||
def _candidate_paths(payload: dict[str, Any], root: Path) -> list[Path]:
|
||||
tool_input = _tool_input(payload)
|
||||
raw_paths: list[str] = []
|
||||
for key in ("path", "file_path"):
|
||||
value = tool_input.get(key)
|
||||
if isinstance(value, str) and value.strip():
|
||||
raw_paths.append(value.strip())
|
||||
|
||||
edits = tool_input.get("edits")
|
||||
if isinstance(edits, list):
|
||||
for edit in edits:
|
||||
if not isinstance(edit, dict):
|
||||
continue
|
||||
value = edit.get("path")
|
||||
if isinstance(value, str) and value.strip():
|
||||
raw_paths.append(value.strip())
|
||||
|
||||
for key in ("command", "patch", "input"):
|
||||
value = tool_input.get(key)
|
||||
if isinstance(value, str):
|
||||
raw_paths.extend(match.group("path") for match in PATCH_PATH.finditer(value))
|
||||
|
||||
paths: list[Path] = []
|
||||
for raw_path in raw_paths:
|
||||
path = Path(raw_path)
|
||||
paths.append(path.resolve() if path.is_absolute() else (root / path).resolve())
|
||||
return list(dict.fromkeys(paths))
|
||||
|
||||
|
||||
def evaluate(payload: dict[str, Any], root: Path) -> str | None:
|
||||
"""Return a blocking reason, or None when the tool call is allowed."""
|
||||
tool_name = payload.get("tool_name")
|
||||
if not isinstance(tool_name, str) or not tool_name:
|
||||
raise HookInputError("hook tool_name must be a non-empty string")
|
||||
tool_input = _tool_input(payload)
|
||||
|
||||
if tool_name in {"Bash", "shell_command", "PowerShell"}:
|
||||
command = tool_input.get("command")
|
||||
if not isinstance(command, str):
|
||||
raise HookInputError("shell tool_input.command must be a string")
|
||||
if EXECUTOR_OWNED_GIT.search(command):
|
||||
return (
|
||||
"Harness-owned Git operation detected. The implementation session "
|
||||
"must leave branch, commit, push, and history operations to the Executor."
|
||||
)
|
||||
if any(
|
||||
pattern.search(command) for pattern in DANGEROUS_PATTERNS
|
||||
):
|
||||
return "위험한 명령어가 감지되어 실행을 차단했습니다."
|
||||
|
||||
if tool_name not in EDIT_TOOL_NAMES:
|
||||
return None
|
||||
|
||||
paths = _candidate_paths(payload, root)
|
||||
if not paths:
|
||||
raise HookInputError(
|
||||
f"{tool_name} input did not contain a path that can be checked"
|
||||
)
|
||||
try:
|
||||
config = load_config(root)
|
||||
except ConfigError as exc:
|
||||
if any(path.suffix.lower() in CPP_SUFFIXES for path in paths):
|
||||
return f"TDD GUARD: .harness/config.json must be repaired: {exc}"
|
||||
return None
|
||||
return evaluate_paths(paths, root, config.tdd)
|
||||
|
||||
|
||||
def main() -> int:
|
||||
try:
|
||||
payload = json.load(sys.stdin)
|
||||
if not isinstance(payload, dict):
|
||||
raise HookInputError("hook input must be a JSON object")
|
||||
cwd = payload.get("cwd")
|
||||
if cwd is not None and not isinstance(cwd, str):
|
||||
raise HookInputError("hook cwd must be a string")
|
||||
|
||||
root = Path(cwd or Path.cwd()).resolve()
|
||||
reason = evaluate(payload, root)
|
||||
except (
|
||||
json.JSONDecodeError,
|
||||
HookInputError,
|
||||
ConfigError,
|
||||
KeyError,
|
||||
ValueError,
|
||||
OSError,
|
||||
) as exc:
|
||||
print(f"TDD GUARD: hook input rejected: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
if reason:
|
||||
print(reason, file=sys.stderr)
|
||||
return 2
|
||||
if payload["tool_name"] in EDIT_TOOL_NAMES:
|
||||
try:
|
||||
record_edit_scope(payload, root, _candidate_paths(payload, root))
|
||||
except (ValueError, OSError) as exc:
|
||||
print(f"TDD GUARD: edit scope could not be recorded: {exc}", file=sys.stderr)
|
||||
return 2
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -1,168 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Codex Stop hook: validate discovered C/C++ projects with MSVC."""
|
||||
|
||||
import json
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
SCRIPTS = Path(__file__).resolve().parents[1]
|
||||
sys.path.insert(0, str(SCRIPTS))
|
||||
|
||||
from msvc_harness.adapters.base import AdapterError
|
||||
from msvc_harness.adapters.cmake import CMakeAdapter
|
||||
from msvc_harness.adapters.msbuild import MSBuildAdapter
|
||||
from msvc_harness.config import ConfigError, load_config
|
||||
from msvc_harness.discovery import DiscoveryError, discover_project
|
||||
from msvc_harness.models import ProjectKind
|
||||
from msvc_harness.process import ValidationFailure, execute_plan
|
||||
from msvc_harness.toolchain import ToolchainError, discover_toolchain
|
||||
from hooks.validation_scope import is_document_only_turn
|
||||
|
||||
|
||||
REENTRY_ENV = "CODEX_STOP_VALIDATION_ACTIVE"
|
||||
TOTAL_TIMEOUT_SECONDS = 7200
|
||||
|
||||
|
||||
def _remaining(deadline, clock, stage):
|
||||
remaining = deadline - clock()
|
||||
if remaining <= 0:
|
||||
raise ValidationFailure(f"{stage} timed out before it could start")
|
||||
return remaining
|
||||
|
||||
|
||||
def _project_root(
|
||||
cwd: Path,
|
||||
*,
|
||||
deadline: float,
|
||||
run=subprocess.run,
|
||||
clock=time.monotonic,
|
||||
) -> Path:
|
||||
argv = ["git", "rev-parse", "--show-toplevel"]
|
||||
resolved_cwd = cwd.resolve()
|
||||
try:
|
||||
result = run(
|
||||
argv,
|
||||
cwd=resolved_cwd,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
shell=False,
|
||||
timeout=_remaining(deadline, clock, "repository discovery"),
|
||||
)
|
||||
except subprocess.TimeoutExpired as exc:
|
||||
raise ValidationFailure(
|
||||
f"repository discovery timed out; argv={argv!r}; "
|
||||
f"cwd={str(resolved_cwd)!r}"
|
||||
) from exc
|
||||
if result.returncode == 0 and result.stdout.strip():
|
||||
return Path(result.stdout.strip()).resolve()
|
||||
return resolved_cwd
|
||||
|
||||
|
||||
def run_validations(
|
||||
root: Path,
|
||||
*,
|
||||
deadline: float | None = None,
|
||||
clock=time.monotonic,
|
||||
) -> tuple[bool, str]:
|
||||
"""Build and test a discovered C/C++ project, when one exists."""
|
||||
if deadline is None:
|
||||
deadline = clock() + TOTAL_TIMEOUT_SECONDS
|
||||
try:
|
||||
config = load_config(root)
|
||||
discovery = discover_project(root, config)
|
||||
if discovery.selection is None:
|
||||
return True, ""
|
||||
selection = discovery.selection
|
||||
tools = discover_toolchain(
|
||||
selection.kind,
|
||||
deadline=deadline,
|
||||
clock=clock,
|
||||
)
|
||||
adapter = (
|
||||
CMakeAdapter()
|
||||
if selection.kind is ProjectKind.CMAKE
|
||||
else MSBuildAdapter()
|
||||
)
|
||||
plan = adapter.create_plan(root, selection, config, tools)
|
||||
child_env = os.environ.copy()
|
||||
child_env[REENTRY_ENV] = "1"
|
||||
execute_plan(
|
||||
plan,
|
||||
root,
|
||||
env=child_env,
|
||||
deadline=deadline,
|
||||
clock=clock,
|
||||
)
|
||||
return True, ""
|
||||
except (
|
||||
ConfigError,
|
||||
DiscoveryError,
|
||||
ToolchainError,
|
||||
AdapterError,
|
||||
ValidationFailure,
|
||||
OSError,
|
||||
) as exc:
|
||||
return False, str(exc)
|
||||
|
||||
|
||||
def _emit_stop_response(message: str) -> None:
|
||||
print(
|
||||
json.dumps(
|
||||
{
|
||||
"decision": "block",
|
||||
"reason": message,
|
||||
},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def main(*, run=subprocess.run, clock=time.monotonic) -> int:
|
||||
if os.environ.get(REENTRY_ENV) == "1":
|
||||
return 0
|
||||
|
||||
try:
|
||||
raw_payload = sys.stdin.read()
|
||||
payload = json.loads(raw_payload) if raw_payload.strip() else {}
|
||||
if not isinstance(payload, dict):
|
||||
raise TypeError("hook input must be a JSON object")
|
||||
cwd = payload.get("cwd")
|
||||
if cwd is not None and not isinstance(cwd, str):
|
||||
raise TypeError("hook cwd must be a string")
|
||||
stop_hook_active = payload.get("stop_hook_active", False)
|
||||
if not isinstance(stop_hook_active, bool):
|
||||
raise TypeError("stop_hook_active must be a boolean")
|
||||
except (json.JSONDecodeError, TypeError) as exc:
|
||||
_emit_stop_response(f"validation hook input rejected: {exc}")
|
||||
return 0
|
||||
|
||||
if stop_hook_active:
|
||||
return 0
|
||||
|
||||
deadline = clock() + TOTAL_TIMEOUT_SECONDS
|
||||
try:
|
||||
root = _project_root(
|
||||
Path(cwd or Path.cwd()),
|
||||
deadline=deadline,
|
||||
run=run,
|
||||
clock=clock,
|
||||
)
|
||||
if is_document_only_turn(payload, root):
|
||||
return 0
|
||||
ok, message = run_validations(root, deadline=deadline, clock=clock)
|
||||
except Exception as exc:
|
||||
_emit_stop_response(f"validation hook failed: {exc}")
|
||||
return 0
|
||||
|
||||
if ok:
|
||||
return 0
|
||||
_emit_stop_response(message)
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
@@ -1,109 +0,0 @@
|
||||
"""Track whether a Codex turn edited Markdown files only."""
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
from pathlib import Path
|
||||
from typing import Any, Iterable
|
||||
|
||||
|
||||
EDIT_TOOL_NAMES = frozenset({"apply_patch", "Edit", "MultiEdit", "Write"})
|
||||
STATE_VERSION = 1
|
||||
|
||||
|
||||
def _identifier(payload: dict[str, Any], name: str) -> str | None:
|
||||
value = payload.get(name)
|
||||
if not isinstance(value, str) or not value.strip():
|
||||
return None
|
||||
return value
|
||||
|
||||
|
||||
def _digest(value: str) -> str:
|
||||
return hashlib.sha256(value.encode("utf-8")).hexdigest()
|
||||
|
||||
|
||||
def _state_path(root: Path, session_id: str) -> Path:
|
||||
return root / ".harness" / "hook-state" / f"{_digest(session_id)}.json"
|
||||
|
||||
|
||||
def _is_markdown_in_root(path: Path, root: Path) -> bool:
|
||||
resolved_root = root.resolve()
|
||||
resolved_path = path.resolve()
|
||||
try:
|
||||
resolved_path.relative_to(resolved_root)
|
||||
except ValueError:
|
||||
return False
|
||||
return resolved_path.suffix.lower() == ".md"
|
||||
|
||||
|
||||
def record_edit_scope(
|
||||
payload: dict[str, Any],
|
||||
root: Path,
|
||||
paths: Iterable[Path],
|
||||
) -> bool:
|
||||
"""Record an allowed edit; return False when turn identity is unavailable."""
|
||||
session_id = _identifier(payload, "session_id")
|
||||
turn_id = _identifier(payload, "turn_id")
|
||||
if session_id is None or turn_id is None:
|
||||
return False
|
||||
|
||||
edit_paths = list(paths)
|
||||
if not edit_paths:
|
||||
raise ValueError("edit scope requires at least one path")
|
||||
|
||||
turn_digest = _digest(turn_id)
|
||||
state_path = _state_path(root, session_id)
|
||||
document_only = all(
|
||||
_is_markdown_in_root(path, root) for path in edit_paths
|
||||
)
|
||||
|
||||
if state_path.is_file():
|
||||
try:
|
||||
previous = json.loads(state_path.read_text(encoding="utf-8"))
|
||||
valid_previous = (
|
||||
isinstance(previous, dict)
|
||||
and previous.get("version") == STATE_VERSION
|
||||
and isinstance(previous.get("turn"), str)
|
||||
and isinstance(previous.get("document_only"), bool)
|
||||
)
|
||||
if not valid_previous:
|
||||
document_only = False
|
||||
elif previous["turn"] == turn_digest:
|
||||
document_only = previous["document_only"] and document_only
|
||||
except (json.JSONDecodeError, OSError):
|
||||
document_only = False
|
||||
|
||||
state_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
temporary_path = state_path.with_suffix(".tmp")
|
||||
temporary_path.write_text(
|
||||
json.dumps(
|
||||
{
|
||||
"version": STATE_VERSION,
|
||||
"turn": turn_digest,
|
||||
"document_only": document_only,
|
||||
}
|
||||
),
|
||||
encoding="utf-8",
|
||||
)
|
||||
temporary_path.replace(state_path)
|
||||
return True
|
||||
|
||||
|
||||
def is_document_only_turn(payload: dict[str, Any], root: Path) -> bool:
|
||||
"""Return True only for a valid state proving Markdown-only edits."""
|
||||
session_id = _identifier(payload, "session_id")
|
||||
turn_id = _identifier(payload, "turn_id")
|
||||
if session_id is None or turn_id is None:
|
||||
return False
|
||||
|
||||
state_path = _state_path(root, session_id)
|
||||
try:
|
||||
state = json.loads(state_path.read_text(encoding="utf-8"))
|
||||
except (FileNotFoundError, json.JSONDecodeError, OSError):
|
||||
return False
|
||||
|
||||
return (
|
||||
isinstance(state, dict)
|
||||
and state.get("version") == STATE_VERSION
|
||||
and state.get("turn") == _digest(turn_id)
|
||||
and state.get("document_only") is True
|
||||
)
|
||||
@@ -1,16 +1,9 @@
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from string import Formatter
|
||||
from typing import Any
|
||||
|
||||
from .models import CMakeConfig, HarnessConfig, MSBuildConfig, TDDConfig
|
||||
|
||||
DEFAULT_TEST_PATTERNS = (
|
||||
"{stem}_test.cpp",
|
||||
"{stem}_tests.cpp",
|
||||
"test_{stem}.cpp",
|
||||
"{stem}.test.cpp",
|
||||
)
|
||||
from .models import CMakeConfig, HarnessConfig, MSBuildConfig
|
||||
|
||||
|
||||
class ConfigError(ValueError):
|
||||
@@ -60,38 +53,6 @@ def _string_array(value: Any, label: str) -> tuple[str, ...]:
|
||||
)
|
||||
|
||||
|
||||
def _validate_test_pattern(pattern: str) -> None:
|
||||
candidate = Path(pattern)
|
||||
if (
|
||||
candidate.is_absolute()
|
||||
or bool(candidate.drive)
|
||||
or "/" in pattern
|
||||
or "\\" in pattern
|
||||
or candidate.name != pattern
|
||||
):
|
||||
raise ConfigError(
|
||||
"every tdd.testPatterns entry must be a safe basename pattern"
|
||||
)
|
||||
try:
|
||||
fields = [
|
||||
(field_name, format_spec, conversion)
|
||||
for _, field_name, format_spec, conversion in Formatter().parse(pattern)
|
||||
if field_name is not None
|
||||
]
|
||||
except ValueError as exc:
|
||||
raise ConfigError(f"invalid tdd.testPatterns entry: {exc}") from exc
|
||||
if (
|
||||
not fields
|
||||
or any(
|
||||
field_name != "stem" or format_spec or conversion
|
||||
for field_name, format_spec, conversion in fields
|
||||
)
|
||||
):
|
||||
raise ConfigError(
|
||||
"every tdd.testPatterns entry may contain only the {stem} field"
|
||||
)
|
||||
|
||||
|
||||
def load_config(root: Path) -> HarnessConfig:
|
||||
root = root.resolve()
|
||||
config_path = root / ".harness" / "config.json"
|
||||
@@ -166,21 +127,12 @@ def load_config(root: Path) -> HarnessConfig:
|
||||
else None
|
||||
)
|
||||
|
||||
tdd_data = _mapping(data.get("tdd", {}), "tdd")
|
||||
_reject_unknown(tdd_data, {"testRoots", "testPatterns", "exclude"}, "tdd")
|
||||
raw_test_roots = _string_array(tdd_data["testRoots"], "tdd.testRoots") if "testRoots" in tdd_data else ("tests", "test")
|
||||
test_roots = tuple(_repo_path(root, item, "tdd.testRoots") for item in raw_test_roots)
|
||||
test_patterns = _string_array(tdd_data["testPatterns"], "tdd.testPatterns") if "testPatterns" in tdd_data else DEFAULT_TEST_PATTERNS
|
||||
for pattern in test_patterns:
|
||||
_validate_test_pattern(pattern)
|
||||
exclude = _string_array(tdd_data["exclude"], "tdd.exclude") if "exclude" in tdd_data else ()
|
||||
for item in exclude:
|
||||
_repo_path(root, item, "tdd.exclude")
|
||||
if "tdd" in data:
|
||||
print("Deprecated config field 'tdd' is ignored; it may be removed.", file=sys.stderr)
|
||||
|
||||
return HarnessConfig(
|
||||
version=1,
|
||||
project_type=project_type,
|
||||
cmake=CMakeConfig(source_dir, binary_dir, configure_preset, build_preset, test_preset),
|
||||
msbuild=MSBuildConfig(solution, configuration, platform, test_command),
|
||||
tdd=TDDConfig(test_roots, test_patterns, exclude),
|
||||
)
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
from pathlib import Path
|
||||
|
||||
from .models import DiscoveryResult, HarnessConfig, ProjectKind, ProjectSelection
|
||||
from .tdd_policy import find_cpp_files
|
||||
|
||||
|
||||
class DiscoveryError(RuntimeError):
|
||||
@@ -68,10 +67,4 @@ def discover_project(root: Path, config: HarnessConfig) -> DiscoveryResult:
|
||||
ProjectSelection(ProjectKind.MSBUILD, projects[0])
|
||||
)
|
||||
|
||||
cpp_files = find_cpp_files(root)
|
||||
if cpp_files:
|
||||
raise DiscoveryError(
|
||||
"C/C++ files exist but no CMakeLists.txt, preset, .sln, or .vcxproj "
|
||||
"was found; configure projectType and project path"
|
||||
)
|
||||
return DiscoveryResult(None, ())
|
||||
return DiscoveryResult(None)
|
||||
|
||||
@@ -30,20 +30,12 @@ class MSBuildConfig:
|
||||
test_command: tuple[str, ...] | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class TDDConfig:
|
||||
test_roots: tuple[Path, ...]
|
||||
test_patterns: tuple[str, ...]
|
||||
exclude: tuple[str, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class HarnessConfig:
|
||||
version: int
|
||||
project_type: str
|
||||
cmake: CMakeConfig
|
||||
msbuild: MSBuildConfig
|
||||
tdd: TDDConfig
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
@@ -55,7 +47,6 @@ class ProjectSelection:
|
||||
@dataclass(frozen=True)
|
||||
class DiscoveryResult:
|
||||
selection: ProjectSelection | None
|
||||
cpp_files: tuple[Path, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
|
||||
@@ -1,88 +0,0 @@
|
||||
from fnmatch import fnmatch
|
||||
from pathlib import Path
|
||||
|
||||
CPP_SUFFIXES = frozenset({".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".hxx"})
|
||||
DEFAULT_EXCLUDES = (
|
||||
".harness/build/**",
|
||||
"build/**",
|
||||
"out/**",
|
||||
"cmake-build-*/**",
|
||||
"third_party/**",
|
||||
"external/**",
|
||||
"vendor/**",
|
||||
"generated/**",
|
||||
)
|
||||
|
||||
|
||||
def is_excluded_path(path: Path, root: Path, extra: tuple[str, ...] = ()) -> bool:
|
||||
try:
|
||||
relative = path.resolve().relative_to(root.resolve()).as_posix()
|
||||
except ValueError:
|
||||
return False
|
||||
return any(fnmatch(relative, pattern) for pattern in DEFAULT_EXCLUDES + extra)
|
||||
|
||||
|
||||
def find_cpp_files(
|
||||
root: Path,
|
||||
extra_excludes: tuple[str, ...] = (),
|
||||
) -> tuple[Path, ...]:
|
||||
found = (
|
||||
path
|
||||
for path in root.resolve().rglob("*")
|
||||
if path.is_file()
|
||||
and path.suffix.lower() in CPP_SUFFIXES
|
||||
and not is_excluded_path(path, root, extra_excludes)
|
||||
)
|
||||
return tuple(sorted(found))
|
||||
|
||||
|
||||
def is_test_file(path: Path, root: Path, config) -> bool:
|
||||
resolved = path.resolve()
|
||||
if any(root == resolved or root in resolved.parents for root in config.test_roots):
|
||||
return True
|
||||
relative = resolved.relative_to(root.resolve())
|
||||
if {"test", "tests"} & {part.lower() for part in relative.parts}:
|
||||
return True
|
||||
stem = resolved.stem.lower()
|
||||
return stem.startswith("test_") or stem.endswith(("_test", "_tests", ".test"))
|
||||
|
||||
|
||||
def matching_test_exists(path: Path, config) -> bool:
|
||||
names = tuple(pattern.format(stem=path.stem) for pattern in config.test_patterns)
|
||||
roots = (
|
||||
*config.test_roots,
|
||||
path.parent / "tests",
|
||||
path.parent / "test",
|
||||
)
|
||||
for root in roots:
|
||||
if not root.is_dir():
|
||||
continue
|
||||
for name in names:
|
||||
if any(candidate.is_file() for candidate in root.rglob(name)):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def evaluate_paths(paths, root: Path, config) -> str | None:
|
||||
root = root.resolve()
|
||||
for raw in paths:
|
||||
path = raw.resolve()
|
||||
try:
|
||||
path.relative_to(root)
|
||||
except ValueError:
|
||||
return f"TDD GUARD: '{path}' is outside the repository"
|
||||
if path.suffix.lower() not in CPP_SUFFIXES:
|
||||
continue
|
||||
if (
|
||||
path.name.lower() == "main.cpp"
|
||||
or is_excluded_path(path, root, config.exclude)
|
||||
or is_test_file(path, root, config)
|
||||
):
|
||||
continue
|
||||
if not matching_test_exists(path, config):
|
||||
expected = config.test_patterns[0].format(stem=path.stem)
|
||||
return (
|
||||
f"TDD GUARD: '{path.name}' requires an existing test such as "
|
||||
f"'{expected}'. Add the test in a configured test root first."
|
||||
)
|
||||
return None
|
||||
Reference in New Issue
Block a user