From 42a4847da54b525ab62a746bee06525ad28aab4b Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Sun, 6 Sep 2026 21:49:07 +0900 Subject: [PATCH 1/3] fix: allow full validation time for shared Stop hook --- .codex/hooks.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.codex/hooks.json b/.codex/hooks.json index 598631c..1812703 100644 --- a/.codex/hooks.json +++ b/.codex/hooks.json @@ -22,7 +22,7 @@ "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": 1800, + "timeout": 7500, "statusMessage": "Running MSVC build and tests" } ] From d7e96296404f5b882b50affcb4941a15d05596dc Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Mon, 7 Sep 2026 01:15:26 +0900 Subject: [PATCH 2/3] update agent, skill and scripts --- .agents/skills/harness/SKILL.md | 172 +- .agents/skills/review/SKILL.md | 51 +- .codex/agents/coordinator-agent.toml | 64 - .codex/agents/correction-agent.toml | 41 - .codex/agents/formulation-agent.toml | 43 +- .codex/agents/implementation-agent.toml | 61 +- .../agents/implementation-planning-agent.toml | 45 - .codex/agents/io-definition-agent.toml | 45 +- .codex/agents/numerical-review-agent.toml | 52 +- .codex/agents/physics-evaluation-agent.toml | 45 +- .codex/agents/release-agent.toml | 38 - .codex/agents/requirement-agent.toml | 48 +- .codex/agents/research-agent.toml | 43 +- .codex/config.toml | 4 - .codex/hooks.json | 32 - .codex/skills/fem-formulation-spec/SKILL.md | 35 +- .codex/skills/fem-implementation-tdd/SKILL.md | 48 +- .../fem-implementation-tdd/agents/openai.yaml | 2 +- .../references/toolchain-and-verification.md | 33 +- .codex/skills/fem-io-contract/SKILL.md | 35 +- .codex/skills/fem-numerical-review/SKILL.md | 37 +- .codex/skills/fem-physics-review/SKILL.md | 34 +- .codex/skills/fem-release-readiness/SKILL.md | 35 +- .../fem-release-readiness/agents/openai.yaml | 2 +- .../skills/fem-requirements-baseline/SKILL.md | 34 +- .../references/evidence-and-handoff.md | 27 +- .../references/workflow-and-decisions.md | 6 +- .codex/skills/fem-research-evidence/SKILL.md | 34 +- .harness/config.example.json | 6 +- ...9-07-agent-harness-documentation-update.md | 282 ++++ scripts/execute.py | 1391 +---------------- scripts/hooks/pre_tool_use.py | 158 -- scripts/hooks/stop_validation.py | 168 -- scripts/hooks/validation_scope.py | 109 -- scripts/msvc_harness/config.py | 56 +- scripts/msvc_harness/discovery.py | 9 +- scripts/msvc_harness/models.py | 9 - scripts/msvc_harness/tdd_policy.py | 88 -- 38 files changed, 476 insertions(+), 2946 deletions(-) delete mode 100644 .codex/agents/coordinator-agent.toml delete mode 100644 .codex/agents/correction-agent.toml delete mode 100644 .codex/agents/implementation-planning-agent.toml delete mode 100644 .codex/agents/release-agent.toml delete mode 100644 .codex/config.toml delete mode 100644 .codex/hooks.json create mode 100644 docs/superpowers/plans/2026-09-07-agent-harness-documentation-update.md delete mode 100644 scripts/hooks/pre_tool_use.py delete mode 100644 scripts/hooks/stop_validation.py delete mode 100644 scripts/hooks/validation_scope.py delete mode 100644 scripts/msvc_harness/tdd_policy.py diff --git a/.agents/skills/harness/SKILL.md b/.agents/skills/harness/SKILL.md index 2d23818..5e34edf 100644 --- a/.agents/skills/harness/SKILL.md +++ b/.agents/skills/harness/SKILL.md @@ -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//index.json -phases//step0.md -phases//step1.md -... -``` - -The top-level entry is: - -```json -{"dir": "", "status": "pending"} -``` - -The phase index is: - -```json -{ - "project": "", - "phase": "", - "steps": [ - { - "step": 0, "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 +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 --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 --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. diff --git a/.agents/skills/review/SKILL.md b/.agents/skills/review/SKILL.md index 82b4e05..29d2660 100644 --- a/.agents/skills/review/SKILL.md +++ b/.agents/skills/review/SKILL.md @@ -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. diff --git a/.codex/agents/coordinator-agent.toml b/.codex/agents/coordinator-agent.toml deleted file mode 100644 index bffc85e..0000000 --- a/.codex/agents/coordinator-agent.toml +++ /dev/null @@ -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// layout for feature work. - -Owned work: -- On requirements intake, assign a stable feature_id and create `docs//` 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. -""" diff --git a/.codex/agents/correction-agent.toml b/.codex/agents/correction-agent.toml deleted file mode 100644 index 1c2c042..0000000 --- a/.codex/agents/correction-agent.toml +++ /dev/null @@ -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//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. -""" diff --git a/.codex/agents/formulation-agent.toml b/.codex/agents/formulation-agent.toml index 38b2398..a715aa5 100644 --- a/.codex/agents/formulation-agent.toml +++ b/.codex/agents/formulation-agent.toml @@ -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//`; 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//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. """ diff --git a/.codex/agents/implementation-agent.toml b/.codex/agents/implementation-agent.toml index 9f82acc..1bfeb71 100644 --- a/.codex/agents/implementation-agent.toml +++ b/.codex/agents/implementation-agent.toml @@ -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//`; 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//`. -- 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. """ diff --git a/.codex/agents/implementation-planning-agent.toml b/.codex/agents/implementation-planning-agent.toml deleted file mode 100644 index 08d1711..0000000 --- a/.codex/agents/implementation-planning-agent.toml +++ /dev/null @@ -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//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. -""" diff --git a/.codex/agents/io-definition-agent.toml b/.codex/agents/io-definition-agent.toml index 1dc3da6..e8fd1fa 100644 --- a/.codex/agents/io-definition-agent.toml +++ b/.codex/agents/io-definition-agent.toml @@ -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//`; 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//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. """ diff --git a/.codex/agents/numerical-review-agent.toml b/.codex/agents/numerical-review-agent.toml index cc4e774..a786ed3 100644 --- a/.codex/agents/numerical-review-agent.toml +++ b/.codex/agents/numerical-review-agent.toml @@ -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//`; 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//numerical-review.md` and - `docs//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. """ diff --git a/.codex/agents/physics-evaluation-agent.toml b/.codex/agents/physics-evaluation-agent.toml index af747ac..8228110 100644 --- a/.codex/agents/physics-evaluation-agent.toml +++ b/.codex/agents/physics-evaluation-agent.toml @@ -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//`; 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//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. """ diff --git a/.codex/agents/release-agent.toml b/.codex/agents/release-agent.toml deleted file mode 100644 index 0ae6f94..0000000 --- a/.codex/agents/release-agent.toml +++ /dev/null @@ -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//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. -""" diff --git a/.codex/agents/requirement-agent.toml b/.codex/agents/requirement-agent.toml index 120d26f..fc98ddb 100644 --- a/.codex/agents/requirement-agent.toml +++ b/.codex/agents/requirement-agent.toml @@ -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//`; 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//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--###` 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. """ diff --git a/.codex/agents/research-agent.toml b/.codex/agents/research-agent.toml index 0f5e6a8..6a100f8 100644 --- a/.codex/agents/research-agent.toml +++ b/.codex/agents/research-agent.toml @@ -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//`; 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//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. """ diff --git a/.codex/config.toml b/.codex/config.toml deleted file mode 100644 index 151b8b6..0000000 --- a/.codex/config.toml +++ /dev/null @@ -1,4 +0,0 @@ -#:schema https://developers.openai.com/codex/config-schema.json - -[features] -hooks = true diff --git a/.codex/hooks.json b/.codex/hooks.json deleted file mode 100644 index 1812703..0000000 --- a/.codex/hooks.json +++ /dev/null @@ -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" - } - ] - } - ] - } -} diff --git a/.codex/skills/fem-formulation-spec/SKILL.md b/.codex/skills/fem-formulation-spec/SKILL.md index 726b2d0..f4166c0 100644 --- a/.codex/skills/fem-formulation-spec/SKILL.md +++ b/.codex/skills/fem-formulation-spec/SKILL.md @@ -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//requirements.md` -- `docs//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//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. diff --git a/.codex/skills/fem-implementation-tdd/SKILL.md b/.codex/skills/fem-implementation-tdd/SKILL.md index a8d23fa..52670fd 100644 --- a/.codex/skills/fem-implementation-tdd/SKILL.md +++ b/.codex/skills/fem-implementation-tdd/SKILL.md @@ -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//implementation-plan.md` -- `docs//implementation-report.md` -- `docs//build-test.md` -- `docs//reference-comparison.md` -- `docs//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. diff --git a/.codex/skills/fem-implementation-tdd/agents/openai.yaml b/.codex/skills/fem-implementation-tdd/agents/openai.yaml index 2772b1d..4401f03 100644 --- a/.codex/skills/fem-implementation-tdd/agents/openai.yaml +++ b/.codex/skills/fem-implementation-tdd/agents/openai.yaml @@ -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." diff --git a/.codex/skills/fem-implementation-tdd/references/toolchain-and-verification.md b/.codex/skills/fem-implementation-tdd/references/toolchain-and-verification.md index 945999a..74da54a 100644 --- a/.codex/skills/fem-implementation-tdd/references/toolchain-and-verification.md +++ b/.codex/skills/fem-implementation-tdd/references/toolchain-and-verification.md @@ -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. diff --git a/.codex/skills/fem-io-contract/SKILL.md b/.codex/skills/fem-io-contract/SKILL.md index e15b9f5..053029b 100644 --- a/.codex/skills/fem-io-contract/SKILL.md +++ b/.codex/skills/fem-io-contract/SKILL.md @@ -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//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. diff --git a/.codex/skills/fem-numerical-review/SKILL.md b/.codex/skills/fem-numerical-review/SKILL.md index f54c542..75ce632 100644 --- a/.codex/skills/fem-numerical-review/SKILL.md +++ b/.codex/skills/fem-numerical-review/SKILL.md @@ -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//numerical-review.md`: verdict, findings, risks, consistency checks, verification readiness, required revisions, and handoff. -- `docs//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. diff --git a/.codex/skills/fem-physics-review/SKILL.md b/.codex/skills/fem-physics-review/SKILL.md index 7bd0619..70c5670 100644 --- a/.codex/skills/fem-physics-review/SKILL.md +++ b/.codex/skills/fem-physics-review/SKILL.md @@ -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//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. diff --git a/.codex/skills/fem-release-readiness/SKILL.md b/.codex/skills/fem-release-readiness/SKILL.md index 7eb9b21..d0347e4 100644 --- a/.codex/skills/fem-release-readiness/SKILL.md +++ b/.codex/skills/fem-release-readiness/SKILL.md @@ -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//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. diff --git a/.codex/skills/fem-release-readiness/agents/openai.yaml b/.codex/skills/fem-release-readiness/agents/openai.yaml index 1ca513a..52b64dd 100644 --- a/.codex/skills/fem-release-readiness/agents/openai.yaml +++ b/.codex/skills/fem-release-readiness/agents/openai.yaml @@ -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." diff --git a/.codex/skills/fem-requirements-baseline/SKILL.md b/.codex/skills/fem-requirements-baseline/SKILL.md index af7d1b2..9c7d9d9 100644 --- a/.codex/skills/fem-requirements-baseline/SKILL.md +++ b/.codex/skills/fem-requirements-baseline/SKILL.md @@ -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--###` 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//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. diff --git a/.codex/skills/fem-requirements-baseline/references/evidence-and-handoff.md b/.codex/skills/fem-requirements-baseline/references/evidence-and-handoff.md index 30e628e..23d1be2 100644 --- a/.codex/skills/fem-requirements-baseline/references/evidence-and-handoff.md +++ b/.codex/skills/fem-requirements-baseline/references/evidence-and-handoff.md @@ -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` | `\|\|\|`, 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. diff --git a/.codex/skills/fem-requirements-baseline/references/workflow-and-decisions.md b/.codex/skills/fem-requirements-baseline/references/workflow-and-decisions.md index de23753..7925aa0 100644 --- a/.codex/skills/fem-requirements-baseline/references/workflow-and-decisions.md +++ b/.codex/skills/fem-requirements-baseline/references/workflow-and-decisions.md @@ -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. diff --git a/.codex/skills/fem-research-evidence/SKILL.md b/.codex/skills/fem-research-evidence/SKILL.md index 3b43933..d226c39 100644 --- a/.codex/skills/fem-research-evidence/SKILL.md +++ b/.codex/skills/fem-research-evidence/SKILL.md @@ -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//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//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. diff --git a/.harness/config.example.json b/.harness/config.example.json index b8853ea..da2402e 100644 --- a/.harness/config.example.json +++ b/.harness/config.example.json @@ -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": "." } } diff --git a/docs/superpowers/plans/2026-09-07-agent-harness-documentation-update.md b/docs/superpowers/plans/2026-09-07-agent-harness-documentation-update.md new file mode 100644 index 0000000..331323f --- /dev/null +++ b/docs/superpowers/plans/2026-09-07-agent-harness-documentation-update.md @@ -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 `_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 | +| ์˜› ``, `--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 ++ 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 ์™„๋ฃŒ๋กœ ํ™•๋Œ€ํ•˜์—ฌ ๋ณด๊ณ ํ•˜์ง€ ์•Š์Œ. diff --git a/scripts/execute.py b/scripts/execute.py index f4a33f7..3b04fa2 100644 --- a/scripts/execute.py +++ b/scripts/execute.py @@ -1,1360 +1,59 @@ #!/usr/bin/env python3 -""" -Harness Step Executor โ€” phase ๋‚ด Step์„ ์ˆœ์ฐจ ์‹คํ–‰ํ•˜๊ณ  ๊ฒฐ๊ณผ์™€ ํŒŒ์ผ ์†Œ์œ ๊ถŒ์„ ๊ฒ€์ฆํ•œ๋‹ค. - -Usage: - python scripts/execute.py [--push] -""" +"""Run the configured C/C++ build and tests once: python scripts/execute.py.""" import argparse -import contextlib -import json -import os -import re -import subprocess import sys -import tempfile -import threading import time -import types -from datetime import datetime, timezone, timedelta -from pathlib import Path, PureWindowsPath -from typing import Optional +from pathlib import Path -ROOT = Path(__file__).resolve().parent.parent +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 -class HarnessError(RuntimeError): - """Executor๊ฐ€ ์•ˆ์ „ํ•˜๊ฒŒ ๊ณ„์†ํ•  ์ˆ˜ ์—†๋Š” ๊ฒ€์ฆ ๋˜๋Š” ์‹คํ–‰ ์˜ค๋ฅ˜.""" +ROOT = Path(__file__).resolve().parents[1] -class CodexEnvironmentError(HarnessError): - """์žฌ์‹œ๋„๋กœ ํ•ด๊ฒฐํ•  ์ˆ˜ ์—†๋Š” Codex CLI ํ™˜๊ฒฝ ์˜ค๋ฅ˜.""" - - -class StepOwnershipError(HarnessError): - """์Šน์ธ๋œ Step ํŒŒ์ผ ๋ฒ”์œ„ ๋ฐ–์˜ ๋ณ€๊ฒฝ; ์‚ฌ์šฉ์ž ๋ฐ์ดํ„ฐ๋ฅผ ๋˜๋Œ๋ฆฌ์ง€ ์•Š๋Š”๋‹ค.""" - - -def _configure_utf8_stdio(): - """Windows ์ฝ˜์†”์—์„œ๋„ Harness ์ง„ํ–‰ ๋ฌธ์ž๋ฅผ ์•ˆ์ •์ ์œผ๋กœ ์ถœ๋ ฅํ•œ๋‹ค.""" - for stream in (sys.stdout, sys.stderr): - reconfigure = getattr(stream, "reconfigure", None) - if reconfigure is not None: - reconfigure(encoding="utf-8") - - -@contextlib.contextmanager -def progress_indicator(label: str): - """ํ„ฐ๋ฏธ๋„ ์ง„ํ–‰ ํ‘œ์‹œ๊ธฐ. with ๋ฌธ์œผ๋กœ ์‚ฌ์šฉํ•˜๋ฉฐ .elapsed ๋กœ ๊ฒฝ๊ณผ ์‹œ๊ฐ„์„ ์ฝ๋Š”๋‹ค.""" - frames = "โ—โ—“โ—‘โ—’" - stop = threading.Event() - t0 = time.monotonic() - - def _animate(): - idx = 0 - while not stop.wait(0.12): - sec = int(time.monotonic() - t0) - sys.stderr.write(f"\r{frames[idx % len(frames)]} {label} [{sec}s]") - sys.stderr.flush() - idx += 1 - sys.stderr.write("\r" + " " * (len(label) + 20) + "\r") - sys.stderr.flush() - - th = threading.Thread(target=_animate, daemon=True) - th.start() - info = types.SimpleNamespace(elapsed=0.0) +def run_validations(root: Path) -> int: + deadline = time.monotonic() + 1800 try: - yield info - finally: - stop.set() - th.join() - info.elapsed = time.monotonic() - t0 - - -class StepExecutor: - """Phase ๋””๋ ‰ํ† ๋ฆฌ ์•ˆ์˜ step๋“ค์„ ์ˆœ์ฐจ ์‹คํ–‰ํ•˜๋Š” ํ•˜๋„ค์Šค.""" - - MAX_TRANSPORT_ATTEMPTS = 2 - CODEX_TIMEOUT_SECONDS = 1800 - CODEX_SANDBOX_ENV = "FEM_HARNESS_CODEX_SANDBOX" - CODEX_SANDBOX_MODES = frozenset({"workspace-write", "danger-full-access"}) - PHASE_NAME = re.compile(r"^[a-z0-9]+(?:[._-][a-z0-9]+)*$") - STEP_NAME = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$") - STEP_STATUSES = frozenset({"pending", "completed", "error", "blocked"}) - AGENT_STEP_FIELDS = frozenset( - {"status", "summary", "error_message", "blocked_reason"} - ) - IMPLEMENTATION_AGENT_PROFILE = Path( - ".codex/agents/implementation-agent.toml" - ) - FEAT_MSG = "feat({phase}): step {num} - {name}" - CHORE_MSG = "chore({phase}): step {num} output" - TZ = timezone(timedelta(hours=9)) - - def __init__( - self, - phase_dir_name: str, - *, - auto_push: bool = False, - danger_full_access_approved: bool = False, - ): - if not isinstance(phase_dir_name, str) or not self.PHASE_NAME.fullmatch( - phase_dir_name - ): - raise HarnessError( - "phase directory must be one safe repository-relative name" - ) - root_path = ROOT.resolve() - self._root = str(root_path) - self._phases_dir = (root_path / "phases").resolve() - try: - self._phases_dir.relative_to(root_path) - except ValueError as exc: - raise HarnessError( - "phases directory must resolve inside the Harness repository root" - ) from exc - self._phase_dir = (self._phases_dir / phase_dir_name).resolve() - try: - self._phase_dir.relative_to(self._phases_dir.resolve()) - except ValueError as exc: - raise HarnessError( - "phase directory must stay inside the repository phases directory" - ) from exc - self._phase_dir_name = phase_dir_name - self._top_index_file = self._phases_dir / "index.json" - self._auto_push = auto_push - self._danger_full_access_approved = danger_full_access_approved - self._validated_sandbox_mode: str | None = None - self._implementation_profile_cache: tuple[str, str, str] | None = None - - if not self._phase_dir.is_dir(): - raise HarnessError(f"phase directory not found: {self._phase_dir}") - - self._index_file = self._phase_dir / "index.json" - if not self._index_file.exists(): - raise HarnessError(f"phase index not found: {self._index_file}") - if not self._top_index_file.is_file(): - raise HarnessError( - f"top-level phase index not found: {self._top_index_file}" - ) - - self._read_top_index() - idx = self._read_phase_index() - self._project = idx["project"] - self._phase_name = idx["phase"] - self._total = len(idx["steps"]) - - def run(self): - self._print_header() - self._check_blockers() - self._preflight_repository() - self._checkout_branch() - guardrails = self._load_guardrails() - self._ensure_created_at() - self._execute_all_steps(guardrails) - self._finalize() - - # --- timestamps --- - - def _stamp(self) -> str: - return datetime.now(self.TZ).strftime("%Y-%m-%dT%H:%M:%S%z") - - # --- JSON I/O --- - - def _control_scope(self, path: Path) -> Path: - if path == self._top_index_file: - return self._phases_dir - try: - path.relative_to(self._phase_dir) - except ValueError as exc: - raise HarnessError( - f"control path is outside the selected phase: {path}" - ) from exc - return self._phase_dir - - def _validate_control_parent(self, path: Path, scope: Path) -> None: - root = Path(self._root) - try: - resolved_scope = scope.resolve(strict=True) - resolved_scope.relative_to(root) - path.parent.resolve(strict=True).relative_to(resolved_scope) - except (OSError, ValueError) as exc: - raise HarnessError( - f"control path parent escapes its trusted scope: {path}" - ) from exc - - def _read_control_bytes(self, path: Path) -> bytes: - scope = self._control_scope(path) - self._validate_control_parent(path, scope) - try: - metadata = path.lstat() - resolved = path.resolve(strict=True) - resolved.relative_to(scope.resolve(strict=True)) - except (OSError, ValueError) as exc: - raise HarnessError( - f"protected control file is missing or escapes its scope: {path}" - ) from exc - if path.is_symlink() or not path.is_file() or metadata.st_nlink != 1: - raise HarnessError( - f"protected control file must be a non-link regular file: {path}" - ) - try: - return path.read_bytes() - except OSError as exc: - raise HarnessError( - f"protected control file could not be read: {path}: {exc}" - ) from exc - - def _atomic_write_control_bytes(self, path: Path, contents: bytes) -> None: - scope = self._control_scope(path) - self._validate_control_parent(path, scope) - if path.exists() and not path.is_symlink() and not path.is_file(): - raise HarnessError( - f"control output path is not a regular file: {path}" - ) - - temporary_path: Path | None = None - try: - with tempfile.NamedTemporaryFile( - mode="wb", - dir=path.parent, - prefix=f".{path.name}.", - suffix=".tmp", - delete=False, - ) as handle: - temporary_path = Path(handle.name) - handle.write(contents) - handle.flush() - os.fsync(handle.fileno()) - os.replace(temporary_path, path) - except OSError as exc: - raise HarnessError( - f"control output could not be written atomically: {path}: {exc}" - ) from exc - finally: - if temporary_path is not None and temporary_path.exists(): - temporary_path.unlink() - - def _read_json(self, p: Path) -> dict: - try: - data = json.loads(self._read_control_bytes(p).decode("utf-8")) - except (UnicodeDecodeError, json.JSONDecodeError) as exc: - raise HarnessError(f"invalid JSON file {p}: {exc}") from exc - if not isinstance(data, dict): - raise HarnessError(f"JSON root must be an object: {p}") - return data - - def _write_json(self, p: Path, data: dict): - contents = json.dumps(data, indent=2, ensure_ascii=False).encode("utf-8") - self._atomic_write_control_bytes(p, contents) - - def _read_phase_index(self) -> dict: - index = self._read_json(self._index_file) - self._validate_phase_index(index) - return index - - def _read_top_index(self) -> dict: - index = self._read_json(self._top_index_file) - phases = index.get("phases") - if not isinstance(phases, list) or not phases: - raise HarnessError("top-level phase index requires a non-empty phases array") - - selected_count = 0 - seen: set[str] = set() - for position, phase in enumerate(phases): - if not isinstance(phase, dict): - raise HarnessError( - f"top-level phase entry {position} must be an object" - ) - directory = phase.get("dir") - if not isinstance(directory, str) or not self.PHASE_NAME.fullmatch( - directory - ): - raise HarnessError( - f"top-level phase entry {position} has an invalid directory" - ) - if directory in seen: - raise HarnessError( - f"top-level phase '{directory}' must appear exactly once" - ) - seen.add(directory) - if directory == self._phase_dir_name: - selected_count += 1 - if phase.get("status") not in self.STEP_STATUSES: - raise HarnessError( - f"top-level phase entry {position} has an invalid status" - ) - - if selected_count != 1: - raise HarnessError( - f"selected phase '{self._phase_dir_name}' must appear exactly once " - "in the top-level phase index" - ) - return index - - def _validate_phase_index(self, index: dict) -> None: - project = index.get("project") - if not isinstance(project, str) or not project.strip(): - raise HarnessError("phase index project must be a non-empty string") - phase = index.get("phase") - if phase != self._phase_dir_name: - raise HarnessError( - "phase index phase must match its phase directory name" - ) - steps = index.get("steps") - if not isinstance(steps, list) or not steps: - raise HarnessError("phase index steps must be a non-empty array") - - expected_steps = list(range(len(steps))) - actual_steps = [step.get("step") if isinstance(step, dict) else None for step in steps] - if actual_steps != expected_steps: - raise HarnessError("phase step numbers must be contiguous from zero") - - state = "completed-prefix" - for expected, step in enumerate(steps): - if not isinstance(step, dict): - raise HarnessError(f"phase step {expected} must be an object") - name = step.get("name") - if not isinstance(name, str) or not self.STEP_NAME.fullmatch(name): - raise HarnessError( - f"phase step {expected} name must be a kebab-case slug" - ) - status = step.get("status") - if status not in self.STEP_STATUSES: - raise HarnessError(f"phase step {expected} has invalid status") - if "owned_paths" in step: - self._step_owned_paths(step) - self._validate_attempt_history(step) - - if status == "completed": - if state != "completed-prefix": - raise HarnessError("phase step status order is invalid") - if not isinstance(step.get("summary"), str) or not step["summary"].strip(): - raise HarnessError( - f"completed phase step {expected} requires summary" - ) - elif status == "pending": - if state == "completed-prefix": - state = "pending-suffix" - else: - if state != "completed-prefix": - raise HarnessError("phase step status order is invalid") - detail_key = "error_message" if status == "error" else "blocked_reason" - if not isinstance(step.get(detail_key), str) or not step[detail_key].strip(): - raise HarnessError( - f"{status} phase step {expected} requires {detail_key}" - ) - state = "terminal-then-pending" - - if state == "terminal-then-pending" and status == "pending": - state = "pending-suffix" - - step_file = self._phase_dir / f"step{expected}.md" - if not step_file.is_file(): - raise HarnessError(f"phase step file not found: {step_file}") - - @staticmethod - def _path_key(path: str) -> str: - return os.path.normcase(path).replace("\\", "/") - - def _step_owned_paths(self, step: dict) -> tuple[str, ...]: - paths = step.get("owned_paths") - if not isinstance(paths, list): - raise HarnessError(f"Step {step['step']} requires an owned_paths file array before execution") - normalized = [] - seen = set() - for path in paths: - if not isinstance(path, str): - raise HarnessError("owned_paths entries must be repository-relative file paths") - path = path.replace("\\", "/") - parts = path.split("/") - if ( - not path or PureWindowsPath(path).drive or path.startswith("/") - or any(part in {"", ".", ".."} or part.endswith((".", " ")) for part in parts) - or any(ord(char) < 32 or char in ':*?[]<>"|' for char in path) - or any(part.casefold() == ".git" or PureWindowsPath(part).is_reserved() for part in parts) - or parts[0].casefold() == "phases" - ): - raise HarnessError(f"owned_paths requires an exact non-control relative file path: {path!r}") - key = self._path_key(path) - if key in seen: - raise HarnessError(f"owned_paths contains duplicate/aliased paths: {path}") - seen.add(key) - normalized.append(path) - return tuple(normalized) - - def _validate_owned_file(self, path: str) -> None: - root = Path(self._root) - candidate = root / path - try: - resolved = candidate.resolve() - resolved.relative_to(root) - if resolved != candidate or candidate.is_symlink() or candidate.is_dir(): - raise ValueError("directory or linked path") - if candidate.exists() and candidate.lstat().st_nlink != 1: - raise ValueError("hard-linked file") - except (OSError, RuntimeError, ValueError) as exc: - raise HarnessError(f"owned_paths must name non-linked files inside the repository: {path}") from exc - - def _validate_attempt_history(self, step: dict) -> None: - if "attempt_history" not in step: - return - history = step["attempt_history"] - if not isinstance(history, list): - raise HarnessError("attempt_history must be an Executor-owned array") - for number, record in enumerate(history, 1): - if ( - not isinstance(record, dict) - or type(record.get("attempt")) is not int or record["attempt"] != number - or "exit_code" not in record - or (record["exit_code"] is not None and type(record["exit_code"]) is not int) - or not isinstance(record.get("reported_status"), str) - or record["reported_status"] not in self.STEP_STATUSES - or not isinstance(record.get("recorded_at"), str) or not record["recorded_at"] - or not isinstance(record.get("reported_reason"), str) - or not isinstance(record.get("reason"), str) - or not isinstance(record.get("diagnostic"), str) - or not isinstance(record.get("classification"), str) - or record["classification"] not in { - "environment", "reported-blocked", "reported-error", "completed", - "inconsistent-result", "transport-timeout", "process-error", "missing-result", - "ownership-violation", "commit-error", - } - ): - raise HarnessError(f"attempt_history contains an invalid record at attempt {number}") - - def _snapshot_phase_control_files( - self, index: dict - ) -> tuple[bytes, dict[str, bytes]]: - expected_names = {f"step{step['step']}.md" for step in index["steps"]} - current_names = { - path.name - for path in self._phase_dir.glob("step*.md") - if path.is_file() - } - if current_names != expected_names: - raise HarnessError( - "protected phase control file inventory does not match the phase index" - ) - try: - top_index = self._read_control_bytes(self._top_index_file) - step_files = { - f"step{step['step']}.md": ( - self._read_control_bytes( - self._phase_dir / f"step{step['step']}.md" - ) - ) - for step in index["steps"] - } - except HarnessError as exc: - raise HarnessError( - f"protected phase control file could not be read: {exc}" - ) from exc - return top_index, step_files - - def _validate_phase_control_files( - self, snapshot: tuple[bytes, dict[str, bytes]] - ) -> None: - expected_top, expected_steps = snapshot - try: - current_top = self._read_control_bytes(self._top_index_file) - current_names = { - path.name - for path in self._phase_dir.glob("step*.md") - if path.is_file() - } - current_steps = { - name: self._read_control_bytes(self._phase_dir / name) - for name in current_names - } - except HarnessError as exc: - raise HarnessError( - f"protected phase control file changed or disappeared: {exc}" - ) from exc - if current_top != expected_top or current_steps != expected_steps: - raise HarnessError( - "Codex modified a protected phase control file; only the current " - "Step outcome in the phase index may change" - ) - - def _record_untrusted_step_result( - self, - index_before: dict, - current_step: int, - classification: str, - reason: str, - control_snapshot: tuple[bytes, dict[str, bytes]], - ) -> None: - expected_top, expected_steps = control_snapshot - self._top_index_file.parent.mkdir(parents=True, exist_ok=True) - self._atomic_write_control_bytes(self._top_index_file, expected_top) - self._phase_dir.mkdir(parents=True, exist_ok=True) - for name, contents in expected_steps.items(): - self._atomic_write_control_bytes(self._phase_dir / name, contents) - - recovered = json.loads(json.dumps(index_before)) - current = recovered["steps"][current_step] - self._clear_step_outcome(current) - current["status"] = "error" - current["error_message"] = f"[{classification}] {reason}" - current["failed_at"] = self._stamp() - self._write_json(self._index_file, recovered) - self._update_top_index("error") - - def _validate_step_index_mutation( - self, before: dict, after: dict, current_step: int - ) -> None: - before_metadata = {key: value for key, value in before.items() if key != "steps"} - after_metadata = {key: value for key, value in after.items() if key != "steps"} - if before_metadata != after_metadata: - raise HarnessError( - "Codex modified protected phase index metadata" - ) - - before_steps = before["steps"] - after_steps = after["steps"] - if len(before_steps) != len(after_steps): - raise HarnessError("Codex modified the protected Step inventory") - - for position, (old_step, new_step) in enumerate( - zip(before_steps, after_steps) - ): - if position != current_step: - if old_step != new_step: - raise HarnessError( - f"Codex modified non-current Step {position}" - ) - continue - old_fixed = { - key: value - for key, value in old_step.items() - if key not in self.AGENT_STEP_FIELDS - } - new_fixed = { - key: value - for key, value in new_step.items() - if key not in self.AGENT_STEP_FIELDS - } - if old_fixed != new_fixed: - raise HarnessError( - "Codex modified immutable metadata on the current Step" - ) - - # --- git --- - - def _run_git(self, *args) -> subprocess.CompletedProcess: - cmd = ["git"] + list(args) - return subprocess.run( - cmd, cwd=self._root, capture_output=True, text=True, encoding="utf-8" - ) - - def _run_git_checked(self, *args) -> subprocess.CompletedProcess: - result = self._run_git(*args) - if result.returncode != 0: - diagnostic = (result.stderr or result.stdout).strip() - message = f"git {args[0]} failed" - if diagnostic: - message = f"{message}: {diagnostic}" - raise HarnessError(message) - return result - - def _git_execution_identity(self) -> tuple[str, str]: - branch = self._run_git_checked( - "symbolic-ref", "--quiet", "HEAD" - ).stdout.strip() - head = self._run_git_checked( - "rev-parse", "--verify", "HEAD" - ).stdout.strip() - if not branch or not head: - raise HarnessError("Git branch and HEAD identity must be non-empty") - return branch, head - - def _worktree_paths(self) -> tuple[str, ...]: - result = self._run_git_checked( - "status", "--porcelain=v1", "-z", "--untracked-files=all" - ) - paths: list[str] = [] - records = result.stdout.split("\0") - position = 0 - while position < len(records): - record = records[position] - position += 1 - if not record: - continue - if len(record) < 4 or record[2] != " ": - raise HarnessError("git status returned an invalid porcelain record") - status = record[:2] - paths.append(record[3:].replace("\\", "/")) - if "R" in status or "C" in status: - if position >= len(records) or not records[position]: - raise HarnessError( - "git status returned an incomplete rename/copy record" - ) - paths.append(records[position].replace("\\", "/")) - position += 1 - return tuple(dict.fromkeys(paths)) - - def _is_phase_owned_path(self, path: str) -> bool: - phase_prefix = f"phases/{self._phase_dir_name}/" - declared = { - "phases/index.json", - f"{phase_prefix}index.json", - *( - f"{phase_prefix}step{step_num}.md" - for step_num in range(self._total) - ), - } - return path in declared or self._is_step_output_path(path) - - def _is_step_output_path(self, path: str) -> bool: - phase_prefix = f"phases/{self._phase_dir_name}/" - if not path.startswith(phase_prefix): - return False - name = path.removeprefix(phase_prefix) - match = re.fullmatch(r"step(\d+)-output\.json", name) - return match is not None and int(match.group(1)) < self._total - - def _preflight_repository(self) -> None: - for step in self._read_phase_index()["steps"]: - if step["status"] == "pending": - for path in self._step_owned_paths(step): - self._validate_owned_file(path) - self._implementation_agent_profile() - top_level_result = self._run_git_checked("rev-parse", "--show-toplevel") - raw_top_level = top_level_result.stdout.strip() - if not raw_top_level or Path(raw_top_level).resolve() != Path(self._root): - raise HarnessError( - "Git top-level must exactly match the Harness repository root" - ) - mode = self._codex_sandbox_mode() - paths = self._worktree_paths() - if mode == "danger-full-access": - if paths: - raise CodexEnvironmentError( - "danger-full-access requires a clean worktree" - ) - return - unrelated = [path for path in paths if not self._is_phase_owned_path(path)] - if unrelated: - preview = ", ".join(unrelated[:5]) - raise HarnessError( - "Harness requires a clean worktree outside the selected phase; " - f"unrelated changes: {preview}" - ) - - def _is_isolated_worktree(self) -> bool: - git_dir = Path( - self._run_git_checked("rev-parse", "--absolute-git-dir").stdout.strip() - ).resolve() - common_raw = self._run_git_checked("rev-parse", "--git-common-dir").stdout.strip() - common_dir = Path(common_raw) - if not common_dir.is_absolute(): - common_dir = Path(self._root) / common_dir - return git_dir != common_dir.resolve() - - def _checkout_branch(self): - branch = f"feat-{self._phase_name}" - branch_ref = f"refs/heads/{branch}" - - current = self._run_git("symbolic-ref", "--quiet", "HEAD") - if current.returncode == 0 and current.stdout.strip() == branch_ref: - return - - exists = self._run_git( - "show-ref", "--verify", "--quiet", branch_ref - ) - if exists.returncode == 0: - switched = self._run_git("switch", branch) - elif exists.returncode == 1: - switched = self._run_git("switch", "-c", branch) - else: - raise HarnessError( - f"git show-ref failed for branch '{branch}': " - f"{(exists.stderr or exists.stdout).strip()}" - ) - - if switched.returncode != 0: - raise HarnessError( - f"git switch failed for branch '{branch}': " - f"{(switched.stderr or switched.stdout).strip()}" - ) - - verified = self._run_git_checked( - "symbolic-ref", "--quiet", "HEAD" - ) - if verified.stdout.strip() != branch_ref: - raise HarnessError( - f"Git did not enter the expected local branch '{branch}'; " - f"actual={verified.stdout.strip()!r}" - ) - - print(f" Branch: {branch}") - - def _assert_step_scope(self, owned_paths: tuple[str, ...]) -> tuple[str, ...]: - allowed = {self._path_key(path) for path in owned_paths} - changed = self._worktree_paths() - unexpected = [ - path for path in changed - if not self._is_phase_owned_path(path) and self._path_key(path) not in allowed - ] - if unexpected: - raise StepOwnershipError("Step ownership violation: " + ", ".join(unexpected)) - try: - for path in owned_paths: - self._validate_owned_file(path) - except HarnessError as exc: - raise StepOwnershipError(str(exc)) from exc - return changed - - def _commit_paths( - self, paths: list[str], message: str, *, owned_paths: tuple[str, ...] = () - ) -> bool: - validated_paths = self._assert_step_scope(owned_paths) - if not paths: - return False - # Codex may stage files even though the prompt tells it not to. Reset only - # the index so the following path-scoped add controls the commit content; - # working-tree data is preserved. This also expands staged renames back to - # a deletion/addition pair, allowing both porcelain pathnames to be staged. - if validated_paths: - self._run_git_checked( - "--literal-pathspecs", "reset", "--quiet", "HEAD", "--", *sorted(validated_paths) - ) - self._run_git_checked("--literal-pathspecs", "add", "-A", "--", *sorted(paths)) - staged = self._run_git_checked( - "diff", "--cached", "--name-only", "--no-renames", "-z" - ).stdout - selected = {self._path_key(path) for path in paths} - unexpected = [ - path for path in staged.split("\0") - if path and self._path_key(path) not in selected - ] - if unexpected: - raise StepOwnershipError("Unexpected staged paths before commit: " + ", ".join(unexpected)) - self._assert_step_scope(owned_paths) - if not staged: - return False - self._run_git_checked("commit", "-m", message) - return True - - def _commit_step(self, step_num: int, step_name: str, owned_paths: tuple[str, ...]): - changed = self._assert_step_scope(owned_paths) - code_paths = [ - path - for path in changed - if not self._is_phase_owned_path(path) - ] - message = self.FEAT_MSG.format( - phase=self._phase_name, num=step_num, name=step_name - ) - if self._commit_paths(code_paths, message, owned_paths=owned_paths): - print(f" Commit: {message}") - - metadata_paths = [ - path - for path in self._assert_step_scope(owned_paths) - if self._is_phase_owned_path(path) and not self._is_step_output_path(path) - ] - message = self.CHORE_MSG.format( - phase=self._phase_name, num=step_num - ) - self._commit_paths(metadata_paths, message, owned_paths=owned_paths) - - # --- top-level index --- - - def _update_top_index(self, status: str): - if status not in {"pending", "completed", "error", "blocked"}: - raise HarnessError(f"invalid top-level phase status: {status}") - top = self._read_top_index() - phases = top["phases"] - ts = self._stamp() - matched = False - for phase in phases: - if not isinstance(phase, dict): - raise HarnessError("top-level phase entry must be an object") - if phase.get("dir") == self._phase_dir_name: - matched = True - phase["status"] = status - ts_key = {"completed": "completed_at", "error": "failed_at", "blocked": "blocked_at"}.get(status) - for key in ("completed_at", "failed_at", "blocked_at"): - if key != ts_key: - phase.pop(key, None) - if ts_key: - phase[ts_key] = ts - break - if not matched: # Defensive: _read_top_index already enforces this invariant. - raise HarnessError("selected phase is missing from the top-level phase index") - self._write_json(self._top_index_file, top) - - # --- guardrails & context --- - - def _load_guardrails(self) -> str: - sections = [] - agents_md = ROOT / "AGENTS.md" - if agents_md.exists(): - sections.append( - "## ํ”„๋กœ์ ํŠธ ๊ทœ์น™ (AGENTS.md)\n\n" - f"{agents_md.read_text(encoding='utf-8')}" - ) - docs_dir = ROOT / "docs" - if docs_dir.is_dir(): - for doc in sorted(docs_dir.glob("*.md")): - sections.append( - f"## {doc.stem}\n\n{doc.read_text(encoding='utf-8')}" - ) - return "\n\n---\n\n".join(sections) if sections else "" - - @staticmethod - def _build_step_context(index: dict) -> str: - lines = [ - f"- Step {s['step']} ({s['name']}): {s['summary']}" - for s in index["steps"] - if s["status"] == "completed" and s.get("summary") - ] - if not lines: - return "" - return "## ์ด์ „ Step ์‚ฐ์ถœ๋ฌผ\n\n" + "\n".join(lines) + "\n\n" - - def _build_preamble(self, guardrails: str, step_context: str, - prev_error: Optional[str] = None) -> str: - retry_section = "" - if prev_error: - retry_section = ( - f"\n## โš  ์ด์ „ ์‹œ๋„ ์‹คํŒจ โ€” ์•„๋ž˜ ์—๋Ÿฌ๋ฅผ ๋ฐ˜๋“œ์‹œ ์ฐธ๊ณ ํ•˜์—ฌ ์ˆ˜์ •ํ•˜๋ผ\n\n" - f"{prev_error}\n\n---\n\n" - ) - _, _, role_instructions = self._implementation_agent_profile() - return ( - f"๋‹น์‹ ์€ {self._project} ํ”„๋กœ์ ํŠธ์˜ ๊ฐœ๋ฐœ์ž์ž…๋‹ˆ๋‹ค. ์•„๋ž˜ step์„ ์ˆ˜ํ–‰ํ•˜์„ธ์š”.\n\n" - f"## Implementation Agent role\n\n{role_instructions}\n\n---\n\n" - f"{guardrails}\n\n---\n\n" - f"{step_context}{retry_section}" - f"## ์ž‘์—… ๊ทœ์น™\n\n" - f"1. ์ด์ „ step์—์„œ ์ž‘์„ฑ๋œ ์ฝ”๋“œ๋ฅผ ํ™•์ธํ•˜๊ณ  ์ผ๊ด€์„ฑ์„ ์œ ์ง€ํ•˜๋ผ.\n" - f"2. ์ด step์— ๋ช…์‹œ๋œ ์ž‘์—…๋งŒ ์ˆ˜ํ–‰ํ•˜๋ผ. ์ถ”๊ฐ€ ๊ธฐ๋Šฅ์ด๋‚˜ ํŒŒ์ผ์„ ๋งŒ๋“ค์ง€ ๋งˆ๋ผ.\n" - f"3. ๊ธฐ์กด ํ…Œ์ŠคํŠธ๋ฅผ ๊นจ๋œจ๋ฆฌ์ง€ ๋งˆ๋ผ.\n" - f"4. AC(Acceptance Criteria) ๊ฒ€์ฆ์„ ์ง์ ‘ ์‹คํ–‰ํ•˜๋ผ.\n" - f"5. /phases/{self._phase_dir_name}/index.json์˜ ํ•ด๋‹น step status๋ฅผ ์—…๋ฐ์ดํŠธํ•˜๋ผ:\n" - f" - AC ํ†ต๊ณผ โ†’ \"completed\" + \"summary\" ํ•„๋“œ์— ์ด step์˜ ์‚ฐ์ถœ๋ฌผ์„ ํ•œ ์ค„๋กœ ์š”์•ฝ\n" - f" - ๊ตฌํ˜„ ๋˜๋Š” ๊ฒ€์ฆ ์‹คํŒจ โ†’ \"error\" + \"error_message\" ๊ธฐ๋ก\n" - f" - ์‚ฌ์šฉ์ž ๊ฐœ์ž…์ด ํ•„์š”ํ•œ ๊ฒฝ์šฐ (API ํ‚ค, ์ธ์ฆ, ์ˆ˜๋™ ์„ค์ • ๋“ฑ) โ†’ \"blocked\" + \"blocked_reason\" ๊ธฐ๋ก ํ›„ ์ฆ‰์‹œ ์ค‘๋‹จ\n" - f"6. ๋ณ€๊ฒฝ์‚ฌํ•ญ์„ ์ง์ ‘ ์ปค๋ฐ‹ํ•˜์ง€ ๋งˆ๋ผ. Git ์ปค๋ฐ‹๊ณผ timestamp๋Š” ์‹คํ–‰๊ธฐ๊ฐ€ ์ฒ˜๋ฆฌํ•œ๋‹ค.\n\n" - f"---\n\n" - ) - - # --- Codex ํ˜ธ์ถœ --- - - def _codex_sandbox_mode(self) -> str: - if self._validated_sandbox_mode is not None: - return self._validated_sandbox_mode - mode = os.environ.get(self.CODEX_SANDBOX_ENV, "workspace-write") - if mode not in self.CODEX_SANDBOX_MODES: - allowed = ", ".join(sorted(self.CODEX_SANDBOX_MODES)) - raise CodexEnvironmentError( - f"{self.CODEX_SANDBOX_ENV} must be one of: {allowed}" - ) - if mode == "danger-full-access": - if not self._danger_full_access_approved: - raise CodexEnvironmentError( - "danger-full-access requires explicit authorization through " - "--approve-danger-full-access" - ) - if not self._is_isolated_worktree(): - raise CodexEnvironmentError( - "danger-full-access requires an isolated linked worktree" - ) - if self._worktree_paths(): - raise CodexEnvironmentError( - "danger-full-access requires a clean worktree" - ) - self._validated_sandbox_mode = mode - return mode - - def _implementation_agent_profile(self) -> tuple[str, str, str]: - if self._implementation_profile_cache is not None: - return self._implementation_profile_cache - profile_path = Path(self._root) / self.IMPLEMENTATION_AGENT_PROFILE - try: - profile_text = profile_path.read_text(encoding="utf-8") - except OSError as exc: - raise CodexEnvironmentError( - f"Implementation Agent profile์„ ์ฝ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค: {profile_path}" - ) from exc - - settings = {} - for line in profile_text.splitlines(): - key, separator, value = line.partition("=") - key = key.strip() - if separator and key in {"model", "model_reasoning_effort"}: - try: - settings[key] = json.loads(value.strip()) - except json.JSONDecodeError as exc: - raise CodexEnvironmentError( - f"Implementation Agent profile์˜ {key} ๊ฐ’์ด ์˜ฌ๋ฐ”๋ฅธ ๋ฌธ์ž์—ด์ด ์•„๋‹™๋‹ˆ๋‹ค." - ) from exc - - model = settings.get("model") - reasoning_effort = settings.get("model_reasoning_effort") - if not isinstance(model, str) or not isinstance(reasoning_effort, str): - raise CodexEnvironmentError( - "Implementation Agent profile์— model๊ณผ model_reasoning_effort ๋ฌธ์ž์—ด์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค." - ) - match = re.search( - r'^developer_instructions\s*=\s*"""(.*?)"""\s*$', - profile_text, - re.MULTILINE | re.DOTALL, - ) - if match is None or not match.group(1).strip(): - raise CodexEnvironmentError( - "Implementation Agent profile์— developer_instructions๊ฐ€ ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค." - ) - instructions = match.group(1).strip() - self._implementation_profile_cache = ( - model, - reasoning_effort, - instructions, - ) - return self._implementation_profile_cache - - def _implementation_agent_settings(self) -> tuple[str, str]: - model, reasoning_effort, _ = self._implementation_agent_profile() - return model, reasoning_effort - - @staticmethod - def _process_text(value: str | bytes | None) -> str: - if value is None: - return "" - if isinstance(value, bytes): - return value.decode("utf-8", errors="replace") - return value - - def _invoke_codex(self, step: dict, preamble: str) -> dict: - step_num, step_name = step["step"], step["name"] - step_file = self._phase_dir / f"step{step_num}.md" - - if not step_file.exists(): - print(f" ERROR: {step_file} not found") - sys.exit(1) - - try: - step_text = self._read_control_bytes(step_file).decode("utf-8") - except UnicodeDecodeError as exc: - raise HarnessError(f"Step instruction must be valid UTF-8: {step_file}") from exc - prompt = preamble + step_text - sandbox_mode = self._codex_sandbox_mode() - model, reasoning_effort = self._implementation_agent_settings() - command = [ - "codex", - "exec", - "--disable", - "unified_exec", - "--json", - "--model", - model, - "--config", - f"model_reasoning_effort={json.dumps(reasoning_effort)}", - "--sandbox", - sandbox_mode, - "--dangerously-bypass-hook-trust", - "--cd", - self._root, - "-", - ] - transport_failure = None - try: - result = subprocess.run( - command, - cwd=self._root, - input=prompt, - capture_output=True, - text=True, - encoding="utf-8", - timeout=self.CODEX_TIMEOUT_SECONDS, - ) - except FileNotFoundError as exc: - raise CodexEnvironmentError( - "Codex CLI๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค. codex๋ฅผ ์„ค์น˜ํ•˜๊ณ  PATH๋ฅผ ํ™•์ธํ•˜์„ธ์š”." - ) from exc - except subprocess.TimeoutExpired as exc: - transport_failure = "timeout" - timeout_message = f"Codex timed out after {exc.timeout} seconds." - stdout = self._process_text(exc.stdout) - stderr = self._process_text(exc.stderr) - if stderr: - stderr = f"{timeout_message}\n{stderr}" - else: - stderr = timeout_message - result = subprocess.CompletedProcess( - command, 124, stdout=stdout, stderr=stderr - ) - - if result.returncode != 0: - print(f"\n WARN: Codex๊ฐ€ ๋น„์ •์ƒ ์ข…๋ฃŒ๋จ (code {result.returncode})") - if result.stderr: - print(f" stderr: {result.stderr[:500]}") - - output = { - "step": step_num, "name": step_name, - "exitCode": result.returncode, - "stdout": result.stdout, "stderr": result.stderr, - "transportFailure": transport_failure, - } - out_path = self._phase_dir / f"step{step_num}-output.json" - self._write_json(out_path, output) - - return output - - @staticmethod - def _codex_environment_failure(output: dict) -> Optional[str]: - diagnostic = ( - f"{output.get('stderr', '')}\n{output.get('stdout', '')}" - ).lower() - if "orchestrator_helper_launch_failed" in diagnostic: - return "Codex Windows sandbox helper๋ฅผ ์‹คํ–‰ํ•  ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค." - if output.get("exitCode", 0) == 0: - return None - markers = { - "not logged in": "Codex ์ธ์ฆ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค.", - "authentication": "Codex ์ธ์ฆ์— ์‹คํŒจํ–ˆ์Šต๋‹ˆ๋‹ค.", - "unexpected argument": "ํ˜„์žฌ Codex CLI๊ฐ€ ํ•„์š”ํ•œ ์˜ต์…˜์„ ์ง€์›ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.", - "unrecognized option": "ํ˜„์žฌ Codex CLI๊ฐ€ ํ•„์š”ํ•œ ์˜ต์…˜์„ ์ง€์›ํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.", - } - for marker, message in markers.items(): - if marker in diagnostic: - return message - return None - - # --- ํ—ค๋” & ๊ฒ€์ฆ --- - - def _print_header(self): - print(f"\n{'='*60}") - print(f" Harness Step Executor") - print(f" Phase: {self._phase_name} | Steps: {self._total}") - if self._auto_push: - print(f" Auto-push: enabled") - print(f"{'='*60}") - - def _check_blockers(self): - index = self._read_phase_index() - current = next( - (step for step in index["steps"] if step["status"] != "completed"), - None, - ) - if current is None or current["status"] == "pending": - return - if current["status"] == "error": - print(f"\n โœ— Step {current['step']} ({current['name']}) failed.") - print(f" Error: {current['error_message']}") - print(" Coordinator must classify the workflow correction before retry.") - sys.exit(1) - print(f"\n โธ Step {current['step']} ({current['name']}) blocked.") - print(f" Reason: {current['blocked_reason']}") - print(" Resolve the blocker and reset the Step to pending before retry.") - sys.exit(2) - - @staticmethod - def _clear_step_outcome(step: dict, keep: frozenset[str] = frozenset()) -> None: - for key in ( - "summary", - "completed_at", - "error_message", - "failed_at", - "blocked_reason", - "blocked_at", - ): - if key not in keep: - step.pop(key, None) - - def _ensure_created_at(self): - index = self._read_phase_index() - changed = False - has_pending = any(step["status"] == "pending" for step in index["steps"]) - if "created_at" not in index: - index["created_at"] = self._stamp() - changed = True - if has_pending: - if "completed_at" in index: - index.pop("completed_at") - changed = True - for step in index["steps"]: - if step["status"] != "pending": - continue - before = dict(step) - self._clear_step_outcome(step) - if step != before: - changed = True - if changed: - self._write_json(self._index_file, index) - if has_pending: - top = self._read_top_index() - selected = next( - phase - for phase in top["phases"] - if phase["dir"] == self._phase_dir_name - ) - if selected["status"] != "pending" or any( - key in selected - for key in ("completed_at", "failed_at", "blocked_at") - ): - self._update_top_index("pending") - - # --- ์‹คํ–‰ ๋ฃจํ”„ --- - - def _classify_attempt( - self, current: dict, output: dict, environment_failure: Optional[str] - ) -> tuple[str, str, str]: - """Return local classification, action and reason; never infer retry from exit alone.""" - environment_failure = environment_failure or self._codex_environment_failure(output) - if environment_failure: - return "environment", "blocked", environment_failure - status = current["status"] - if status == "blocked": - return "reported-blocked", "blocked", current["blocked_reason"] - if status == "error": - return "reported-error", "error", current["error_message"] - exit_code = output["exitCode"] - if status == "completed": - if exit_code == 0: - return "completed", "completed", current["summary"] - return ( - "inconsistent-result", "error", - f"Step reported completed but Codex exited with code {exit_code}", - ) - diagnostic = (output.get("stderr", "").strip() or output.get("stdout", "").strip())[-4000:] - if output.get("transportFailure") == "timeout": - return "transport-timeout", "retry", diagnostic - if exit_code != 0: - return "process-error", "error", diagnostic or f"Codex exited with code {exit_code}" - return "missing-result", "error", "Step did not update its workflow status" - - def _record_attempt(self, current: dict, output: dict, classification: str, reason: str) -> None: - history = current.setdefault("attempt_history", []) - field = {"completed": "summary", "error": "error_message", "blocked": "blocked_reason"}.get(current["status"]) - history.append({ - "attempt": len(history) + 1, - "recorded_at": self._stamp(), - "exit_code": output["exitCode"], - "reported_status": current["status"], - "reported_reason": current.get(field, "") if field else "", - "classification": classification, - "reason": reason, - "diagnostic": (output.get("stderr", "").strip() or output.get("stdout", "").strip())[-4000:], - }) - - def _stop_step(self, index: dict, step_num: int, status: str, reason: str) -> None: - current = index["steps"][step_num] - current["attempt_history"][-1]["reason"] = reason - self._clear_step_outcome(current) - current["status"] = status - field, timestamp, exit_code = ( - ("blocked_reason", "blocked_at", 2) if status == "blocked" - else ("error_message", "failed_at", 1) - ) - current[field] = reason - current[timestamp] = self._stamp() - self._write_json(self._index_file, index) - self._update_top_index(status) - print(f" Step {step_num}: {status} โ€” {reason}") - sys.exit(exit_code) - - def _execute_single_step(self, step: dict, guardrails: str) -> bool: - """Step์„ ์‹คํ–‰ํ•œ๋‹ค. ์ž๋™ ์žฌ์‹œ๋„๋Š” Codex transport ์‹คํŒจ์—๋งŒ ์ ์šฉํ•œ๋‹ค.""" - step_num, step_name = step["step"], step["name"] - owned_paths = self._step_owned_paths(self._read_phase_index()["steps"][step_num]) - for path in owned_paths: - self._validate_owned_file(path) - done = sum( - 1 - for item in self._read_phase_index()["steps"] - if item["status"] == "completed" - ) - prev_error = None - - for attempt in range(1, self.MAX_TRANSPORT_ATTEMPTS + 1): - index = self._read_phase_index() - step_context = self._build_step_context(index) - preamble = self._build_preamble(guardrails, step_context, prev_error) - control_snapshot = self._snapshot_phase_control_files(index) - index_before_invocation = index - git_identity = self._git_execution_identity() - - tag = f"Step {step_num}/{self._total - 1} ({done} done): {step_name}" - if attempt > 1: - tag += ( - f" [transport retry {attempt}/" - f"{self.MAX_TRANSPORT_ATTEMPTS}]" - ) - - environment_failure = None - with progress_indicator(tag) as pi: - try: - output = self._invoke_codex(step, preamble) - except CodexEnvironmentError as exc: - environment_failure = str(exc) - output = {"exitCode": None, "stdout": "", "stderr": str(exc)} - elapsed = int(pi.elapsed) - - try: - if self._git_execution_identity() != git_identity: - raise HarnessError( - "Codex changed the Git branch or HEAD; Git history is " - "Executor-owned" - ) - self._validate_phase_control_files(control_snapshot) - index = self._read_phase_index() - self._validate_step_index_mutation( - index_before_invocation, index, step_num - ) - except HarnessError as exc: - self._record_untrusted_step_result( - index_before_invocation, - step_num, - "control violation", - str(exc), - control_snapshot, - ) - raise - - exit_code = output.get("exitCode") - if type(exit_code) is not int and environment_failure is None: - reason = "Codex output requires an integer exitCode" - self._record_untrusted_step_result( - index_before_invocation, - step_num, - "protocol violation", - reason, - control_snapshot, - ) - raise HarnessError(reason) - - current = index["steps"][step_num] - ts = self._stamp() - try: - self._assert_step_scope(owned_paths) - except StepOwnershipError as exc: - self._record_attempt(current, output, "ownership-violation", str(exc)) - self._stop_step(index, step_num, "error", str(exc)) - classification, action, reason = self._classify_attempt( - current, output, environment_failure - ) - self._record_attempt(current, output, classification, reason) - - if action == "retry": - if attempt < self.MAX_TRANSPORT_ATTEMPTS: - self._clear_step_outcome(current) - self._write_json(self._index_file, index) - prev_error = reason - print( - f" โ†ป Step {step_num}: transport retry " - f"{attempt}/{self.MAX_TRANSPORT_ATTEMPTS} โ€” {reason}" - ) - continue - reason = ( - f"[transport failure after {self.MAX_TRANSPORT_ATTEMPTS} " - f"attempts] {reason}" - ) - action = "error" - - if action == "completed": - self._clear_step_outcome( - current, frozenset({"summary", "completed_at"}) - ) - current["completed_at"] = ts - self._write_json(self._index_file, index) - try: - self._commit_step(step_num, step_name, owned_paths) - except HarnessError as exc: - current["attempt_history"][-1]["classification"] = ( - "ownership-violation" if isinstance(exc, StepOwnershipError) else "commit-error" - ) - self._stop_step(index, step_num, "error", str(exc)) - print(f" โœ“ Step {step_num}: {step_name} [{elapsed}s]") - return True - - self._stop_step(index, step_num, action, reason) - - return False # unreachable - - def _execute_all_steps(self, guardrails: str): - while True: - index = self._read_phase_index() - pending = next((s for s in index["steps"] if s["status"] == "pending"), None) - if pending is None: - print("\n All steps completed!") - return - - step_num = pending["step"] - for s in index["steps"]: - if s["step"] == step_num and "started_at" not in s: - s["started_at"] = self._stamp() - self._write_json(self._index_file, index) - break - - self._execute_single_step(pending, guardrails) - - def _finalize(self): - index = self._read_phase_index() - if any(step["status"] != "completed" for step in index["steps"]): - raise HarnessError("phase cannot finalize before every Step is completed") - - changed = list(self._worktree_paths()) - unexpected = [ - path - for path in changed - if not self._is_phase_owned_path(path) - ] - if unexpected: - raise HarnessError( - "uncommitted implementation paths remain before finalization: " - + ", ".join(unexpected[:5]) - ) - index["completed_at"] = self._stamp() - self._write_json(self._index_file, index) - self._update_top_index("completed") - changed = list(self._worktree_paths()) - metadata_paths = [ - path for path in changed if not self._is_step_output_path(path) - ] - msg = f"chore({self._phase_name}): mark phase completed" - if self._commit_paths(metadata_paths, msg): - print(f" โœ“ {msg}") - - if self._auto_push: - branch = f"feat-{self._phase_name}" - self._run_git_checked("push", "-u", "origin", branch) - print(f" โœ“ Pushed to origin/{branch}") - - print(f"\n{'='*60}") - print(f" Phase '{self._phase_name}' completed!") - print(f"{'='*60}") - - -def main(): - _configure_utf8_stdio() - parser = argparse.ArgumentParser(description="Harness Step Executor") - parser.add_argument("phase_dir", help="Phase directory name (e.g. 0-mvp)") - parser.add_argument("--push", action="store_true", help="Push branch after completion") - parser.add_argument( - "--approve-danger-full-access", - action="store_true", - help=( - "Explicitly authorize danger-full-access when the matching sandbox " - "environment setting is used in a clean linked worktree" - ), - ) - args = parser.parse_args() - - try: - StepExecutor( - args.phase_dir, - auto_push=args.push, - danger_full_access_approved=args.approve_danger_full_access, - ).run() - except HarnessError as exc: - print(f"ERROR: {exc}") - sys.exit(1) + config = load_config(root) + selection = discover_project(root, config).selection + if selection is None: + print("not configured: no CMake or MSBuild project found", file=sys.stderr) + return 2 + tools = discover_toolchain(selection.kind, deadline=deadline) + adapter = CMakeAdapter() if selection.kind is ProjectKind.CMAKE else MSBuildAdapter() + plan = adapter.create_plan(root, selection, config, tools) + results = execute_plan(plan, root, deadline=deadline) + except (ConfigError, DiscoveryError, ToolchainError, AdapterError, ValidationFailure, OSError) as exc: + print(str(exc), file=sys.stderr) + return 1 + + for result in results: + print(f"{result.command.stage}: argv={list(result.command.argv)!r}; " + f"cwd={str(result.command.cwd)!r}; exit {result.returncode}") + if result.command.stage == "test": + output = (result.stdout + "\n" + result.stderr).strip() + tail = "\n".join(output.splitlines()[-8:])[-2000:] + if tail != output: + print("[test output tail]") + if tail: + print(tail) + print(f"Validation passed ({len(results)} commands).") + return 0 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.parse_args(argv) + return run_validations(ROOT) if __name__ == "__main__": - main() + raise SystemExit(main()) diff --git a/scripts/hooks/pre_tool_use.py b/scripts/hooks/pre_tool_use.py deleted file mode 100644 index 30e26e6..0000000 --- a/scripts/hooks/pre_tool_use.py +++ /dev/null @@ -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.+?)\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()) diff --git a/scripts/hooks/stop_validation.py b/scripts/hooks/stop_validation.py deleted file mode 100644 index 7c3555f..0000000 --- a/scripts/hooks/stop_validation.py +++ /dev/null @@ -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 = 1800 - - -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()) diff --git a/scripts/hooks/validation_scope.py b/scripts/hooks/validation_scope.py deleted file mode 100644 index 5bfd4c9..0000000 --- a/scripts/hooks/validation_scope.py +++ /dev/null @@ -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 - ) diff --git a/scripts/msvc_harness/config.py b/scripts/msvc_harness/config.py index 8723605..aab8571 100644 --- a/scripts/msvc_harness/config.py +++ b/scripts/msvc_harness/config.py @@ -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), ) diff --git a/scripts/msvc_harness/discovery.py b/scripts/msvc_harness/discovery.py index 0c51fea..69218f6 100644 --- a/scripts/msvc_harness/discovery.py +++ b/scripts/msvc_harness/discovery.py @@ -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) diff --git a/scripts/msvc_harness/models.py b/scripts/msvc_harness/models.py index 1c03085..fe640aa 100644 --- a/scripts/msvc_harness/models.py +++ b/scripts/msvc_harness/models.py @@ -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) diff --git a/scripts/msvc_harness/tdd_policy.py b/scripts/msvc_harness/tdd_policy.py deleted file mode 100644 index b5f5b8c..0000000 --- a/scripts/msvc_harness/tdd_policy.py +++ /dev/null @@ -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 From 5e2a30fce06eba5e7ba4fda670328462c7a0cd02 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Mon, 7 Sep 2026 22:12:48 +0900 Subject: [PATCH 3/3] docs: align guidance with simplified agent and harness workflow --- AGENTS.md | 133 +++--- docs/ADR.md | 70 +++- docs/ARCHITECTURE.md | 72 ++-- docs/CODINGSTYLE.md | 22 +- docs/FEATURE_DOCUMENTATION.md | 125 +++--- docs/HARNESS.md | 208 +++++----- docs/HARNESS_WORKFLOW.md | 744 ++++------------------------------ docs/PRD.md | 35 +- docs/SOLVER_AGENT_DESIGN.md | 279 +++++-------- docs/SOLVER_SKILL_DESIGN.md | 209 ++++------ 10 files changed, 593 insertions(+), 1304 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3b02cfb..8c55ca5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//`์— ๋‘”๋‹ค. Coordinator๊ฐ€ ์•ˆ์ •์ ์ธ kebab-case Feature ID๋ฅผ ์ •ํ•˜๊ณ  ๋ชจ๋“  dispatch์—์„œ ๊ฐ™์€ ํด๋”์™€ revision์„ ์‚ฌ์šฉํ•œ๋‹ค. ๊ธฐ์กด `docs/features//` ์ž๋ฃŒ๊ฐ€ ์žˆ์œผ๋ฉด ์ž๋™ ์ด๋™ยท๋ณต์ œํ•˜์ง€ ์•Š๊ณ  ํ•„์š”ํ•œ ๊ฒฝ๋กœ์™€ 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 ํด๋”๋‚˜ ๋นˆ ๋ณด๊ณ ์„œ๋ฅผ ๋งŒ๋“ค์ง€ ์•Š๋Š”๋‹ค. +- ์ผ๋ฐ˜ 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//`์™€ 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-` 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--###`์ด๋‹ค. +- ์ˆ˜์‹ยท์š”์†Œยท์žฌ๋ฃŒยท์ ๋ถ„ยท์ƒํƒœ ๊ฐฑ์‹  ๋ณ€๊ฒฝ์€ ๋…๋ฆฝ numerical review์™€ ํ•ด๋‹น analytical/invariant ๊ฒ€์ฆ์„ ์ˆ˜ํ–‰ํ•œ๋‹ค. ํ•„์š”ํ•œ ๋ฌผ๋ฆฌยทreference ๊ฒ€์ฆ๋„ ์œ ์ง€ํ•œ๋‹ค. +- ๋ณ€๊ฒฝ ์ค‘์—๋Š” ๊ด€๋ จ ๊ฒ€์‚ฌ๋ฅผ, ์†”๋ฒ„ ๊ธฐ๋Šฅ ์™„๋ฃŒ ์‹œ์—๋Š” ๊ตฌ์„ฑ๋œ ์ „์ฒด build/test์™€ ํ•„์ˆ˜ reference ๋น„๊ต๋ฅผ ํ•œ ๋ฒˆ ์ˆ˜ํ–‰ํ•œ๋‹ค. ์‚ฌ์šฉ์ž ์š”์ฒญ์ด๋‚˜ ๋„“์€ ๋ณ€๊ฒฝ ์˜ํ–ฅ์œผ๋กœ ์ „์ฒด ๊ฒ€์ฆ์ด ํ•„์š”ํ•œ ๊ฒฝ์šฐ์—๋„ ์‹คํ–‰ํ•˜๋ฉฐ ์ดํ›„ ๋ณ€๊ฒฝยท์‹คํŒจ๊ฐ€ ์—†์œผ๋ฉด ๋ฐ˜๋ณตํ•˜์ง€ ์•Š๋Š”๋‹ค. +- ๋ฌธ์„œ๋งŒ ์ˆ˜์ •ํ•˜๋Š” ์ž‘์—…์€ ๋งํฌยท์†Œ์Šค ๋Œ€์กฐยทdiff ์ •์  ๊ฒ€ํ† ๋กœ ํ™•์ธํ•˜๊ณ  build/test๋ฅผ ์‹คํ–‰ํ•˜์ง€ ์•Š๋Š”๋‹ค. ๋ฏธ์‹คํ–‰์„ ํ†ต๊ณผ๋กœ ๋ณด๊ณ ํ•˜์ง€ ์•Š๋Š”๋‹ค. +- ๊ธฐ๋Šฅ ๋ฌธ์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ํ•œ๊ตญ์–ด Markdown์œผ๋กœ ์ž‘์„ฑํ•˜๋˜ agent/skill ID, field, requirement ID, ๊ฒฝ๋กœ์™€ ๋ช…๋ น์€ English๋ฅผ ์œ ์ง€ํ•œ๋‹ค. ์ƒˆ requirement ID ๊ธฐ๋ณธ ํ˜•์‹์€ `FEM-REQ--###`์ด๋‹ค. - ์ปค๋ฐ‹ ๋ฉ”์‹œ์ง€๋Š” 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//`) | -| --- | --- | --- | --- | -| 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//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 +python scripts/execute.py ``` -``๋Š” ํ• ๋‹น๋œ phase๋กœ ๋Œ€์ฒดํ•œ๋‹ค. `--push`๋Š” ์›๊ฒฉ push๊ฐ€ ๋ช…์‹œ์ ์œผ๋กœ ์Šน์ธ๋œ ๊ฒฝ์šฐ์—๋งŒ ์ถ”๊ฐ€ํ•œ๋‹ค. +Phase ์ธ์ž๋‚˜ `--push`ยท`--approve-danger-full-access`๋ฅผ ์ถ”๊ฐ€ํ•˜์ง€ ์•Š๋Š”๋‹ค. ์ด ์ธ์ž๋“ค์€ +usage error๋กœ ๊ฑฐ๋ถ€๋œ๋‹ค. Exit ์˜๋ฏธยท์„ค์ •ยท์ด์ „ ๋ฐฉ์‹ ๋ณ€๊ฒฝ ์•ˆ๋‚ด๋Š” [HARNESS](docs/HARNESS.md)๋ฅผ +๋”ฐ๋ฅธ๋‹ค. ํ•„์š”ํ•œ ์ˆ˜์น˜/reference ๊ฒ€์ฆ์„ runner ์„ฑ๊ณต๋งŒ์œผ๋กœ ๋Œ€์ฒดํ•˜์ง€ ์•Š๋Š”๋‹ค. ### CMake/CTest ํ”„๋กœ์ ํŠธ @@ -189,7 +181,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 ํŒŒ์ผ์„ ๋”ฐ๋ฅธ๋‹ค. diff --git a/docs/ADR.md b/docs/ADR.md index 6382413..dae8bfe 100644 --- a/docs/ADR.md +++ b/docs/ADR.md @@ -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์ด ์•„๋‹ˆ๋ฏ€๋กœ ๋’ค์ชฝ ์ปค๋ฐ‹ ์‹คํŒจ ์‹œ ์•ž์„  ์ปค๋ฐ‹์„ ๋ณด์กดํ•˜๊ณ  ์˜ค๋ฅ˜๋กœ ๋ฐ˜ํ™˜ํ•œ๋‹ค. + + +### 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, diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4c04b21..df5824a 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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 ๋ณ€๊ฒฝ์€ ์˜ํ–ฅ๋ฐ›๋Š” diff --git a/docs/CODINGSTYLE.md b/docs/CODINGSTYLE.md index e897acd..e3549fb 100644 --- a/docs/CODINGSTYLE.md +++ b/docs/CODINGSTYLE.md @@ -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 ๊ฒ€์ฆ ๋ฒ”์œ„ ๋ฐ ๋ช…๋ น์„ ์ •ํ–ˆ๋‹ค. diff --git a/docs/FEATURE_DOCUMENTATION.md b/docs/FEATURE_DOCUMENTATION.md index 6877ba1..dc62d9c 100644 --- a/docs/FEATURE_DOCUMENTATION.md +++ b/docs/FEATURE_DOCUMENTATION.md @@ -1,79 +1,82 @@ # Feature ๋ฌธ์„œ ๊ด€๋ฆฌ -์ด ๊ทœ์น™์€ ๋ชจ๋“  agent์˜ Feature ์‚ฐ์ถœ๋ฌผ์— ์ ์šฉํ•œ๋‹ค. Coordinator๋Š” ์š”๊ตฌ์‚ฌํ•ญ์„ ๋ฐ›์œผ๋ฉด -`docs//`๋ฅผ ์ƒ์„ฑํ•˜๊ณ  ๋ฌธ์„œ ๋ชฉ๋ก, ์ฐธ์กฐ์™€ workflow ์ƒํƒœ๋ฅผ ๊ด€๋ฆฌํ•œ๋‹ค. -``๋Š” Coordinator๊ฐ€ ์ •ํ•œ ์•ˆ์ •์ ์ธ kebab-case ์ด๋ฆ„์ด๋ฉฐ ๋ชจ๋“  dispatch์—์„œ ๊ณต์œ ํ•œ๋‹ค. +์ง€์†ํ•  ์š”๊ตฌ์‚ฌํ•ญยท๊ณ„์•ฝยท๊ฒ€์ฆ evidence๊ฐ€ ํ•„์š”ํ•œ solver Feature์—๋Š” `docs//`๋ฅผ +์‚ฌ์šฉํ•œ๋‹ค. ๋ฉ”์ธ 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//` ์ž๋ฃŒ๋Š” ์ด๋ ฅ์ด๋ฏ€๋กœ ์ž๋™ ์ด๋™ํ•˜๊ฑฐ๋‚˜ ๋ณต์ œํ•˜์ง€ ์•Š๋Š”๋‹ค. - ์žฌ๊ฐœ์— ํ•„์š”ํ•œ ๊ธฐ์กด ์ž๋ฃŒ๋Š” ์ƒˆ ํด๋”์˜ ๋ฌธ์„œ ๋ชฉ๋ก์—์„œ ๊ฒฝ๋กœ์™€ 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//`์™€ `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//`์— ์ €์žฅํ•œ๋‹ค. ์†Œ์Šคยทํ…Œ์ŠคํŠธยท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--###`๋‹ค. + +๋ฉ”์ธ์€ ์‹ค์ œ ํŒŒ์ผยท์†Œ์œ ๊ถŒยท์ƒ๋Œ€ ๋งํฌ์™€ ํŒ๋‹จ์— ํ•„์š”ํ•œ evidence๋ฅผ ํ™•์ธํ•œ๋‹ค. ํ•„์ˆ˜ ์ƒ์„ธ ๊ทผ๊ฑฐ๊ฐ€ +์—†๊ฑฐ๋‚˜ ์—ฐ๊ฒฐ์ด ๋Š๊ฒผ๋‹ค๋ฉด ํ•ด๋‹น owner์™€ ํ•ด๊ฒฐํ•˜๊ณ  ์š”์•ฝ๋งŒ์œผ๋กœ ๊ฒ€์ฆ์„ ๋Œ€์‹ ํ•˜์ง€ ์•Š๋Š”๋‹ค. +๋ฌธ์„œ ์ •๋ฆฌ๋Š” ์ •์  ๊ฒ€ํ† ๋กœ ํ™•์ธํ•˜๋ฉฐ solver build๋‚˜ ์ˆ˜์น˜/reference ๊ฒ€์ฆ์˜ ํ†ต๊ณผ๋กœ ๋ณด๊ณ ํ•˜์ง€ ์•Š๋Š”๋‹ค. diff --git a/docs/HARNESS.md b/docs/HARNESS.md index f6c90e3..f9cbec9 100644 --- a/docs/HARNESS.md +++ b/docs/HARNESS.md @@ -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 -``` +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 --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 ` ํ˜ธ์ถœ๊ณผ `--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๋ฅผ ๋”ฐ๋ฅธ๋‹ค. +์‹ค์ œ ๊ฒ€์‚ฌ ๊ฒฐ๊ณผ์™€ ๋ฏธ์‹คํ–‰ ํ•ญ๋ชฉ์„ ๊ตฌ๋ถ„ํ•ด ๋ณด๊ณ ํ•œ๋‹ค. ๋ฌธ์„œ๋งŒ ๊ฐฑ์‹ ํ•  ๋•Œ๋Š” ์ด ๋ช…๋ น์„ ์‹คํ–‰ํ•˜์ง€ ์•Š๋Š”๋‹ค. diff --git a/docs/HARNESS_WORKFLOW.md b/docs/HARNESS_WORKFLOW.md index 1569ba4..02de807 100644 --- a/docs/HARNESS_WORKFLOW.md +++ b/docs/HARNESS_WORKFLOW.md @@ -1,693 +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์˜ `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 - --config model_reasoning_effort="" - --sandbox - --dangerously-bypass-hook-trust - --cd - - -``` - -๊ธฐ๋ณธ๊ฐ’์€ `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 -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 -cmake --build --preset -ctest --preset --show-only=json-v1 -ctest --preset --output-on-failure -``` - -์ด ๊ฒฝ์šฐ ๋ชจ๋“  ๋ช…๋ น์€ `cmake.sourceDir`์—์„œ ์‹คํ–‰ํ•˜๊ณ  compiler metadata ๊ฒ€์‚ฌ๋Š” ์„ค์ •ํ•œ -`binaryDir`์—์„œ ์ˆ˜ํ–‰ํ•œ๋‹ค. - -### 9.3 ์ง์ ‘ MSBuild - -[MSBuild adapter](../scripts/msvc_harness/adapters/msbuild.py)๋Š” ๋‹ค์Œ ์ˆœ์„œ๋กœ ์‹คํ–‰ํ•œ๋‹ค. - -```powershell -MSBuild.exe /m /nologo ` - /p:Configuration= ` - /p:Platform= - - -``` - -์ง์ ‘ MSBuild ํ”„๋กœ์ ํŠธ๋Š” ํ‘œ์ค€ ํ…Œ์ŠคํŠธ ํƒ์ƒ‰ ๋ช…๋ น์ด ์—†์œผ๋ฏ€๋กœ -`.harness/config.json`์˜ `msbuild.testCommand`๊ฐ€ ๋ฐ˜๋“œ์‹œ ํ•„์š”ํ•˜๋‹ค. ์ด ๊ฐ’์ด ์—†์œผ๋ฉด -Stop ๊ฒ€์ฆ์ด ์‹คํŒจํ•œ๋‹ค. - -## 10. ๋ช…๋ น ์‹คํ–‰ ์•ˆ์ „์„ฑ๊ณผ ์ œํ•œ์‹œ๊ฐ„ - -[๊ฒ€์ฆ ์‹คํ–‰๊ธฐ](../scripts/msvc_harness/process.py)๋Š” ๋‹ค์Œ ์•ˆ์ „ ๊ทœ์น™์„ ์ ์šฉํ•œ๋‹ค. - -- ๋ช…๋ น์„ shell ๋ฌธ์ž์—ด์ด ์•„๋‹Œ argv ๋ฐฐ์—ด๋กœ ์‹คํ–‰ํ•œ๋‹ค. -- `shell=False`๋ฅผ ์‚ฌ์šฉํ•œ๋‹ค. -- ๊ฐ ๋ช…๋ น์˜ working directory๊ฐ€ ์ €์žฅ์†Œ ๋‚ด๋ถ€์ธ์ง€ ๊ฒ€์‚ฌํ•œ๋‹ค. -- ๋ช…๋ น๋ณ„ ์ œํ•œ์‹œ๊ฐ„๊ณผ Stop ์ „์ฒด ์ œํ•œ์‹œ๊ฐ„ ์ค‘ ๋” ์งง์€ ๊ฐ’์„ ์ ์šฉํ•œ๋‹ค. -- ์ข…๋ฃŒ ์ฝ”๋“œ๊ฐ€ 0์ด ์•„๋‹ˆ๋ฉด ์ฆ‰์‹œ ํ•ด๋‹น stage๋ฅผ ์‹คํŒจ ์ฒ˜๋ฆฌํ•œ๋‹ค. - -Stop ํ›…์˜ ์ „์ฒด ์ œํ•œ์‹œ๊ฐ„์€ ์ €์žฅ์†Œ ํƒ์ƒ‰, toolchain ํƒ์ƒ‰, configure, build, test discovery, -test๋ฅผ ๋ชจ๋‘ ํฌํ•จํ•ด 1,800์ดˆ๋‹ค. `.codex/hooks.json`์˜ Stop command timeout๋„ 1,800์ดˆ๋‹ค. - -์‹คํŒจ ๋ฉ”์‹œ์ง€์—๋Š” ๋‹ค์Œ ์ง„๋‹จ ์ •๋ณด๋ฅผ ํฌํ•จํ•œ๋‹ค. - -- ์‹คํŒจ 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 ์‹คํ–‰ ๊ถŒํ•œ์„ ๋ถ€์—ฌํ•˜์ง€ ์•Š๋Š”๋‹ค. diff --git a/docs/PRD.md b/docs/PRD.md index bf2a08f..9c18f64 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -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๋กœ ํ™•๋Œ€ํ•˜์ง€ ์•Š๋Š”๋‹ค. ## ๋‹จ๊ณ„์  ํ™•์žฅ๊ณผ ๋น„๋ชฉํ‘œ diff --git a/docs/SOLVER_AGENT_DESIGN.md b/docs/SOLVER_AGENT_DESIGN.md index 608c8b2..395bb5e 100644 --- a/docs/SOLVER_AGENT_DESIGN.md +++ b/docs/SOLVER_AGENT_DESIGN.md @@ -1,220 +1,135 @@ # Structural FEM Solver Agent Design -## 1. ๋ชฉ์  +## ๋ชฉ์  -์ด ๋ฌธ์„œ๋Š” ๋ฒ”์šฉ ์œ ํ•œ์š”์†Œ ๊ตฌ์กฐํ•ด์„ ์†”๋ฒ„๋ฅผ ๊ฐœ๋ฐœํ•˜๋Š” agent๋“ค์˜ ๊ณตํ†ต ์šด์˜ ๊ณ„์•ฝ์„ ์ •์˜ํ•œ๋‹ค. -`coordinator-agent`๋งŒ workflow ์ƒํƒœ๋ฅผ ์ „์ดํ•˜๋ฉฐ, specialist agent๋Š” ํ• ๋‹น๋œ ๋‹จ๊ณ„์˜ ํŒ๋‹จ๊ณผ -์‚ฐ์ถœ๋ฌผ๋งŒ ์†Œ์œ ํ•œ๋‹ค. ๊ธฐ๋Šฅ๋ณ„ ๋ฌธ์„œ๋Š” `docs//`์— ๋ณด์กดํ•œ๋‹ค. -ํด๋” ์ƒ์„ฑ, ๊ณตํ†ต ๋ฌธ์„œ ์ฐธ์กฐ, ๊ฐ„๊ฒฐํ•œ ๋ณธ๋ฌธ๊ณผ ์ƒ์„ธ ๋ฌธ์„œ ๋ถ„๋ฆฌ๋Š” -[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//`๋ฅผ ์ดˆ๊ธฐํ™”ํ•˜๊ณ  +`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//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//` ๊ธฐ์ค€์ด๋‹ค. ๊ฐ 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: -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: -evidence_paths: [] -evidence_digest: -failure_classification: -retry_key: -attempt: -escalation_class: -blocker: -``` +์ƒˆ 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 ๊ด€๋ฆฌ ๋ฌธ์„œ 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--###`์ด๋‹ค. -- Placeholder artifact๋Š” ๋งŒ๋“ค์ง€ ์•Š๋Š”๋‹ค. Correction์ด ์‹ค์ œ ๋ฐœ์ƒํ•  ๋•Œ๋งŒ `corrections.md`๋ฅผ ๋งŒ๋“ ๋‹ค. -- ๋ชจ๋“  stage๋Š” ์ž์‹ ์ด ๋ณ€๊ฒฝํ•œ ๊ฒฝ๋กœ์™€ ๋ณ€๊ฒฝํ•˜์ง€ ์•Š์€ upstream contract๋ฅผ ๋ช…ํ™•ํžˆ ๊ธฐ๋กํ•œ๋‹ค. +๊ธฐ๋Šฅ ๋ฌธ์„œ๋Š” ๊ธฐ๋ณธ์ ์œผ๋กœ ํ•œ๊ตญ์–ด Markdown์œผ๋กœ ์ž‘์„ฑํ•œ๋‹ค. Agent/skill ID, field, +requirement ID, ๊ฒฝ๋กœ์™€ ๋ช…๋ น์€ English๋ฅผ ์œ ์ง€ํ•œ๋‹ค. ์ƒˆ requirement ID ๊ธฐ๋ณธ ํ˜•์‹์€ +`FEM-REQ--###`์ด๋‹ค. ๋ณด๊ณ ์„œ๋Š” ์‹ค์ œ ๊ฒฐ์ •๊ณผ evidence๋ฅผ ํ•œ ๋ฒˆ๋งŒ ๊ธฐ๋กํ•˜๊ณ , +๊ธฐ์กด phaseยทcoordinationยท์‹คํŒจ ๊ธฐ๋ก์€ ์ด๋ ฅ์œผ๋กœ ๋ณด์กดํ•œ๋‹ค. diff --git a/docs/SOLVER_SKILL_DESIGN.md b/docs/SOLVER_SKILL_DESIGN.md index 136031c..67dee63 100644 --- a/docs/SOLVER_SKILL_DESIGN.md +++ b/docs/SOLVER_SKILL_DESIGN.md @@ -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.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 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๋ฅผ ๊ฐ•์ œํ•˜์ง€ ์•Š๋Š”๋‹ค. ์ •์  ๊ฒ€ํ† ์™€ ์‹ค์ œ ์‹คํ–‰ ์—ฌ๋ถ€๋ฅผ ๊ตฌ๋ถ„ํ•ด ๊ธฐ๋กํ•œ๋‹ค.