@donghyeonlee/jjamppong-harness 0.1.0

package/harness/contracts/installer-contract.yaml

@@ -0,0 +1,79 @@
+version: 0.1.0
+name: installer-contract
+
+modes:
+  install:
+    behavior: install_verify_stop
+    may_modify: [harness_core_files, state_neutral_files, harness_lock]
+    must_not: [start_planning, create_product_task, create_code, run_live_access, commit, push]
+  verify:
+    behavior: read_only_pass_fail
+  doctor:
+    behavior: read_only_diagnose_plus_proposal
+    live_edit_default: false
+  update:
+    behavior: proposal_only_if_managed_files_modified
+  repair:
+    behavior: proposal_only_if_managed_files_modified
+
+ownership_classes:
+  harness_core_owned:
+    examples: [AGENTS.md, harness/rules/**, harness/contracts/**, scripts/install-jjamppong-harness.ps1]
+    update_strategy: replace_with_backup_if_clean_else_proposal
+  project_overlay_owned:
+    examples: [project-local policy files]
+    update_strategy: merge_proposal
+  user_owned:
+    update_strategy: never_overwrite
+  generated_derived:
+    examples: [task.yaml, gate-ledger.md projection, index files]
+    update_strategy: regenerate_from_canonical_when_explicit
+  append_only_canonical:
+    examples: [events.jsonl]
+    update_strategy: append_only_never_rewrite_without_repair_record
+  local_artifact:
+    examples: [harness/artifacts/local/**]
+    update_strategy: gitignored_do_not_publish
+
+fresh_install_requirements:
+  root_items:
+    - AGENTS.md
+    - README.md
+    - CONTEXT.md
+    - handoff.md
+    - harness/
+    - modules/
+    - module-template/
+    - proposals/
+    - harness.lock.yaml
+  forbidden_nested:
+    - jjamppong-harness/
+    - ourosuper-harness/
+  state:
+    active_tasks_empty: true
+    archive_empty_or_gitkeep_only: true
+    planning_state: neutral
+    handoff: neutral
+  git:
+    origin_must_not_be_template_repo: true
+    create_remote_repo_default: false
+    commit_default: false
+    push_default: false
+
+backup_rollback:
+  backup_before_overwrite: true
+  rollback_manifest_required: true
+  idempotent_install_required: true
+
+harness_lock_required_fields:
+  - harness.name
+  - harness.version
+  - installer.package
+  - installer.version
+  - installed_at
+  - installed_from
+  - planning_started
+  - github_repo_created
+  - commit_created
+  - push_performed
+  - managed_files

package/harness/contracts/ledger-event.schema.yaml

@@ -0,0 +1,79 @@
+version: 0.1.0
+name: ledger-event-schema
+canonical_log: events.jsonl
+append_only: true
+hash_chain_required: true
+
+required_fields:
+  - event_id
+  - schema_version
+  - task_id
+  - event_type
+  - created_at
+  - actor_type
+  - previous_hash
+  - event_hash
+
+fields:
+  event_id: {type: string, format: uuid_or_ulid}
+  schema_version: {type: string}
+  task_id: {type: string}
+  event_type:
+    enum:
+      - task_opened
+      - gate_question
+      - user_answer
+      - approval_decision
+      - gate_status_change
+      - artifact_written
+      - permission_decision
+      - capability_used
+      - verification_result
+      - invalidation
+      - projection_generated
+      - task_archived
+  created_at: {type: string, format: iso8601}
+  actor_type:
+    enum: [user, assistant, tool, verifier, doctor, installer, reviewer]
+  actor_id: {type: string, required: false}
+  previous_hash: {type: string}
+  event_hash: {type: string}
+  payload: {type: object}
+
+payload_schemas:
+  gate_question:
+    required: [gate_id, question_text, explicit_scope, still_forbidden]
+    fields:
+      gate_id: {type: string}
+      question_text: {type: string}
+      explicit_scope: {type: object}
+      still_forbidden: {type: array}
+      target_paths: {type: array, required: false}
+      capability_flags: {type: object, required: false}
+  user_answer:
+    required: [answer_quote, responds_to_event_id]
+    fields:
+      answer_quote: {type: string}
+      responds_to_event_id: {type: string}
+  approval_decision:
+    required: [gate_id, user_answer_event_id, gate_question_event_id, interpreted_scope, effects, invalidates_on]
+    fields:
+      gate_id: {type: string}
+      status: {enum: [approved, rejected, blocked, not_applicable, invalidated]}
+      interpreted_scope: {type: object}
+      effects: {type: object}
+      based_on_artifact_hashes: {type: object}
+      target_paths: {type: object}
+      still_forbidden: {type: array}
+      invalidates_on: {type: array}
+  permission_decision:
+    required: [decision_id, capability, decision, reason, based_on_events]
+    fields:
+      decision_id: {type: string}
+      capability: {type: string}
+      path: {type: string, required: false}
+      target: {type: string, required: false}
+      decision: {enum: [allow, deny, block, proposal_required]}
+      reason: {type: string}
+      required_next_action: {type: object, required: false}
+      based_on_events: {type: array}

package/harness/contracts/path-policy.schema.yaml

@@ -0,0 +1,51 @@
+version: 0.1.0
+name: path-policy-schema
+
+normalization_required:
+  - expand_user_visible_windows_drive_shorthand
+  - normalize_separators
+  - resolve_dot_segments
+  - convert_to_absolute_path
+  - resolve_realpath
+  - case_normalize_when_filesystem_is_case_insensitive
+  - detect_symlink
+  - detect_junction
+  - detect_hardlink_when_possible
+  - reject_alternate_data_streams_on_windows
+  - reject_reserved_device_names_on_windows
+
+windows_cases:
+  drive_shorthand:
+    example: F:mptech
+    policy: normalize_to_explicit_drive_root_or_ask_if_ambiguous
+  unc_paths:
+    example: "\\\\server\\share"
+    policy: deny_unless_project_root_explicitly_unc
+  alternate_data_stream:
+    example: file.txt:stream
+    policy: deny
+  reserved_names:
+    examples: [CON, NUL, AUX, PRN]
+    policy: deny
+  symlink_junction_escape:
+    policy: deny_if_realpath_outside_project_root_or_outside_approved_module
+
+glob_policy:
+  raw_globs_do_not_grant_permission: true
+  glob_must_expand_to_exact_paths_before_decision: true
+  empty_glob: deny
+  glob_with_escape: deny
+
+containment:
+  project_root:
+    required_for_all_repo_writes: true
+  modules_root:
+    default_product_code_root: modules/
+    path_decision_uses: realpath
+  harness_core_paths:
+    - AGENTS.md
+    - harness/rules/**
+    - harness/contracts/**
+    - scripts/install-jjamppong-harness.ps1
+    - plugins/**
+    - package installer files

package/harness/contracts/permission-decision.schema.yaml

@@ -0,0 +1,95 @@
+version: 0.1.0
+name: permission-decision-schema
+
+required_fields:
+  - decision_id
+  - schema_version
+  - task_id
+  - requested_action
+  - capability
+  - decision
+  - reason
+  - based_on
+  - created_at
+
+decisions:
+  - allow
+  - deny
+  - block
+  - proposal_required
+
+requested_action_fields:
+  action_type:
+    enum:
+      - file_read
+      - file_write
+      - file_delete
+      - command_exec
+      - network_access
+      - package_install
+      - git_operation
+      - installer_operation
+      - harness_core_change
+      - parallel_write
+  path: {type: string, required: false}
+  command: {type: string, required: false}
+  network_target: {type: string, required: false}
+  package_name: {type: string, required: false}
+
+capability_examples:
+  file_write_module: file.write.module
+  live_target: network.live_target
+  package_install: package.install
+  git_push: git.push
+  secret_read: file.read.secret
+
+based_on:
+  required:
+    - canonical_event_log_hash
+    - relevant_event_ids
+    - artifact_hashes
+    - contract_versions
+  fields:
+    canonical_event_log_hash: string
+    relevant_event_ids: array
+    artifact_hashes: object
+    contract_versions: object
+
+path_policy_result:
+  required_when: path_present
+  fields:
+    raw_path: string
+    normalized_path: string
+    absolute_path: string
+    realpath: string
+    project_root: string
+    is_within_project_root: boolean
+    is_within_modules: boolean
+    has_symlink_or_junction: boolean
+    matched_allowed_pattern: string
+    escape_detected: boolean
+
+required_next_action:
+  fields:
+    type:
+      enum: [ask_user, open_gate, create_proposal, run_verify, stop]
+    gate_id: string
+    suggested_user_question: string
+    missing_capabilities: array
+
+invalidation:
+  approval_must_bind_to:
+    - gate_question_event_id
+    - user_answer_event_id
+    - target_paths
+    - capability_flags
+    - artifact_hashes
+  invalidates_when:
+    - prd_hash_changed
+    - issues_hash_changed
+    - module_structure_hash_changed
+    - writing_plan_hash_changed
+    - target_paths_changed
+    - capability_need_added
+    - user_added_new_constraint
+    - contract_version_changed

package/harness/contracts/task.schema.yaml

@@ -0,0 +1,88 @@
+version: 0.1.0
+name: task-schema
+
+canonical_event_log: events.jsonl
+human_projection: gate-ledger.md
+cache_projection: task.yaml
+
+allowed_task_types:
+  - install
+  - module_bootstrap
+  - product_feature
+  - product_bugfix
+  - template_maintenance
+  - project_policy_change
+  - harness_update
+  - knowledge_maintenance
+  - archive_maintenance
+
+task_types:
+  module_bootstrap:
+    purpose: Create module workspace only.
+    allowed_capabilities:
+      - file.write.folder_skeleton
+      - file.write.task_artifact
+    denied_capabilities:
+      - file.write.module_executable_source
+      - tests.create
+      - fixtures.create
+      - package.install
+      - network.live_target
+      - git.commit
+      - git.push
+    allowed_files:
+      - directories
+      - .gitkeep
+      - MODULE.md
+      - README.md
+      - module-state.md
+    denied_files:
+      - "*.py"
+      - "*.ts"
+      - "*.js"
+      - "*.ps1"
+      - "*.sh"
+      - tests/**
+      - fixtures/**
+      - package.json
+      - pyproject.toml
+      - executable runtime config
+
+  product_feature:
+    purpose: Implement approved vertical slice inside approved module paths.
+    requires:
+      - grill
+      - research
+      - prd
+      - issues
+      - module_structure
+      - writing_plan
+      - plan_review
+      - implementation
+    default_root: modules/
+
+  template_maintenance:
+    purpose: Change harness-core rules/contracts/installer/plugins.
+    requires:
+      - proposal_approved
+      - separate_template_maintenance_checkout
+    forbidden:
+      - product_code
+      - project_domain_solution_as_core_rule_without_proposal
+
+  project_policy_change:
+    purpose: Change project-local policy only.
+    requires:
+      - project_policy_proposal
+    forbidden:
+      - harness_core_rule_change
+
+projections:
+  task_yaml:
+    status: derived_cache
+    may_be_regenerated: true
+    cannot_grant_permission: true
+  gate_ledger_md:
+    status: human_projection
+    may_be_regenerated: true
+    cannot_grant_permission_without_events: true

package/harness/docs/adr/.gitkeep

@@ -0,0 +1 @@
+# keep

package/harness/docs/adr/2026-06-02-jjamppong-planning-gate.md

@@ -0,0 +1,33 @@
+# ADR: Use 짬뽕하네스 Planning Gate
+
+## Status
+
+Accepted after proposal approval.
+
+## Context
+
+The previous harness centered planning on OuroSuper interview, Seed YAML, and handoff-packet concepts. That flow made the harness depend on a planning runtime and produced confusion around missing ambiguity scores, duplicated handoff meanings, and scattered AI artifacts.
+
+## Decision
+
+Use 짬뽕하네스 as the harness workflow. The planning gate combines Matt Pocock planning skills, Superpowers writing plans, gstack review, Compound Engineering learning, and vowline discipline.
+
+AI task artifacts live under `harness/docs/tasks/active/<slug>/` while in progress and move to `harness/docs/tasks/archive/<slug>/` after completion by default. Long-lived reusable learning lives under `harness/docs/solutions/`. `harness/state/` stores only small pointer/status files.
+
+## Alternatives Considered
+
+- Keep OuroSuper as the planning engine.
+- Store AI artifacts under root `docs/`.
+- Put reusable solutions under `harness/state/`.
+- Restore a small-task bypass.
+
+## Consequences
+
+- The workflow is more explicit and easier to audit.
+- Every task creates more planning artifacts.
+- The user reviews one active task folder during work, then mostly works from `modules/` after approval.
+- Root `handoff.md` keeps its original next-chat role.
+
+## Rollback
+
+Reintroduce a proposal that restores the previous workflow and updates `harness/rules/`, README, and AGENTS.md together. Do not partially restore OuroSuper terms without restoring the full old workflow.

package/harness/docs/agents/domain.md

@@ -0,0 +1,14 @@
+# Domain Docs
+
+This harness uses a single-context documentation layout.
+
+Required files:
+
+- Root glossary: `CONTEXT.md`
+- Architecture decisions: `harness/docs/adr/`
+
+Consumer rules:
+
+- `CONTEXT.md` is a glossary, not a PRD or scratch pad.
+- ADRs are for decisions that are hard to reverse, surprising without context, and chosen after a real trade-off.
+- Do not create ADRs for routine implementation details.

package/harness/docs/agents/issue-tracker.md

@@ -0,0 +1,9 @@
+# Issue Tracker
+
+This harness uses local markdown task issues by default.
+
+Issues live under `harness/docs/tasks/active/<YYYY-MM-DD-short-topic>/issues/`.
+
+Each issue is a vertical slice that can be reviewed or implemented independently.
+
+Do not publish issues to GitHub Issues unless the user explicitly asks for that in the current chat.

package/harness/docs/agents/matt-pocock-skills.md

@@ -0,0 +1,60 @@
+# Matt Pocock Skills
+
+짬뽕하네스 requires these external Matt Pocock skills:
+
+- `setup-matt-pocock-skills`
+- `grill-with-docs`
+- `to-prd`
+- `to-issues`
+
+## Readiness Check
+
+Before the planning gate continues, the agent must verify that the required skills are available in the current Codex skill list or installed skill directories.
+
+Use this readiness command in PowerShell when the visible skill list is unavailable:
+
+```powershell
+$required = @(
+  'setup-matt-pocock-skills',
+  'grill-with-docs',
+  'to-prd',
+  'to-issues'
+)
+$roots = @(
+  (Join-Path $env:USERPROFILE '.codex/skills'),
+  (Join-Path $env:USERPROFILE '.agents/skills')
+)
+$skillFiles = foreach ($root in $roots) {
+  if (Test-Path -LiteralPath $root) {
+    Get-ChildItem -LiteralPath $root -Recurse -Filter 'SKILL.md' -ErrorAction SilentlyContinue
+  }
+}
+$missing = foreach ($skill in $required) {
+  $found = $skillFiles | Where-Object {
+    Select-String -LiteralPath $_.FullName -Pattern "name: $skill" -Quiet
+  }
+  if (-not $found) { $skill }
+}
+if ($missing) {
+  $missing
+  throw "Missing required Matt Pocock planning skills"
+}
+"OK: all Matt Pocock planning skills available"
+```
+
+If any required skill is unavailable, stop and tell the user:
+
+```text
+Matt Pocock planning skills are required before this harness can continue.
+Install them first, then rerun this task.
+```
+
+## Install Reference
+
+Use the official installer when available:
+
+```bash
+npx skills@latest add mattpocock/skills
+```
+
+Do not vendor-copy the skill files into this repository.

package/harness/docs/agents/triage-labels.md

@@ -0,0 +1,11 @@
+# Triage Labels
+
+Local markdown issues use these canonical roles:
+
+- `needs-triage` - maintainer needs to evaluate
+- `needs-info` - waiting on user input
+- `ready-for-agent` - ready for AFK agent work
+- `ready-for-human` - requires human judgment or external access
+- `wontfix` - will not be actioned
+
+For local markdown issues, record the role in the issue body instead of applying a GitHub label.

package/harness/docs/solutions/.gitkeep

@@ -0,0 +1 @@
+# keep

package/harness/docs/tasks/active/.gitkeep

@@ -0,0 +1 @@
+# keep

package/harness/docs/tasks/archive/.gitkeep

@@ -0,0 +1 @@
+# keep

package/harness/docs/tasks/archive/index.md

@@ -0,0 +1,5 @@
+# Archive Index
+
+Archive is cold context.
+
+Read `archive-summary.md` first before opening detailed artifacts.

package/harness/docs/tasks/index.md

@@ -0,0 +1,13 @@
+# Task Index
+
+Active tasks are read directly from `harness/docs/tasks/active/`.
+
+Archived tasks are cold context. Read archive indexes and summaries before opening detailed artifacts.
+
+## Active
+
+- See `active/`
+
+## Archive
+
+- See `archive/`

package/harness/doctor/doctor.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { verifyRoot } = require('../verify/verify');
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i += 1;
+    }
+  }
+  return args;
+}
+
+function nextActionFor(failure) {
+  const table = {
+    missing_root_item: 'Run installer or restore the missing root file before planning.',
+    missing_contract: 'Restore harness/contracts from the release package.',
+    nested_harness_folder: 'Move harness files to the project root; do not keep a nested template clone.',
+    secret_file_present: 'Do not read the value. Move/ignore the secret outside publishable harness scope.',
+    harness_lock_missing_field: 'Regenerate harness.lock.yaml from installer receipt data.',
+    planning_started_during_install: 'Treat install as contaminated; create a repair proposal and reset install-only state.',
+    github_repo_created_during_install: 'Record as policy violation; future installer defaults must not create remote repos.',
+    commit_created_during_install: 'Stop and ask for git cleanup instructions; do not rewrite history automatically.',
+    push_performed_during_install: 'Stop and ask for remote cleanup instructions; do not mutate remote automatically.',
+    active_task_single_default: 'Archive, cancel, or explicitly approve parallel active task handling.',
+    projection_without_canonical_event: 'Regenerate projections from events.jsonl or ask the user for explicit approval again.',
+    event_hash_chain_broken: 'Stop using this task state until the event log is audited; do not invent missing approvals.',
+    event_required_fields: 'Repair event log only from trusted source events.',
+  };
+  return table[failure.id] || 'Create a proposal explaining the required safe repair.';
+}
+
+function createProposal(root, verifyResult) {
+  const proposalDir = path.join(root, 'proposals', 'active');
+  fs.mkdirSync(proposalDir, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, 'Z');
+  const proposalPath = path.join(proposalDir, `doctor-fix-${stamp}.md`);
+  const lines = [
+    '# Doctor Repair Proposal',
+    '',
+    'This proposal was generated by `harness/doctor/doctor.js --proposal`.',
+    'It does not apply live repairs.',
+    '',
+    '## Failures',
+    '',
+  ];
+  for (const failure of verifyResult.failures) {
+    lines.push(`- ${failure.id}: ${failure.message}`);
+    lines.push(`  - Suggested next action: ${nextActionFor(failure)}`);
+  }
+  lines.push('');
+  lines.push('## Required Approval');
+  lines.push('');
+  lines.push('A user must approve any live file change separately. This proposal does not grant implementation, git, package, network, or harness-core write permission.');
+  fs.writeFileSync(proposalPath, `${lines.join('\n')}\n`, 'utf8');
+  return proposalPath;
+}
+
+function diagnose(root, options = {}) {
+  const result = verifyRoot(root);
+  const diagnosis = {
+    ok: result.ok,
+    root: result.root,
+    failures: result.failures.map((failure) => ({
+      ...failure,
+      next_action: nextActionFor(failure),
+    })),
+    warnings: result.warnings,
+    proposal_path: null,
+  };
+  if (!result.ok && options.proposal) {
+    diagnosis.proposal_path = createProposal(result.root, result);
+  }
+  return diagnosis;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = path.resolve(args.root || process.cwd());
+  const result = diagnose(root, { proposal: Boolean(args.proposal) });
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else if (result.ok) {
+    process.stdout.write(`doctor found no P0 issues for ${result.root}\n`);
+  } else {
+    process.stdout.write(`doctor found ${result.failures.length} issue(s) for ${result.root}\n`);
+    for (const failure of result.failures) {
+      process.stdout.write(`- ${failure.id}: ${failure.next_action}\n`);
+    }
+    if (result.proposal_path) {
+      process.stdout.write(`proposal: ${result.proposal_path}\n`);
+    }
+  }
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  diagnose,
+};