@ps-neko/nekowork 0.1.0-alpha.0

package/rules/typescript/testing.md

@@ -0,0 +1,78 @@
+# typescript/testing — TS/JS 테스트 룰
+
+> [common/testing.md](../common/testing.md) 의 TS/JS 확장.
+
+## 1. 프레임워크
+
+- 단위 / 통합: **node:test** (repo default). Vitest 는 필요할 때 프로젝트별 devDependency 로 추가.
+- E2E: **Playwright**.
+- 노드 코어 스크립트(`scripts/`): `node --test` 로 충분.
+
+## 2. 파일 위치
+
+- 단위: `tests/unit/<area>.test.js` (이 레포는 ESM `.js`).
+- 통합: `tests/integration/<scenario>.test.js`.
+- E2E: `tests/e2e/<flow>.spec.ts`.
+- 픽스처: `tests/fixtures/<area>/`.
+
+## 3. node:test 패턴
+
+```js
+import { test, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+beforeEach(() => { /* reset */ });
+
+test('router: critical routes to opus', () => {
+  assert.equal(route({ severity: 'critical' }), 'opus');
+});
+```
+
+- table case 는 배열 + `for ... of` 로 작성.
+- 모듈 mock 이 꼭 필요하면 테스트 대상의 의존성 주입 경계를 먼저 검토.
+
+## 4. node:test 실행
+
+이 레포의 `tests/unit/*.test.js` 는 다음 형태:
+
+```js
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { route } from '../../scripts/lib/router.js';
+
+test('router: critical → opus', () => {
+  assert.equal(route({ severity: 'critical' }), 'opus');
+});
+```
+
+실행: `node --test tests/unit/*.test.js`.
+
+## 5. 모킹
+
+- 외부 의존(SDK, 네트워크) 만 mock. 자체 모듈은 가능한 한 실 구현.
+- mock 함수가 필요하면 `node:test` 의 `mock.fn()` 또는 작은 fake 구현을 사용.
+- `nock` / `msw` 로 HTTP 모킹.
+
+## 6. 비동기 테스트
+
+- `async () => { ... }` 로 작성, await 누락 방지.
+- 타임아웃 명시 (`{ timeout: 10000 }`) — 기본 5000ms 보다 길어야 하면 이유 주석.
+
+## 7. E2E (Playwright)
+
+- 파일: `tests/e2e/<flow>.spec.ts`.
+- Trace + 스크린샷 + 비디오 자동 첨부 (`use: { trace: 'retain-on-failure' }`).
+- CI 에서 워커 1, 로컬에서 multiple OK.
+- 데이터: 격리된 테스트 사용자 또는 세션.
+
+## 8. 커버리지
+
+- Node/V8 coverage: `node --test --experimental-test-coverage tests/unit/*.test.js`.
+- v8 또는 istanbul 기반 라인 80% 이상.
+- `coverage/` 는 `.gitignore`. `lcov.info` 만 CI 아티팩트로.
+
+## 9. 에이전트 지원
+
+- 새 기능 / 버그 수정: `tdd-guide` 에이전트 (skills/tdd-workflow).
+- E2E 흐름: `e2e-runner` 에이전트.
+- 실패 분석: `debugger` 에이전트.

package/schemas/agent-yaml.schema.json

