@ai-content-space/loopx 0.1.2 → 0.1.4

package/skills/kratos/references/troubleshooting.md

@@ -0,0 +1,385 @@
+# Troubleshooting
+
+Guide for common Kratos issues and debugging techniques.
+
+## When to Use
+
+- Route override problems
+- Zero-value field issues
+- Validation errors on partial updates
+- Enum display issues
+- Debugging runtime behavior
+
+---
+
+## Route Override Issue
+
+### Problem
+
+Generic routes shadow specific routes when defined first:
+
+```protobuf
+// WRONG: specific route shadowed
+rpc GetUser(GetUserRequest) returns (User) {
+    option (google.api.http) = {get: "/v1/user/{user_id}"};  // Matches "profile"!
+}
+rpc GetProfile(GetProfileRequest) returns (Profile) {
+    option (google.api.http) = {get: "/v1/user/profile"};    // Never matched
+}
+```
+
+### Solution
+
+Define specific routes before generic ones:
+
+```protobuf
+// CORRECT: specific route first
+rpc GetProfile(GetProfileRequest) returns (Profile) {
+    option (google.api.http) = {get: "/v1/user/profile"};    // Matches first
+}
+rpc GetUser(GetUserRequest) returns (User) {
+    option (google.api.http) = {get: "/v1/user/{user_id}"};  // Matches remaining
+}
+```
+
+**Why this matters:** HTTP routers match in order. `{user_id}` is a wildcard that matches any string including "profile".
+
+---
+
+## Zero-Value Field Issue
+
+### Problem
+
+Protobuf by default omits fields with zero values (empty string, 0, false, nil):
+
+```go
+// Proto message
+message User {
+    string name = 1;
+    int32 age = 2;
+}
+
+// Response
+{name: "", age: 0}
+
+// JSON output: {}  // Empty! All fields omitted.
+```
+
+### Solution 1: EmitUnpopulated
+
+```go
+import "google.golang.org/protobuf/encoding/protojson"
+
+var MarshalOptions = protojson.MarshalOptions{
+    EmitUnpopulated: true,  // Include zero values
+}
+
+// Custom codec
+func (codec) Marshal(v interface{}) ([]byte, error) {
+    if m, ok := v.(proto.Message); ok {
+        return MarshalOptions.Marshal(m)
+    }
+    return json.Marshal(v)
+}
+```
+
+### Solution 2: anypb.New Wrapper
+
+```go
+import "google.golang.org/protobuf/types/known/anypb"
+
+payload, err := anypb.New(m)
+reply.Data = payload
+```
+
+**Note:** Adds `@type` field: `{"@type": "type.googleapis.com/...", "value": {...}}`
+
+### Solution 3: Remove omitempty
+
+```bash
+# Makefile - remove omitempty from pb.go tags
+find ./api -name '*.pb.go' -exec sed -i -e "s/,omitempty/,optional/g" {} \;
+```
+
+---
+
+## Partial Update Validation Issue
+
+### Problem
+
+Validate middleware checks all fields, but partial updates (PATCH) may only send some:
+
+```protobuf
+message UpdateUserRequest {
+    string user_id = 1 [(buf.validate.field).string.min_len = 1];  // Required
+    string name = 2 [(buf.validate.field).string.min_len = 1];     // Required
+    string email = 3 [(buf.validate.field).string.email = true];   // Required
+}
+
+// PATCH request only sends name
+{name: "John", user_id: "123", email: ""}  // Fails validation! email is required.
+```
+
+### Solution 1: Whitelist Operations
+
+Skip validation for specific operations:
+
+```go
+func WhitelistValidateMiddleware(whitelist map[string]bool) middleware.Middleware {
+    return func(handler middleware.Handler) middleware.Handler {
+        return func(ctx context.Context, req interface{}) (interface{}, error) {
+            if tr, ok := transport.FromServerContext(ctx); ok {
+                if whitelist[tr.Operation()] {
+                    return handler(ctx, req)  // Skip validation
+                }
+            }
+            // Normal validation
+            if err := validator.Validate(req); err != nil {
+                return nil, err
+            }
+            return handler(ctx, req)
+        }
+    }
+}
+
+// Usage
+whitelist := map[string]bool{
+    "/api.v1.UserService/PatchUser": true,
+}
+```
+
+### Solution 2: Manual Validation
+
+Validate only changed fields in biz layer:
+
+```go
+func (uc *UserUseCase) PatchUser(ctx context.Context, req *v1.PatchUserRequest) error {
+    // Only validate if field is set
+    if req.Name != "" && len(req.Name) < 1 {
+        return errors.New(400, "INVALID_NAME", "name too short")
+    }
+    if req.Email != "" && !isValidEmail(req.Email) {
+        return errors.New(400, "INVALID_EMAIL", "invalid email")
+    }
+}
+```
+
+---
+
+## Enum as String Issue
+
+### Problem
+
+Custom ResponseEncoder may display enums as strings instead of numbers:
+
+```protobuf
+enum Status {
+    UNKNOWN = 0;
+    ACTIVE = 1;
+}
+
+// Expected JSON: {"status": 1}
+// Actual JSON: {"status": "ACTIVE"}  // String!
+```
+
+### Solution: UseEnumNumbers
+
+```go
+var MarshalOptions = protojson.MarshalOptions{
+    EmitUnpopulated: true,
+    UseEnumNumbers:  true,  // Enums as numbers
+}
+
+type codec struct{}
+
+func (codec) Marshal(v interface{}) ([]byte, error) {
+    if m, ok := v.(proto.Message); ok {
+        return MarshalOptions.Marshal(m)
+    }
+    return json.Marshal(v)
+}
+
+func init() {
+    encoding.RegisterCodec(codec{})
+}
+```
+
+---
+
+## HTTP Proto Unsupported Scenarios
+
+### Problem
+
+Some HTTP features can't be expressed in proto:
+
+- File upload (multipart/form-data)
+- WebSocket upgrade
+- Server-Sent Events (SSE)
+- Custom authentication flows
+
+### Solution: Custom Routes
+
+```go
+func NewHTTPServer(c *conf.Server, svc *service.MyService) *http.Server {
+    srv := http.NewServer(
+        http.Address(c.Http.Addr),
+        http.Middleware(
+            recovery.Recovery(),
+            auth.Token(),
+        ),
+    )
+    
+    // Proto-generated routes
+    v1.RegisterMyServiceHTTPServer(srv, svc)
+    
+    // Custom routes (inherit middleware)
+    route := srv.Route("/")
+    route.POST("/v1/upload", svc.UploadFile)
+    route.GET("/v1/ws", svc.WebSocketHandler)
+    
+    return srv
+}
+
+func (s *MyService) UploadFile(ctx http.Context) error {
+    http.SetOperation(ctx, "/upload.v1.UploadService/Upload")
+    
+    // Use ctx.Middleware to inherit server middleware
+    h := ctx.Middleware(func(ctx context.Context, req interface{}) (interface{}, error) {
+        return s.uc.Upload(ctx, req.(*UploadRequest))
+    })
+    
+    resp, err := h(ctx, parseUploadRequest(ctx))
+    return ctx.JSON(200, resp)
+}
+```
+
+---
+
+## Debugging Tools
+
+### statsviz - Real-time Runtime Metrics
+
+Visualize Go runtime metrics in browser:
+
+```go
+import "github.com/arl/statsviz"
+
+func newApp(logger log.Logger, hs *http.Server, gs *grpc.Server) *kratos.App {
+    statsviz.RegisterDefault()  // Register /debug/statsviz/
+    
+    return kratos.New(
+        kratos.Name("my-app"),
+        kratos.Server(hs, gs),
+    )
+}
+```
+
+Access at: `http://localhost:8000/debug/statsviz/`
+
+Shows:
+- Heap allocation
+- Goroutine count
+- GC pauses
+- CPU usage
+- Scheduler latency
+
+### fgtrace - Timeline Profiler
+
+```go
+import "github.com/felixge/fgtrace"
+
+// Enable in development only (causes stop-the-world pauses)
+func init() {
+    if os.Getenv("ENV") == "dev" {
+        fgtrace.Start()
+    }
+}
+```
+
+### pprof - Standard Go Profiler
+
+Built into Kratos HTTP server:
+
+```go
+import "net/http/pprof"
+
+// Automatically available at /debug/pprof/
+// - /debug/pprof/heap - memory profile
+// - /debug/pprof/goroutine - goroutine profile
+// - /debug/pprof/profile?seconds=30 - CPU profile
+// - /debug/pprof/trace - execution trace
+```
+
+---
+
+## Common Error Patterns
+
+### Error Creation
+
+```go
+import "github.com/go-kratos/kratos/v2/errors"
+
+// Standard errors
+var ErrUserNotFound = errors.NotFound("USER_NOT_FOUND", "user not found")
+
+// With details
+func (uc *UserUseCase) GetUser(ctx context.Context, id string) (*User, error) {
+    user, err := uc.repo.FindByID(ctx, id)
+    if err != nil {
+        return nil, errors.NotFound("USER_NOT_FOUND", "user %s not found", id)
+    }
+    return user, nil
+}
+```
+
+### Error Response Format
+
+```json
+{
+    "code": 404,
+    "reason": "USER_NOT_FOUND",
+    "message": "user 123 not found",
+    "metadata": {
+        "user_id": "123"
+    }
+}
+```
+
+### Error Checking
+
+```go
+// Check error type
+if errors.Is(err, v1.ErrUserNotFound) {
+    // Handle user not found
+}
+
+// Check error code
+if se := errors.FromError(err); se.Code == 404 {
+    // Handle not found
+}
+```
+
+---
+
+## gRPC Error Mapping
+
+Kratos HTTP gateway maps HTTP status to gRPC status:
+
+| HTTP Status | gRPC Status |
+|-------------|-------------|
+| 400 | InvalidArgument |
+| 401 | Unauthenticated |
+| 403 | PermissionDenied |
+| 404 | NotFound |
+| 409 | AlreadyExists |
+| 500 | Internal |
+| 503 | Unavailable |
+
+```go
+// Create HTTP-compatible error
+errors.BadRequest("INVALID_PARAM", "invalid parameter")
+// → HTTP 400, gRPC InvalidArgument
+
+errors.Unauthenticated("TOKEN_EXPIRED", "token expired")
+// → HTTP 401, gRPC Unauthenticated
+```

