@ai-content-space/loopx 0.1.2 → 0.1.4

package/skills/build/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: build
 description: Ralph-style loopx execution runtime under the public build stage.
-argument-hint: "[--no-deslop] <approved workflow slug>"
+argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
 # loopx Build
@@ -14,6 +14,7 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 
 <Use_When>
 - `plan -> build` has already been explicitly approved.
+- `review -> build` was requested for implementation fixes and a review artifact is supplied with `--from-review`.
 - Canonical plan artifacts already exist and execution should now proceed.
 - The task needs execution persistence, verification evidence, and explicit pre-review quality gates.
 </Use_When>
@@ -29,34 +30,97 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 - Execution may parallelize internally without exposing a public `team` stage.
 - `build` does not replace `review`.
 - `execution-record.md` remains the sole canonical execution and verification artifact.
+- Feature work and bug fixes should use `tdd`: write a failing test, confirm it fails for the intended reason, then implement the smallest passing change.
+- Bug, test-failure, build-failure, and unexpected-behavior work should use `debug` before proposing fixes.
+- Completion and review-ready claims should use `verify` before they are stated.
+- Go edits should use `go-style` and preserve local repository conventions.
+- Go-Kratos work should use `kratos` when Kratos project signals or Kratos-specific tasks are present.
 - Fresh evidence is required before review handoff.
 - Deslop and regression re-verification are part of the default build path.
+- `build` has one owner for persistence. Delegation may run in parallel, but the owner remains accountable for draining delegated work and proving completion before review handoff.
 </Core_Principles>
 
 <Preconditions>
-`build` starts only when all of the following are true:
+For initial execution, `build` starts only when all of the following are true:
 
 - approved `plan -> build` transition exists
 - `.loopx/plans/prd-<slug>.md` exists
 - `.loopx/plans/test-spec-<slug>.md` exists
 - workflow-local planning artifacts required by the execution lane exist
+
+For review-requested implementation fixes, `build` may instead start from:
+
+- `$build --from-review .loopx/workflows/<slug>/review-report.md`
+- or `$build --from-review .loopx/workflows/<slug>/review.md`
+
+In that mode, the review artifact is the direct rework contract. The approved PRD, test spec, previous execution record, and workflow-local plan package remain required context, but they are not the primary user-facing argument.
 </Preconditions>
 
+<Inputs>
+Preferred skill input:
+
+- `.loopx/plans/prd-<slug>.md`
+
+Preferred review rework input:
+
+- `--from-review .loopx/workflows/<slug>/review-report.md`
+
+Compatible skill / CLI input:
+
+- `<slug>`
+
+When invoked with a PRD path, derive `<slug>` from `prd-<slug>.md` and still use the matching workflow-local plan package and test spec.
+
+When invoked with `--from-review`, derive `<slug>` from the workflow directory, treat the review artifact as the implementation-fix contract, and load the matching PRD, test spec, previous `execution-record.md`, and workflow-local plan package as supporting context. This Codex skill invocation consumes the `review -> build` rework intent; users should not need a separate bash `loopx approve ... --from review --to build` step for the normal Codex-facing flow.
+</Inputs>
+
 <Execution_Model>
 `build` should behave like a Ralph-style execution runtime:
 
 1. Initialize or resume build iteration state.
-2. Run internal execution / evidence / verification lanes in parallel.
-3. Aggregate lane results into canonical `execution-record.md`.
-4. Run fresh verification and read actual output.
-5. Run architect verification as a hard pre-review gate.
-6. Run deslop on build-owned changes.
-7. Re-run regression verification after deslop.
-8. Stop only when review handoff gates are satisfied or a real blocker remains.
+2. If running from `--from-review`, load the review artifact first and constrain implementation work to the requested implementation fixes unless the review artifact exposes a real plan or clarify blocker.
+3. Run internal execution / evidence / verification lanes in parallel.
+4. For implementation work, apply `tdd` unless the approved plan explicitly classifies the change as non-behavioral or test-inapplicable.
+5. For failures discovered during execution or verification, apply `debug` before attempting fixes.
+6. For `.go` edits, apply `go-style`; for Kratos API/service/biz/data work, apply `kratos` before changing framework structure.
+7. Aggregate lane results into canonical `execution-record.md`.
+8. Run fresh verification and read actual output using `verify` discipline.
+9. Run architect verification as a hard pre-review gate.
+10. Run deslop on build-owned changes.
+11. Re-run regression verification after deslop.
+12. Write/update the build delegation ledger and ensure blocking delegated work is drained.
+13. Write/update the completion audit mapping approved plan, slices, and review rework inputs to evidence.
+14. Stop only when review handoff gates are satisfied or a real blocker remains.
 
 `build` may persist support artifacts for runtime inspection, but they must not replace `execution-record.md`.
 </Execution_Model>
 
