@donghyeonlee/jjamppong-harness 0.1.0

package/harness/rules/rules.md

@@ -0,0 +1,220 @@
+# Harness Rules
+
+This file is a projection of FINAL-PLAN and the machine-readable contracts.
+
+The permission source of truth is:
+
+```text
+1. FINAL-PLAN.md in the build pack, while rebuilding this template
+2. harness/contracts/*.yaml
+3. active task events.jsonl
+4. PermissionDecision output
+```
+
+`AGENTS.md`, this file, `workflow.md`, `gate-ledger.md`, and `task.yaml` may restrict behavior further, but they must not grant permission beyond the contracts and canonical events.
+
+## Hard Defaults
+
+- Missing capability: deny.
+- Ambiguous scope: deny.
+- Short approval expansion: deny.
+- Secrets: deny.
+- Live target access: deny until explicit capability approval.
+- Package install: deny until explicit capability approval.
+- Git commit/push: deny until separate git approvals.
+- Harness-core writes in product tasks: deny; create proposal instead.
+- Parallel active write: deny until explicit parallel approval.
+
+## Artifact Language Policy
+
+Human-facing artifacts use the user's language.
+
+Static templates may use Korean starter copy. This phase does not add lifecycle-level localization. Agents write live human-facing artifacts in the current user's language when presenting or updating them.
+
+Machine-readable artifacts keep stable schema keys.
+
+`events.jsonl`, `task.yaml`, contracts, and PermissionDecision outputs keep stable machine-readable keys.
+
+events.jsonl, task.yaml, contracts, and PermissionDecision outputs keep stable machine-readable keys.
+
+`gate-ledger.md`, planning artifacts, `archive-summary.md`, `verification.md`, and `handoff.md` are human-facing.
+
+gate-ledger.md, planning artifacts, archive-summary.md, verification.md, and handoff.md are human-facing.
+
+## Required Reads For Substantive Work
+
+Read these before any substantive write:
+
+```text
+harness/contracts/gate-contract-matrix.yaml
+harness/contracts/capability-catalog.yaml
+harness/contracts/task.schema.yaml
+harness/contracts/permission-decision.schema.yaml
+harness/rules/workflow.md
+harness/state/planning.md
+active task events.jsonl, if one exists
+active task task.yaml, if one exists
+```
+
+If required files are missing or contradictory, stop and run verify/doctor.
+
+## Red Lines
+
+Stop immediately if a step would require:
+
+```text
+README-first rewrite
+AGENTS-first rewrite
+old v1-v13 source-history as active instruction over FINAL-PLAN
+project file read before grill in product planning
+install-to-planning continuation
+docs-first route
+plan_review completed as implementation approval
+module_structure creating folders
+folder_skeleton creating code/tests/fixtures/runtime config
+"좋아" as broad approval
+product code outside modules without exact outside_modules_write approval
+harness-core edit in product task
+live target access without network.live_target approval
+secret read
+package install without package.install approval
+git commit/push without separate approval
+doctor/update live-editing core rules by default
+```
+
+## PermissionDecision Preflight
+
+Before risky actions, run or reason through PermissionDecision.
+
+Risky actions include file read/write/delete/move/symlink, command exec, tests/builds, network, package operations, git operations, installer/update/repair, harness-core changes, and parallel writes.
+
+The decision must name:
+
+```text
+requested action
+capability
+allow/deny/block/proposal_required
+reason
+matched event ids
+paths or targets covered
+required next action
+```
+
+If the decision is not `allow`, do not perform the action.
+
+## Event Log And Projections
+
+Canonical task state lives in:
+
+```text
+harness/docs/tasks/active/<slug>/events.jsonl
+```
+
+Derived projections:
+
+```text
+gate-ledger.md = human-readable projection
+task.yaml = compact cache
+planning-pack.md = final decision manifest
+```
+
+If `task.yaml` or `gate-ledger.md` says something is approved but `events.jsonl` does not contain the approval, verification fails and the gate stays locked.
+
+Doctor may regenerate projections from canonical events, but it must not invent approvals.
+
+## Gate Question Format
+
+Every gate question must state:
+
+- Gate id
+- Approval scope
+- Artifact or decision being approved
+- Capabilities being allowed
+- Paths or targets being covered
+- This unlocks
+- This remains locked
+- Deferred unknowns requiring separate approval
+
+If the question omits these fields, a short affirmative answer must not open the gate.
+
+Ask in the user's language. If the user writes Korean, ask in Korean and briefly explain technical labels in plain language.
+
+## Workflow Boundaries
+
+`install` stops after install and verify.
+
+`grill` comes before project reads.
+
+`research` comes after grill and may use general web research, not live target access.
+
+`evidence_check` is a legacy alias for `research` only. Prefer `research` or Korean `자료조사` in user-facing gates.
+
+`prd` comes after grill/research.
+
+`issues` comes after approved PRD.
+
+`module_structure` does not create folders.
+
+Plain rule: module_structure does not create folders.
+
+`folder_skeleton` does not create executable files.
+
+Plain rule: folder_skeleton does not create executable files.
+
+`plan_review` does not unlock implementation.
+
+Plain rule: plan_review does not unlock implementation.
+
+`implementation` records exact-scope capability approval.
+
+`work` uses only approved capabilities and paths.
+
+`verification` does not create new feature scope.
+
+`archive` requires archive-summary.
+
+## Module Boundaries
+
+Product code belongs under:
+
+```text
+modules/<module>/**
+```
+
+Writes outside `modules/` require exact `file.write.outside_modules` approval with specific paths and reason.
+
+`module_bootstrap` and `product_feature` are separate task types. Bootstrap creates the workspace only; feature work starts as a new task after bootstrap is verified and archived.
+
+## Installer / Update / Doctor
+
+Installer must create the harness directly under the target root and write `harness.lock.yaml`.
+
+Installer must not create nested template folders, planning artifacts, product code, GitHub repos, commits, or pushes.
+
+`verify` is read-only pass/fail.
+
+`doctor` is read-only diagnosis by default.
+
+`doctor --proposal`, `update`, and `repair` create proposals by default when managed files changed. They must not live-edit harness-core rules without explicit approval.
+
+## Archive And Handoff
+
+Archive is cold context. Read indexes and summaries before detailed archived artifacts.
+
+Root `handoff.md` is updated only when the user asks for handoff or new-chat transfer.
+
+## Handoff Response
+
+Root `handoff.md` is updated only when the user asks for handoff or new-chat transfer.
+
+When creating handoff.md, do not embed the restart prompt in the file by default.
+
+After creating handoff.md, return a copy-paste next-chat prompt in the chat response.
+
+Use this Korean prompt when the user is working in Korean:
+
+```text
+handoff.md 보고 이어서 진행해줘.
+먼저 AGENTS.md, harness/rules/workflow.md, 현재 active task의 task.yaml/events.jsonl을 확인해줘.
+현재 gate 상태를 확인한 뒤, 바로 구현하지 말고 필요한 다음 단계부터 이어서 진행해줘.
+```