package/skills/plan/SKILL.md

@@ -29,6 +29,7 @@ By default, `plan` includes the full consensus review loop formerly documented u
 - Default planning is consensus-first, not lightweight-by-default.
 - Treat the clarify spec as source of truth; do not re-interview unless the spec is incomplete or contradictory.
 - Keep planning artifact-bound: produce PRD, architecture, development plan, and test plan outputs.
+- Preserve accepted intent as durable change artifacts: proposal, spec delta, design, tasks, and artifact dependency graph.
 - Separate planning approval from execution approval.
 - Do not start implementation from `plan`.
 - Prefer a smaller executable plan over a broad plan that cannot be verified.
@@ -39,7 +40,7 @@ By default, `plan` includes the full consensus review loop formerly documented u
 Accepted inputs:
 
 - an approved loopx clarify workflow slug
-- `.loopx/specs/clarify-*.md`
+- `.loopx/intake/clarify-*.md`
 - `.omx/specs/deep-interview-*.md`
 - a direct task description when enough context is already present
 - `--direct <spec-path>` to force a specific requirements artifact
@@ -59,8 +60,8 @@ If no requirements artifact is provided, derive a task slug and run pre-context
 Before planning:
 
 1. Derive a task slug.
-2. Reuse the latest relevant `.omx/context/{slug}-*.md` snapshot when available.
-3. If none exists, create `.omx/context/{slug}-{timestamp}.md` with:
+2. Reuse the latest relevant `.loopx/context/{slug}-*.md` snapshot when available.
+3. If none exists, create `.loopx/context/{slug}-{timestamp}.md` with:
    - task statement
    - desired outcome
    - source requirements artifact