+<Continuation_Discipline>
+`build` is a persistence loop, not a "one phase per invocation" runner.
+
+If approved plan work remains, continue executing within the same `$build` invocation until either review handoff gates are satisfied or a real blocker prevents further progress.
+
+The following are **not** real blockers by themselves:
+
+- a planned phase is unfinished
+- a runtime adapter is not fully migrated yet
+- store-layer branches still need to be moved to the new service/client path
+- more files remain in the approved implementation scope
+- verification has not been rerun after the latest edits
+
+Those are remaining execution work. Keep working them down.
+
+A real blocker must identify why execution cannot safely continue now, such as:
+
+- missing human product/architecture decision that is not specified by the approved plan
+- unavailable credential, service, fixture, dependency, or environment that cannot be mocked or bypassed responsibly
+- verification failure caused by a pre-existing repository condition that blocks evaluating this change and cannot be isolated
+- repeated implementation failure after the build iteration budget is exhausted
+- a conflict between the approved plan and current repository facts that requires re-planning
+
+Do not end a build response with "continue in the next build" for unfinished approved work. If work remains and no real blocker exists, keep executing. If a real blocker exists, name the concrete blocker and record it in `execution-record.md`.
+</Continuation_Discipline>
+
 <Runtime_State_Machine>
 `build` should track at minimum:
 
@@ -72,6 +136,14 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 - `build_blockers`
 - `build_progress_artifact_paths`
 - `build_support_evidence_paths`
+- `build_owner_id`
+- `build_owner_session_id`
+- `build_owner_status`
+- `build_delegation_status`
+- `build_delegation_ledger_path`
+- `build_active_delegation_count`
+- `build_completion_audit_status`
+- `build_completion_audit_path`
 - `execution_record_status`
 
 `build -> review` is blocked until:
@@ -81,6 +153,8 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 - architect verification is approved
 - deslop is complete, unless explicitly skipped
 - post-deslop regression passes
+- blocking delegated build work is drained
+- completion audit passes
 - `execution-record.md` is complete
 </Runtime_State_Machine>
 
@@ -89,6 +163,15 @@ Canonical artifact:
 
 - `execution-record.md`
 
+`execution-record.md` must make the completion scope explicit when a plan is larger than the current implementation slice:
+
+- `planned_scope`: the approved PRD/workflow scope being measured.
+- `implemented_scope`: the scope actually completed in this build run.
+- `remaining_scope`: empty only when the approved workflow scope is fully implemented.
+- `completion_claim`: use `full` only when the whole approved workflow is complete; use `slice` or another non-full value for partial implementation.
+
+If `remaining_scope` is non-empty or `completion_claim` is not `full`, build may still hand off for slice review, but review/archive must not treat that as full workflow completion.
+
 Support artifacts may exist for:
 
 - iteration progress
@@ -96,6 +179,8 @@ Support artifacts may exist for:
 - architect gate summaries
 - deslop summaries
 - regression summaries
+- `build-support/delegation-ledger.json`
+- `build-support/completion-audit.json`
 
 These support artifacts are runtime aids only. They must not become new canonical review inputs.
 </Artifact_Contract>
@@ -106,6 +191,23 @@ These support artifacts are runtime aids only. They must not become new canonica
 - review continues to own provenance checks, evidence completeness checks, completion/rollback decisions, and code-review
 </Review_Boundary>
 