package/harness/rules/workflow.md

@@ -0,0 +1,252 @@
+# Workflow
+
+This file is a human-readable projection of:
+
+```text
+harness/contracts/gate-contract-matrix.yaml
+harness/contracts/capability-catalog.yaml
+harness/contracts/task.schema.yaml
+```
+
+If this file conflicts with the contracts, the contracts win.
+
+## User-Facing Flow
+
+Explain the workflow to users in simple Korean when they write in Korean.
+
+```text
+1. 설치만 하기
+2. 만들고 싶은 것 질문하기
+3. 자료조사하기
+4. 기획/이슈/구조/계획 세우기
+5. 진짜 작업 범위 승인받기
+6. 승인된 범위만 작업하기
+7. 검증하고 사용자 확인받기
+8. 배운 점 정리하고 보관하기
+```
+
+Do not show every internal gate first. Show the simple label and the internal gate id when asking for approval.
+
+## Artifact Language Policy
+
+Human-facing artifacts use the user's language.
+
+Human-facing artifacts include `gate-ledger.md`, planning artifacts, `archive-summary.md`, `verification.md`, and `handoff.md`.
+
+gate-ledger.md, planning artifacts, archive-summary.md, verification.md, and handoff.md are human-facing.
+
+Static templates may use Korean starter copy. This phase does not add lifecycle-level localization. When an agent presents or updates live human-facing artifacts, the agent writes them in the current user's language.
+
+Agents write live human-facing artifacts in the current user's language.
+
+Machine-readable artifacts keep stable schema keys.
+
+Machine-readable artifacts include `events.jsonl`, `task.yaml`, contracts, and PermissionDecision outputs. events.jsonl, task.yaml, contracts, and PermissionDecision outputs keep stable machine-readable keys.
+
+## Canonical Gate Order
+
+```text
+install
+-> intake
+-> grill
+-> research
+-> compound_lookup
+-> architecture_orientation
+-> prd
+-> issues
+-> module_structure
+-> compile_current_planning_context
+-> writing_plan
+-> plan_review
+-> folder_skeleton, if needed
+-> implementation
+-> work
+-> verification
+-> acceptance
+-> compound_capture
+-> compound_review
+-> proposal, if needed
+-> archive
+-> handoff, only if requested
+```
+
+`research` is canonical. `evidence_check` is a legacy alias only.
+
+## Install Gate
+
+Install means install and verify, then stop.
+
+Install must not start planning, create active product tasks, create modules, create code/tests/fixtures, access live targets, install packages beyond the installer itself, create GitHub repos, commit, or push.
+
+The installed project root must contain:
+
+```text
+AGENTS.md
+README.md
+CONTEXT.md
+handoff.md
+harness/
+modules/
+module-template/
+proposals/
+harness.lock.yaml
+```
+
+Nested `jjamppong-harness/` or `ourosuper-harness/` install results are invalid.
+
+## Grill Before Read
+
+Product/task planning starts with `grill`.
+
+Before `grill`, do not scan existing project files, old docs, source history, candidate lists, or prior implementation folders as if they were user intent.
+
+After `grill`, `research` may read approved project evidence and general web research. General web research does not authorize live target access.
+
+## Planning Gates
+
+PRD comes after `grill` and `research`.
+
+`issues` comes after approved PRD.
+
+`module_structure` comes after PRD/issues and organizes implementation. It does not create folders.
+
+`writing_plan` reads `planning/00-current-planning-context.md` and the approved planning artifacts. It does not read every raw log by default.
+
+`plan_review` reviews the plan.
+
+Important:
+
+```text
+plan_review completed != implementation approved
+```
+
+Plan review completion only opens the implementation approval question.
+
+## Folder Skeleton
+
+`folder_skeleton` is a separate gate.
+
+It may create approved empty folders, `.gitkeep`, and approved non-executable placeholder docs.
+
+It must not create source code, tests, fixtures, runtime config, dependency manifests, package files, crawlers, extractors, evaluators, live access code, or git operations.
+
+## Implementation And Work
+
+`implementation` records the exact-scope approval.
+
+`work` performs only actions allowed by PermissionDecision.
+
+Every risky action needs a capability:
+
+```text
+file.read.project
+file.read.archive
+file.read.raw_artifact
+file.read.secret
+file.write.task_artifact
+file.write.folder_skeleton
+file.write.module
+file.write.outside_modules
+file.write.harness_core
+file.delete
+file.move
+file.symlink
+exec.readonly_info
+exec.test
+exec.build
+exec.mutating
+exec.destructive
+exec.networked
+network.web_research
+network.live_target
+network.package_registry
+network.authenticated
+package.install
+package.update
+git.commit
+git.push
+git.remote_change
+installer.install
+installer.update
+installer.repair
+installer.rollback
+harness.core_change
+project.policy_change
+parallel.write
+```
+
+Missing or ambiguous capability defaults to deny.
+
+## Approval Rule
+
+Approval is a relationship, not a word list.
+
+A short affirmation such as "좋아" approves only the exact scope in the immediately preceding explicit gate question.
+
+It never adds code, tests, fixtures, live target access, package install, git commit, git push, outside module writes, or harness-core changes unless those were explicitly named as allowed in that question.
+
+Approval evidence must be recorded in:
+
+```text
+events.jsonl
+```
+
+`gate-ledger.md` is only a human-readable projection.
+
+`task.yaml` is only a derived cache.
+
+If projections disagree with `events.jsonl`, verification fails and `events.jsonl` wins.
+
+## Approval Invalidation
+
+Downstream approvals are invalidated when scope changes:
+
+```text
+PRD goal/success criteria/excluded scope
+issue set
+module path or boundary
+writing_plan target files
+target path or glob
+live/package/git/secret/outside_modules requirement
+new user restriction
+source artifact hash mismatch
+harness core rule changes
+```
+
+When uncertain, fail closed and ask a narrower gate question.
+
+## Task Types
+
+Task type must be explicit in `task.yaml` and `events.jsonl`.
+
+```text
+install
+module_bootstrap
+product_feature
+product_bugfix
+template_maintenance
+project_policy_change
+harness_update
+knowledge_maintenance
+archive_maintenance
+```
+
+`module_bootstrap` creates a module/workspace only. It must not create product source code, tests, fixtures, executable config, dependency manifests, live access, package install, commit, or push.
+
+After module bootstrap is verified and archived, actual feature work starts as a new product task with `grill` again.
+
+## Verification, Acceptance, Archive
+
+Verification records commands, expected/actual results, exit codes, and risk status.
+
+Verification must not add new feature work. A failed verification that requires product changes re-enters an approved work path.
+
+Archive requires `archive-summary.md`.
+
+Archive is cold context. Future tasks read indexes and summaries before detailed archived artifacts.
+
+`handoff.md` is updated only when the user asks for a new-chat handoff.
+
+handoff.md is a status summary, not the restart prompt container.
+
+The next-chat prompt is returned in the chat response.