@@ -162,11 +163,19 @@ On approval, write canonical planning artifacts:
 - `.loopx/workflows/<slug>/test-plan.md`
 - `.loopx/plans/prd-<slug>.md`
 - `.loopx/plans/test-spec-<slug>.md`
+- `.loopx/changes/active/<change-id>/proposal.md`
+- `.loopx/changes/active/<change-id>/spec-delta.md`
+- `.loopx/changes/active/<change-id>/design.md`
+- `.loopx/changes/active/<change-id>/tasks.md`
+- `.loopx/changes/active/<change-id>/slices.json`
+- `.loopx/changes/active/<change-id>/artifact-graph.json`
 
 The final plan must include:
 
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
 - concrete implementation steps sized to the actual task
+- target long-lived spec domains and an OpenSpec-style requirements delta for archive
+- vertical slices sized as independently verifiable tracer bullets, not horizontal layer-only task groups
 - execution inputs mapped to concrete sources before build starts
 - available execution lanes and recommended lane
 - test and verification commands
@@ -199,6 +208,9 @@ Without `--interactive`, report the approved plan and recommended next command,
 - `plan_architect_review_status`: `not-started|complete|changes-requested`
 - `plan_critic_verdict`: `none|approve|iterate|reject`
 - `plan_package_status`: `missing|partial|complete`