+<Final_Response_Contract>
+When `build` reaches review handoff readiness, the final response must include an explicit next skill command using the execution record path:
+
+```text
+Next:
+$review .loopx/workflows/<slug>/execution-record.md
+```
+
+If the user needs the CLI/runtime-debug form, use:
+
+```bash
+loopx review <slug>
+```
+
+Do not end with prose-only guidance such as "next step should enter review" when the workflow is ready for review. Do not emit `$review <slug>` as the primary skill handoff when the execution record path is known. If review handoff is blocked, state the blocker instead of emitting a `$review` command.
+</Final_Response_Contract>
+
 <Flags>
 - `--no-deslop`: skip the deslop pass and the post-deslop regression loop, while still requiring the latest successful pre-deslop verification evidence
 </Flags>

package/skills/clarify/SKILL.md

@@ -23,7 +23,7 @@ Its job is not just to ask questions. Its job is to turn a vague or overloaded r
 - The request is broad, ambiguous, or mixes problem, solution, and implementation detail.
 - The user needs help defining scope, non-goals, acceptance criteria, or tradeoffs before planning.
 - A design direction exists only implicitly and would otherwise be invented during implementation.
-- The task will later be handed to `plan`, `build`, or `autopilot`, and you want a high-signal spec first.
+- The task will later be handed to `plan`, and you want a high-signal spec first.
 </Use_When>
 
 <Do_Not_Use_When>
@@ -33,15 +33,17 @@ Its job is not just to ask questions. Its job is to turn a vague or overloaded r
 </Do_Not_Use_When>
 
 <Why_This_Exists>
-Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` or `build` magnifies them.
+Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` turns the clarified intent into an execution contract.
 </Why_This_Exists>
 
 <Core_Principles>
 - Ask one question at a time.
+- Prefer bounded multiple-choice questions when the option space is known; use open-ended questions only when the option space is genuinely unknown.
 - Prefer the highest-leverage unresolved question, not broad coverage.
 - Keep digging on the same thread until one assumption, one boundary, or one tradeoff becomes clearer.
 - Treat every answer as a claim to pressure-test, not a final truth to copy down.
 - Make `Non-goals` and `Decision Boundaries` mandatory gates.
+- Default to YAGNI: shrink speculative scope unless the user gives a concrete reason it belongs in the first pass.
 - Do not stop at “requirements”; shape the solution enough that the next stage has a coherent starting design.
 </Core_Principles>
 
@@ -80,10 +82,20 @@ Do not mark a clarify spec handoff-ready by prose alone. Update the frontmatter
 </Runtime_State_Machine>
 
 <Execution_Policy>
+- Always run a preflight context intake before the first interview question.
+- If supplied context is too large for safe prompt use, first request or create a concise prompt-safe summary that preserves goals, constraints, success criteria, non-goals, decision boundaries, and source references.
 - Explore repo context before asking the user about internals.
 - Prefer evidence-backed clarification in brownfield work:
   - “I found X in Y. Should this clarify spec preserve that pattern?”
+- Route facts before judgment:
+  - discoverable codebase facts should be inspected directly
+  - evidence-backed inferences should be confirmed with the user
+  - product intent, tradeoffs, scope, non-goals, and decision boundaries must be treated as human decisions
 - Ask about intent and boundaries before implementation detail.
+- Respect stage priority:
+  1. intent, outcome, scope, non-goals, decision boundaries
+  2. constraints and success criteria
+  3. brownfield grounding and integration details
 - Stay on the same thread when the answer is still weak instead of rotating dimensions just for coverage.
 - Revisit at least one earlier answer with an explicit assumption, evidence, or tradeoff follow-up before crystallizing.
 - If the task is too large for one coherent spec, decompose it before pretending it is ready.
@@ -111,6 +123,45 @@ When an answer is still weak, prefer one of these next:
 4. If the answer is still describing symptoms, reframe toward root cause.
 </Pressure_Patterns>
 