package/harness/state/compound.md

@@ -0,0 +1,7 @@
+# Compound State
+
+No reusable learning has been captured for this project yet.
+
+Reusable learning belongs under `harness/docs/solutions/`.
+
+This file stores only a short index of reusable learning documents.

package/harness/state/intake.md

@@ -0,0 +1,11 @@
+# Request Intake
+
+No active request has been recorded for this project yet.
+
+When a substantive user request starts, record:
+
+- User Request
+- Plain-Language Interpretation
+- Workflow Decision
+- Required Plugins Or Skills
+- Current Blockers

package/harness/state/module-structure.md

@@ -0,0 +1,13 @@
+# Module Structure
+
+No project module structure has been approved.
+
+Module types and folder standards must be approved through the Module Structure Gate in the Full Workflow before product modules are created.
+
+When approved, record:
+
+- Project Module Types
+- Folder Set For Each Module Type
+- Active Modules
+- Deferred Modules
+- Extra Folders And Reasons

package/harness/state/planning.md

@@ -0,0 +1,21 @@
+# Planning State
+
+No active task is in progress.
+
+When a task starts, record:
+
+- Active Task Slug
+- Current Gate
+- Canonical Event Log
+- Gate Ledger Projection
+- Task YAML Cache
+- Current Allowed Capability Scope
+- Next Locked Gate
+
+Task-specific gate approvals belong in `harness/docs/tasks/active/<slug>/events.jsonl`.
+
+`gate-ledger.md` is a human-readable projection.
+
+`task.yaml` is a derived cache.
+
+This state file points to the active task only. It is not the source of truth for gate approvals or permissions.