+- `change_artifacts_status`: `missing|partial|complete|archived`
+- `spec_delta_status`: `missing|partial|complete`
+- `slice_artifacts_status`: `missing|partial|complete`
 - `plan_acceptance_criteria_testable`: `true|false`
 - `plan_verification_steps_resolved`: `true|false`
 - `plan_execution_inputs_resolved`: `true|false`
@@ -207,6 +219,10 @@ Without `--interactive`, report the approved plan and recommended next command,
 The plan gate is blocked until:
 
 - plan package artifacts exist
+- change proposal, spec delta, design, tasks, vertical slices, and artifact graph exist
+- spec delta declares target domains and `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` blocks
+- every ADDED or MODIFIED requirement uses `### Requirement:`, contains SHALL or MUST text, and includes at least one `#### Scenario:`
+- vertical slices contain at least one `AFK` or `HITL` end-to-end slice with acceptance criteria and verification signal
 - Architect review is complete
 - Critic verdict is `approve`
 - acceptance criteria are testable
@@ -229,6 +245,7 @@ Primary outputs:
 
 - approved plan package under `.loopx/workflows/<slug>/`
 - canonical PRD and test spec under `.loopx/plans/`
+- change artifacts under `.loopx/changes/active/<change-id>/`
 - consensus review summary with Planner / Architect / Critic evidence
 - next-step recommendation
 

package/skills/review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review
 description: Repo-local acceptance surface for loopx.
+argument-hint: "<execution-record path or workflow slug>"
 ---
 
 # loopx Review
@@ -9,21 +10,117 @@ description: Repo-local acceptance surface for loopx.
 
 Repo-local acceptance surface for loopx. Use it to evaluate the execution package from `build` and return an explicit go / no-go result.
 
+## Inputs
+
+Preferred skill input:
+
+- `.loopx/workflows/<slug>/execution-record.md`
+
+Compatible skill / CLI input:
+
+- `<slug>`
+
+When invoked with an execution record path, derive `<slug>` from the workflow directory and evaluate the matching active run.
+
 ## Expected Outputs
 
 - a review artifact tied to the run being evaluated
 - verdict and rationale