+<Socratic_Questioning>
+`clarify` should be Socratic without being vague.
+
+- Ask one focused round at a time.
+- Prefer bounded choices when they reduce user effort:
+  - use single-choice when one answer should drive the next branch
+  - use multi-choice when several constraints, non-goals, or success checks may all apply
+  - include `Other` only when the known options are likely incomplete
+- Lead with the recommended option when repo evidence or prior answers support it, but make the tradeoff visible.
+- Do not hide a branching interview tree inside one overloaded question. If an option would require a follow-up, ask that follow-up next.
+- After each answer, decide whether the next highest-value move is:
+  - deeper pressure on the same thread
+  - zooming out to another unresolved breadth track
+  - crystallizing the spec
+</Socratic_Questioning>
+
+<Breadth_Ledger>
+Maintain a lightweight breadth ledger across independent ambiguity tracks:
+
+- scope
+- constraints
+- outputs / deliverables
+- verification and success criteria
+- brownfield integration
+- user-mentioned workstreams or stakeholder requirements
+
+The ledger is a guard, not a rotation rule. Stay deep on the current thread until it has been pressure-tested, then zoom out only when another material track remains unresolved and would change downstream execution.
+</Breadth_Ledger>
+
+<Challenge_Modes>
+Use these assumption stress tests when applicable:
+
+- **Contrarian**: challenge a core assumption when an answer rests on an untested belief.
+- **Simplifier**: probe the smallest viable first pass when scope expands faster than outcome clarity.
+- **Ontologist**: reframe toward essence/root cause when the user keeps describing symptoms or when ambiguity stalls.
+
+Track which challenge modes have been used in the ambiguity register. Do not repeat a mode mechanically.
+</Challenge_Modes>
+
 <Design_Shaping>
 `clarify` should not stop at “what do you want?” Once the intent is understandable, it should also shape the task enough that the downstream plan is not starting from zero.
 
@@ -120,10 +171,51 @@ When there is a real design choice:
 - lead with the recommended one
 - explain tradeoffs briefly
 - right-size the design to the task
+- identify likely component boundaries, data flow, or user-facing flow when that would materially affect planning
+- reject speculative features unless they are necessary for the stated outcome
 
 The goal is not to produce a full architecture doc here. The goal is to make the clarify spec design-ready.
 </Design_Shaping>
 
+<Incremental_Validation>
+For non-trivial designs, validate the design in small sections before writing the final clarify spec.
+
+Present a compact design summary and ask whether it matches the user's intent. When relevant, validate these sections separately:
+
+- user-facing behavior or workflow
+- component boundaries / ownership
+- data flow or API contract
+- error handling and edge cases
+- test and verification shape
+- explicitly deferred work
+
+If the user rejects a section, continue the interview loop instead of writing a handoff-ready spec.
+</Incremental_Validation>
+
+<Practical_Closure_Audit>
+Treat a low ambiguity score as permission to audit closure, not as automatic permission to stop.
+
+Before crystallizing, ask:
+
+- Would one more question materially change implementation, test strategy, or scope?
+- Are non-goals and decision boundaries explicit enough for downstream agents?
+- Has at least one assumption or tradeoff been pressure-tested?
+- Is remaining uncertainty residual risk rather than actionable ambiguity?
+
+If remaining uncertainty would not change execution, crystallize the spec and preserve it as residual risk instead of opening a low-value branch.
+</Practical_Closure_Audit>
+
+<Spec_Self_Review>
+Before marking a clarify spec handoff-ready, perform a self-review pass:
+
+- remove placeholders such as `TBD`, `TODO`, `REPLACE_ME`, or vague “etc.”
+- check for internal contradictions
+- check whether the scope is still too broad for one coherent execution package
+- check whether any requirement can be interpreted two materially different ways
+- verify that non-goals, decision boundaries, acceptance criteria, and residual risks are explicit
+- verify that brownfield evidence is labeled separately from inference
+</Spec_Self_Review>
+
 <Process>
 
 ## 1. Explore Context
@@ -131,12 +223,22 @@ The goal is not to produce a full architecture doc here. The goal is to make the
 - Read relevant files, docs, and current patterns first.
 - Classify the work as brownfield or greenfield.
 - For brownfield work, collect concrete evidence before questioning.