package/harness/templates/module/module-state.md

@@ -0,0 +1,13 @@
+# Module State
+
+Current state for this module.
+
+This file is not a full archive. Keep it short and current.
+
+## Purpose
+
+## Current Interfaces
+
+## Current Risks
+
+## Last Verified

package/harness/templates/task/archive-summary.md

@@ -0,0 +1,19 @@
+# 보관 요약
+
+active task를 archive로 옮기기 전에 작성하는 사람용 요약입니다.
+
+## 결과
+
+- 상태:
+- 사용자 확인:
+- 미룬 일:
+- 막힌 일:
+
+## 다시 쓸 수 있는 배움
+
+- 아직 없음
+
+## 원본 해시
+
+| 산출물 | 해시 |
+| --- | --- |

package/harness/templates/task/events.jsonl.template

@@ -0,0 +1 @@
+{"event_type":"template_only","note":"Do not copy this line into a live task. A live events.jsonl starts empty and is append-only."}

package/harness/templates/task/gate-ledger.md

@@ -0,0 +1,21 @@
+# 승인 기록
+
+이 파일은 사람이 읽기 쉽게 정리한 승인 기록입니다.
+
+원본 기록:
+
+```text
+events.jsonl
+```
+
+이 파일만 보고 권한을 판단하지 마세요. 실제 권한 판단은 `events.jsonl`, contracts, PermissionDecision을 기준으로 합니다.
+
+## 현재 상태
+
+- 현재 단계:
+- 마지막으로 승인된 것:
+- 아직 잠긴 것:
+
+## 승인 내역
+
+아직 기록된 승인 내역이 없습니다.