-- rollback guidance when execution is incomplete or unstable
+- code review findings for the implementation diff, including file / line references when issues are found
+- architecture-smell findings from the internal review lane, focused on module depth, test seams, domain vocabulary, duplicated rules, and plan architecture alignment
+- rollback/fix guidance when execution is incomplete, unstable, or needs another iteration
+- an explicit `Next:` block with the exact next skill command when more work remains
+
+## User Notification Language
+
+The final user-facing review result must be written in Chinese.
+
+Use stable machine values only where they are commands, file paths, JSON/state fields, or exact verdict identifiers. The human-readable summary, rationale, findings, residual risks, rollback guidance, and next-step instruction must be Chinese.
 
 ## Decision Boundary
 
 - Use this only after build has produced execution and verification evidence for a specific run.
 - Stop here if review evidence is incomplete. `review` remains an independent gate and does not auto-complete the workflow.
+- Review must include code review of the build-owned implementation diff. Do not limit review to artifact/schema checks.
+- Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
+- Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
+- Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.
+- If code review finds blocking high or medium severity issues, return a no-go verdict and rollback guidance instead of approving completion.
+- If architecture-smell findings are only advisory, record them as warnings without blocking. Block only when module seams, testability, domain boundaries, duplicated rules, or plan architecture assumptions are materially wrong.
+- Route request-changes by problem type:
+  - implementation bugs, missing tests, small contract fixes: `review -> build`
+  - wrong plan, wrong architecture, unresolved execution inputs: `review -> plan`
+  - unclear product requirements or decision boundaries: `review -> clarify`
+- Do not route implementation-only fixes back to plan unless the plan itself is wrong.
+
+## Next Step Format
+
+Every no-go review result must end with a concrete next command block.
+
+For implementation fixes:
+
+```text
+Next:
+$build --from-review .loopx/workflows/<slug>/review-report.md
+```
+
+The review artifact is the direct rework contract for implementation fixes. `$build --from-review ...` must load the review findings first, while still using the approved PRD, test spec, previous `execution-record.md`, and workflow-local plan package as supporting context. Do not make the normal Codex-facing handoff require a separate bash `loopx approve ... --from review --to build` step.
+
+For CLI/runtime debugging only, the equivalent state transition is:
+
+```bash
+loopx build --from-review .loopx/workflows/<slug>/review-report.md
+```
+
+For plan fixes:
+
+```text
+Next:
+loopx approve <slug> --from review --to plan
+$plan <slug>
+```
+
+For clarify fixes:
+
+```text
+Next:
+loopx approve <slug> --from review --to clarify
+$clarify <slug>
+```
+
+For approval:
+
+```text
+Next:
+loopx approve <slug> --from review --to done
+```
+
+After the workflow reaches `done`, run:
+
+```text
+$archive <slug>
+```
+
+This syncs the approved `.loopx/changes/active/<change-id>/spec-delta.md` into long-lived `.loopx/specs/` files and moves the change folder under `.loopx/changes/archive/<change-id>/`.
+
+## Support Skill Review Lenses
+
+Use loopx support skills as review lenses, not as implementation instructions:
+
+- `verify`: Evidence lens. Reject completion, passing, or review-ready claims that lack fresh command output and exit status.
+- `scope`: Completion lens. Reject full-completion claims when the execution record still declares remaining workflow scope or only a partial slice was implemented.
+- `tdd`: Behavior-change lens. Feature work and bug fixes should include failing-test or regression-test evidence unless the execution record explicitly explains why tests are not applicable.
+- `debug`: Failure-analysis lens. Fixes for bugs, test failures, build failures, and unexpected behavior should document root cause, not only symptoms or attempted patches.
+- `go-style`: Go diff lens. For `.go` changes, review happy-path structure, error handling, context usage, interface boundaries, naming, table tests, and `gofmt`/Go verification evidence.
+- `kratos`: Kratos diff lens. For Kratos/proto/service/biz/data/middleware/auth/config changes, review layer boundaries, generated-code flow, proto/package contracts, middleware/auth ordering, config compatibility, and project-native verification.
+
+These lenses can produce review findings when the execution package violates them. Do not run new build work from `review`; request rollback or changes instead.
 
 ## Must Not Decide Automatically
 
 - final completion without an explicit approval step
 - re-running build work inside the review surface
+- editing code or rerunning build from inside review
 
 ## Notes