@@ -0,0 +1,168 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/agent-yaml.schema.json",
+  "title": "agent.yaml (gitagent/0.1.0)",
+  "description": "단일 매니페스트. ECC gitagent 스펙 차용 + HARNESS 확장.",
+  "type": "object",
+  "required": ["spec_version", "name", "version", "description"],
+  "additionalProperties": false,
+  "properties": {
+    "spec_version": { "type": "string", "const": "gitagent/0.1.0" },
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "runtime_name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-z0-9.-]+)?$" },
+    "description": { "type": "string", "minLength": 10 },
+    "license": { "type": "string" },
+    "homepage": { "type": "string", "format": "uri" },
+    "authors": { "type": "array", "items": { "type": "string" } },
+
+    "agents": { "type": "array", "items": { "type": "string" } },
+    "skills": { "type": "array", "items": { "type": "string" } },
+    "commands": { "type": "array", "items": { "type": "string" } },
+
+    "hooks": {
+      "type": "object",
+      "required": ["file"],
+      "additionalProperties": false,
+      "properties": {
+        "file": { "type": "string" },
+        "toggles_env_prefix": { "type": "string" },
+        "active": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+
+    "mcp": {
+      "type": "object",
+      "required": ["gateway"],
+      "additionalProperties": false,
+      "properties": {
+        "gateway": { "type": "string" },
+        "external_servers": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string" },
+              "pin": { "type": "string" },
+              "type": { "enum": ["stdio", "http"] },
+              "url": { "type": "string", "format": "uri" }
+            }
+          }
+        }
+      }
+    },
+
+    "harnesses": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "output_dir", "builder"],
+        "additionalProperties": true,
+        "properties": {
+          "name": { "type": "string" },
+          "output_dir": { "type": "string" },
+          "builder": { "type": "string" },
+          "config_format": { "enum": ["json", "toml", "yaml", "summary"] },
+          "plugin_manifest": { "type": "string" },
+          "event_adapter": { "enum": ["required", "optional", "none"] },
+          "output_format": { "type": "string" }
+        }
+      }
+    },
+
+    "profiles": {
+      "type": "object",
+      "required": ["default", "available"],
+      "additionalProperties": false,
+      "properties": {
+        "default": { "type": "string" },
+        "available": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+
+    "modules": { "type": "array", "items": { "type": "string" } },
+
+    "build": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "prepack": { "type": "array", "items": { "type": "string" } },
+        "post_install": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+
+    "verification": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "catalog_validators": { "type": "array", "items": { "type": "string" } },
+        "marker_check": { "type": "string" },
+        "required_coverage_pct": { "type": "number", "minimum": 0, "maximum": 100 }
+      }
+    },
+
+    "security": {
+      "type": "object",
+      "additionalProperties": true
+    },
+
+    "auth": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["delegated-first", "oauth-first", "vault-only"] },
+        "token_store": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "kind": { "enum": ["encrypted-file", "os-keychain"] },
+            "path": { "type": "string" },
+            "fallback": { "enum": ["encrypted-file", "os-keychain"] }
+          }
+        },
+        "providers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "required": ["flow"],
+            "additionalProperties": false,
+            "properties": {
+              "flow": { "enum": ["delegated_cli_auth", "oauth_device", "oauth_pkce", "api_key_vault"] },
+              "command": { "type": "string" },
+              "auth_check": { "type": "string" },
+              "disallow_env_keys": { "type": "array", "items": { "type": "string" } },
+              "scopes": { "type": "array", "items": { "type": "string" } },
+              "client_id_env": { "type": "string" },
+              "vault_key": { "type": "string" },
+              "fallback": { "enum": ["delegated_cli_auth", "oauth_device", "oauth_pkce", "api_key_vault"] }
+            }
+          }
+        },
+        "policy": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "block_subscription_override": { "type": "boolean" },
+            "require_human_approval_for_scope_escalation": { "type": "boolean" },
+            "redact_tokens_in_audit": { "type": "boolean" },
+            "deny_static_api_keys_in_repo": { "type": "boolean" }
+          }
+        }
+      }
+    },
+
+    "routing": {
+      "type": "object",
+      "additionalProperties": true
+    },
+
+    "state": {
+      "type": "object",
+      "additionalProperties": true
+    },
+
+    "tags": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/schemas/agent.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/agent.schema.json",
+  "title": "Agent Frontmatter Schema",
+  "description": "agents/<name>.md frontmatter 검증",
+  "type": "object",
+  "required": ["name", "description", "provider", "model", "level"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 10, "maxLength": 280 },
+    "provider": { "enum": ["claude", "codex", "gemini", "auto"] },
+    "model": {
+      "type": "string",
+      "examples": ["opus", "sonnet", "haiku", "gpt-5-codex", "gemini-2.5-pro"]
+    },
+    "level": { "type": "integer", "minimum": 0, "maximum": 3 },
+    "disallowedTools": {
+      "type": "array",
+      "items": { "enum": ["Read", "Write", "Edit", "Bash", "Network", "MCP"] },
+      "uniqueItems": true
+    },
+    "trigger": { "type": "array", "items": { "type": "string" } },
+    "hand_off_to": { "type": "array", "items": { "type": "string" } },
+    "fact_forcing": { "type": "boolean" },
+    "sandbox": { "enum": ["read-only", "workspace-write", "danger"] },
+    "network_access": { "type": "boolean" },
+    "hand_off_input": { "type": "array", "items": { "type": "string" } },
+    "hand_off_output": { "type": "string" },
+    "output_schema": { "type": "string" }
+  }
+}