package/harness/templates/task/implementation-approval.md

@@ -0,0 +1,11 @@
+# 구현 승인 요약
+
+이 파일은 사람이 읽기 위한 승인 요약입니다.
+
+실제 승인 근거는 반드시 `events.jsonl`에 있어야 합니다.
+
+## 승인 범위
+
+- 허용된 작업:
+- 허용된 경로:
+- 아직 잠긴 작업:

package/harness/templates/task/planning/00-current-planning-context.md

@@ -0,0 +1,3 @@
+# 현재 기획 맥락
+
+writing_plan이 읽을 압축된 현재 맥락입니다.

package/harness/templates/task/planning/01-grill-summary.md

@@ -0,0 +1,3 @@
+# 사용자 의도 질문 요약
+
+사용자가 원하는 결과, 제외 범위, 성공 기준을 정리합니다.

package/harness/templates/task/planning/02-research-summary.md

@@ -0,0 +1,3 @@
+# 자료조사 요약
+
+승인된 자료조사 결과와 근거를 정리합니다.

package/harness/templates/task/planning/02b-compound-lookup.md

@@ -0,0 +1,3 @@
+# Compound 조회
+
+관련 과거 배움이나 패턴을 정리합니다.

package/harness/templates/task/planning/02c-architecture-orientation.md

@@ -0,0 +1,3 @@
+# 아키텍처 방향
+
+필요한 경우 PRD 확정 전에 기술적 모양을 사용자 언어로 설명합니다.

package/harness/templates/task/planning/03-prd.md

@@ -0,0 +1,3 @@
+# PRD
+
+제품 요구사항과 성공 기준을 정리합니다.

package/harness/templates/task/planning/04-issues.md

@@ -0,0 +1,3 @@
+# 이슈
+
+독립적으로 진행 가능한 작업 단위를 정리합니다.

package/harness/templates/task/planning/05-module-structure.md

@@ -0,0 +1,3 @@
+# 모듈 구조
+
+구현을 어디에 둘지 정리합니다. 이 문서는 폴더 생성을 승인하지 않습니다.

package/harness/templates/task/planning/06-writing-plan.md

@@ -0,0 +1,3 @@
+# Writing Plan
+
+구현 계획을 정리합니다. 이 문서는 구현 승인이 아닙니다.

package/harness/templates/task/planning/07-plan-review.md

@@ -0,0 +1,3 @@
+# 계획 리뷰
+
+CEO, 엔지니어링, 준수 관점의 리뷰 결과를 정리합니다.

package/harness/templates/task/planning-pack.md

@@ -0,0 +1,23 @@
+# Planning Pack
+
+이 파일은 최종 결정 manifest입니다. raw transcript를 누적하지 않습니다.
+
+## 현재 결정
+
+- 목표:
+- 제외 범위:
+- 성공 기준:
+- 승인된 다음 단계:
+
+## 읽어야 할 세부 산출물
+
+- planning/00-current-planning-context.md
+- planning/01-grill-summary.md
+- planning/02-research-summary.md
+- planning/02b-compound-lookup.md
+- planning/02c-architecture-orientation.md
+- planning/03-prd.md
+- planning/04-issues.md
+- planning/05-module-structure.md
+- planning/06-writing-plan.md
+- planning/07-plan-review.md

package/harness/templates/task/task.yaml

@@ -0,0 +1,10 @@
+task_id: "{{task_id}}"
+task_type: "{{task_type}}"
+status: active
+current_gate: intake
+canonical_event_log: events.jsonl
+human_projection: gate-ledger.md
+cache_projection: task.yaml
+planning_pack: planning-pack.md
+created_at: "{{created_at}}"
+updated_at: "{{updated_at}}"