+- Create or update a compact context snapshot for the task when the conversation, source docs, or repo evidence would otherwise be too large to carry safely.
 
 ## 2. Interview
 
 - Ask one question per round.
+- Prefer bounded choices for known option spaces; use open-ended questions only when the valid answers cannot be enumerated.
+- Before asking each question, show a compact status line with:
+  - `round`: current round and max rounds
+  - `ambiguity_score`: current score
+  - `target`: selected profile threshold
+  - `open_items`: unresolved ambiguity count
+- Also state the current focus dimension and whether the round is fact confirmation or human judgment.
+- After the user answers and the round is updated, show the revised `ambiguity_score`, whether it moved up/down/unchanged, and the main reason for that change before asking the next question.
 - After each answered round, update `current_round`, the ambiguity register, and `ambiguity_score`.
-- Target the weakest unresolved dimension.
+- Target the weakest unresolved dimension within the stage-priority order.
+- Maintain the breadth ledger; do not rotate dimensions just for coverage.
 - Keep `Non-goals` and `Decision Boundaries` explicit from early in the process.
 - Respect the selected profile:
   - `standard`: stop only when the clarify spec is handoff-ready or `15` rounds are exhausted
@@ -154,12 +256,19 @@ The goal is not to produce a full architecture doc here. The goal is to make the
 - Where needed, propose a small set of options.
 - Recommend one approach.
 - Clarify what that approach implies for scope and downstream execution.
+- Apply incremental validation for non-trivial designs before finalizing the spec.
+
+## 4.5. Closure and Self-Review
+
+- Run the practical closure audit.
+- Run the spec self-review checklist before marking handoff-ready.
+- If the round cap is reached or the user chooses to proceed despite ambiguity, preserve an explicit residual-risk warning in the spec and handoff recommendation.
 
 ## 5. Write the Clarify Spec
 
 Write the output to the loopx runtime namespace:
 
-- `.loopx/specs/clarify-<slug>-<timestamp>.md`
+- `.loopx/intake/clarify-<slug>-<timestamp>.md`
 
 The clarify spec should include:
 
@@ -179,19 +288,28 @@ The clarify spec should include:
 - constraints
 - success criteria
 - assumptions exposed and resolved
+- pressure-pass findings
 - brownfield evidence vs inference
+- breadth ledger / unresolved tracks, if any
 - design direction / preferred approach
+- residual risks
 - explicit next handoff recommendation
 
 ## 6. Handoff
 
 After the clarify spec is ready:
 
-- hand off to `plan` by default
-- hand off to `build` only if the user explicitly wants direct execution and the task is already concrete enough
-- hand off to `autopilot` only when the scope is sufficiently tight for a bounded end-to-end run
+- hand off to `plan`; do not start implementation, TDD, `build`, or `autopilot` from `clarify`
+- if the user asks to execute immediately, explain that loopx requires the `plan` gate first and provide the plan invocation
+- if a task is too small to justify planning, do not use `clarify`; handle that request outside the clarify workflow from the start
+
+Preferred explicit handoff contract:
+
+- Recommended invocation: `$plan <slug>`
+- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
+- Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
-`clarify` itself does not implement the feature.
+`clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.
 
 </Process>
 
@@ -199,6 +317,8 @@ After the clarify spec is ready:
 - `Non-goals` are explicit
 - `Decision Boundaries` are explicit
 - At least one pressure-pass follow-up has revisited an earlier answer
+- The practical closure audit has passed
+- The spec self-review pass has removed placeholders, contradictions, and material ambiguity
 - A written clarify spec exists
 - The task is small enough and clear enough for real downstream handoff
 - The selected profile threshold is met:
@@ -208,6 +328,7 @@ After the clarify spec is ready:
 
 <Must_Not_Decide_Automatically>
 - approval to move from clarify into plan
+- skipping `plan` after producing a clarify spec
 - implementation details that were never clarified or grounded
 - widening the task because a broader redesign sounds cleaner
 </Must_Not_Decide_Automatically>