package/schemas/handoff.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/handoff.schema.json",
+  "title": "Handoff JSON",
+  "description": "단계 간 구조화된 핸드오프. 마크다운 5필드와 별도로 JSON 첨부 가능.",
+  "type": "object",
+  "required": ["stage", "agent", "decided", "files"],
+  "additionalProperties": false,
+  "properties": {
+    "stage": {
+      "enum": ["question-gate", "ideate", "plan", "implement", "self-review", "codex-review", "codex-challenge", "ship"]
+    },
+    "agent": { "type": "string" },
+    "round": { "type": "integer", "minimum": 1 },
+    "session_id": { "type": "string" },
+    "team_stage": {
+      "type": "string",
+      "pattern": "^team-[a-z0-9-]+$"
+    },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "duration_ms": { "type": "integer", "minimum": 0 },
+    "provider": { "enum": ["mock", "claude", "codex", "gemini", "local"] },
+    "model": { "type": "string" },
+    "profile": { "type": "string" },
+    "decided": { "type": "string", "minLength": 1 },
+    "rejected": { "type": "string" },
+    "risks": { "type": "string" },
+    "files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "remaining": { "type": "string" },
+    "issues": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Issue" }
+    },
+    "verdict": {
+      "enum": ["block", "approve_with_fixes", "approve"]
+    },
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "risk_level": {
+      "enum": ["low", "medium", "high", "critical"]
+    },
+    "questions": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "success_criteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "desc"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "desc": { "type": "string", "minLength": 1 },
+          "passes": { "type": "boolean" },
+          "source": { "type": "string" }
+        }
+      }
+    },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "requires_human_gate": {
+      "type": "boolean"
+    },
+    "prdSeed": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "diffPath": {
+      "type": "string"
+    },
+    "executionWorkspace": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "Issue": {
+      "type": "object",
+      "required": ["severity", "category", "summary"],
+      "additionalProperties": false,
+      "properties": {
+        "severity": { "enum": ["critical", "high", "medium", "low", "info"] },
+        "category": { "enum": ["security", "correctness", "performance", "style", "test", "docs"] },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 0 },
+        "claim": { "type": "string" },
+        "evidence": { "type": "string" },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 200 },
+        "why": { "type": "string" },
+        "required_fix": { "type": ["string", "null"] },
+        "suggested_fix": { "type": ["string", "null"] },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "gate_required": { "type": "boolean" }
+      }
+    }
+  }
+}

package/schemas/hooks.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/hooks.schema.json",
+  "title": "Hooks Definition Schema",
+  "description": "hooks/hooks.json 단일 정의 파일 검증",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+" },
+    "PreToolUse": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "PostToolUse": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "PreCompact": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "Stop": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "SessionStart": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "SessionEnd": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "UserPromptSubmit": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } },
+    "PostToolUseFailure": { "type": "array", "items": { "$ref": "#/$defs/HookEntry" } }
+  },
+  "$defs": {
+    "HookEntry": {
+      "type": "object",
+      "required": ["hook"],
+      "additionalProperties": false,
+      "properties": {
+        "hook": { "type": "string", "pattern": "^scripts/.*\\.(js|mjs|cjs|sh)$" },
+        "matcher": { "type": "string" },
+        "timeout_ms": { "type": "integer", "minimum": 100, "maximum": 60000 },
+        "env_toggle": { "type": "string", "pattern": "^HARNESS_HOOK_[A-Z_]+$" },
+        "comment": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/install-components.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/install-components.schema.json",
+  "title": "Install Components",
+  "type": "object",
+  "required": ["version", "components"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string" },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["type"],
+        "additionalProperties": false,
+        "properties": {
+          "type": {
+            "enum": ["rule", "rule_set", "agent", "skill", "command", "hook", "platform"]
+          },
+          "source": { "type": "string" },
+          "target": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          },
+          "marker_managed": { "type": "boolean" },
+          "event": {
+            "enum": [
+              "PreToolUse",
+              "PostToolUse",
+              "PreCompact",
+              "Stop",
+              "SessionStart",
+              "SessionEnd",
+              "UserPromptSubmit",
+              "PostToolUseFailure"
+            ]
+          },
+          "matcher": { "type": "string" },
+          "builder": { "type": "string" },
+          "output_dir": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/install-modules.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/install-modules.schema.json",
+  "title": "Install Modules",
+  "type": "object",
+  "required": ["version", "modules"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string" },
+    "modules": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["description", "components", "level"],
+        "additionalProperties": false,
+        "properties": {
+          "description": { "type": "string", "minLength": 10 },
+          "components": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*:[a-z][a-z0-9-]*$" },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "level": { "type": "integer", "minimum": 0, "maximum": 3 },
+          "required": { "type": "boolean" },
+          "depends_on": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+          },
+          "env_toggles": {
+            "type": "object",
+            "additionalProperties": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/install-profiles.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/install-profiles.schema.json",
+  "title": "Install Profiles",
+  "type": "object",
+  "required": ["version", "profiles"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string" },
+    "profiles": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "required": ["description", "modules"],
+        "additionalProperties": false,
+        "properties": {
+          "description": { "type": "string", "minLength": 10 },
+          "modules": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "defaults": { "type": "object", "additionalProperties": true },
+          "post_install_note": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/install-state.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/install-state.schema.json",
+  "title": "Install State",
+  "description": "현재 설치된 컴포넌트 상태를 영속 저장. ~/.harness/install-state.json",
+  "type": "object",
+  "required": ["version", "harness_version", "profile", "installed_at", "components"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "string" },
+    "harness_version": { "type": "string" },
+    "profile": { "type": "string" },
+    "installed_at": { "type": "string", "format": "date-time" },
+    "last_updated": { "type": "string", "format": "date-time" },
+    "components": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["installed_at", "source_sha256", "targets"],
+        "additionalProperties": false,
+        "properties": {
+          "installed_at": { "type": "string", "format": "date-time" },
+          "source_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+          "targets": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["harness", "path"],
+              "additionalProperties": false,
+              "properties": {
+                "harness": { "type": "string" },
+                "path": { "type": "string" },
+                "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/routing.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/routing.schema.json",
+  "title": "Agent Routing Decision Trace",
+  "description": ".harness/state/sessions/<id>/routing.jsonl 의 한 줄 형식",
+  "type": "object",
+  "required": ["timestamp", "stage", "input_summary", "decision"],
+  "additionalProperties": false,
+  "properties": {
+    "timestamp": { "type": "string", "format": "date-time" },
+    "stage": {
+      "enum": ["ideate", "plan", "implement", "self-review", "codex-review", "codex-challenge", "ship"]
+    },
+    "input_summary": { "type": "string", "maxLength": 280 },
+    "decision": {
+      "type": "object",
+      "required": ["agent", "model", "provider"],
+      "additionalProperties": false,
+      "properties": {
+        "agent": { "type": "string" },
+        "model": { "type": "string" },
+        "provider": { "enum": ["claude", "codex", "gemini", "auto"] },
+        "rationale": { "type": "string" }
+      }
+    },
+    "alternatives": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["agent", "model"],
+        "properties": {
+          "agent": { "type": "string" },
+          "model": { "type": "string" },
+          "rejected_because": { "type": "string" }
+        }
+      }
+    },
+    "eco_mode": { "type": "boolean" },
+    "risk_level": { "enum": ["low", "medium", "high", "critical"] },
+    "blast_radius": { "type": "integer" }
+  }
+}

package/schemas/skill.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Ps-Neko/NEKOWORK/main/schemas/skill.schema.json",
+  "title": "Skill Frontmatter Schema",
+  "description": "skills/<name>/SKILL.md frontmatter 검증",
+  "type": "object",
+  "required": ["name", "description", "origin", "level"],
+  "additionalProperties": false,
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 10, "maxLength": 280 },
+    "origin": { "type": "string", "examples": ["harness-core", "ECC", "OMC", "user"] },
+    "level": { "type": "integer", "minimum": 0, "maximum": 3 },
+    "prerequisites": { "type": "array", "items": { "type": "string" } },
+    "conflicts": { "type": "array", "items": { "type": "string" } },
+    "auto_inject_keywords": { "type": "array", "items": { "type": "string" } },
+    "tags": { "type": "array", "items": { "type": "string" } }
+  }
+}