rungate 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +14 -3
- package/.claude/agents/aditi.md +0 -47
- package/.claude/agents/marcus.md +0 -50
- package/.claude/agents/quinn.md +0 -58
- package/.claude/agents/rook.md +0 -47
- package/.claude/agents/serena.md +0 -46
- package/.claude/rungate.json +0 -11
- package/.fallowrc.json +0 -28
- package/.github/copilot-instructions.md +0 -20
- package/.rungate/conformity-findings.json +0 -648
- package/AGENTS.md +0 -106
- package/CODE-MAP.md +0 -50
- package/HARNESS.md +0 -88
- package/bun.lock +0 -26
- package/bunfig.toml +0 -2
- package/config/brief-policies.json +0 -28
- package/config/ceremony-profiles.json +0 -212
- package/config/consumer-cascade-map.json +0 -24
- package/config/doc-cascade-map.json +0 -24
- package/config/eval.json +0 -84
- package/config/profiles/account-plan.yaml +0 -36
- package/config/profiles/campaign.yaml +0 -94
- package/config/prove-evidence.schema.json +0 -65
- package/config/spec-policies.json +0 -36
- package/config/workflow-schema.json +0 -281
- package/gates/SCHEMA-GUIDE.md +0 -121
- package/gates/ac-quality.test.ts +0 -106
- package/gates/adversarial.test.ts +0 -274
- package/gates/brief-assembler.test.ts +0 -429
- package/gates/brief-assembler.ts +0 -334
- package/gates/bunfig.toml +0 -2
- package/gates/chain.test.ts +0 -91
- package/gates/e2e-smoke.test.ts +0 -234
- package/gates/error-classifier.test.ts +0 -249
- package/gates/error-classifier.ts +0 -89
- package/gates/orchestrator.test.ts +0 -950
- package/gates/orchestrator.ts +0 -569
- package/gates/preload.ts +0 -77
- package/gates/prompts/ac-adversary.md +0 -20
- package/gates/prompts/evidence-validator.md +0 -22
- package/gates/prompts/prove-reproducer.md +0 -53
- package/gates/prove.test.ts +0 -164
- package/gates/run-gate.ts +0 -936
- package/gates/schema-parity.test.ts +0 -197
- package/gates/schema.ts +0 -362
- package/gates/self-heal.test.ts +0 -511
- package/gates/self-heal.ts +0 -121
- package/gates/ship-orchestrator.test.ts +0 -379
- package/gates/ship-orchestrator.ts +0 -363
- package/gates/test-fixtures/broken-no-environments.json +0 -60
- package/gates/test-fixtures/valid-standard.json +0 -54
- package/gates/test-utils.ts +0 -43
- package/gates/witness.ts +0 -220
- package/gates/workflow.test.ts +0 -1053
- package/hooks/AgentBriefGuard.hook.ts +0 -586
- package/hooks/AgentVerdictCapture.hook.ts +0 -134
- package/hooks/AutoVerifyGate.hook.ts +0 -76
- package/hooks/GateEnforcement.hook.ts +0 -273
- package/hooks/IssueCloseGuard.hook.ts +0 -116
- package/hooks/MergeGuard.hook.ts +0 -55
- package/hooks/StaleTTLCleanup.hook.ts +0 -133
- package/hooks/VerifyPhaseLock.hook.ts +0 -81
- package/hooks/WorkflowStateGuard.hook.ts +0 -37
- package/hooks/lib/agentDetection.ts +0 -70
- package/hooks/lib/findWorkflow.ts +0 -101
- package/hooks/lib/parseStdin.ts +0 -37
- package/hooks/lib/paths.ts +0 -111
- package/hooks/lib/utils.ts +0 -81
- package/reference/migration-manifest.json +0 -554
- package/reference/prompts/agent-aditi.md +0 -38
- package/reference/prompts/agent-marcus.md +0 -38
- package/reference/prompts/agent-quinn.md +0 -38
- package/reference/prompts/agent-rook.md +0 -37
- package/reference/prompts/agent-serena.md +0 -37
- package/reference/prompts/council-skill.md +0 -170
- package/reference/prompts/goal-skill.md +0 -235
- package/reference/prompts/prove-skill.md +0 -283
- package/reference/prompts/quinn-standard.md +0 -246
- package/reference/prompts/ship-convergence.md +0 -65
- package/reference/prompts/ship-escalation.md +0 -43
- package/reference/prompts/ship-iteration.md +0 -382
- package/reference/prompts/ship-pending-patches.md +0 -246
- package/reference/prompts/ship-reference.md +0 -250
- package/reference/prompts/ship-skill.md +0 -347
- package/reference/prompts/ship-templates.md +0 -215
- package/reference/scripts/batch-status.sh +0 -68
- package/reference/scripts/chain-compat-check.sh +0 -67
- package/reference/scripts/context-audit.sh +0 -314
- package/reference/scripts/dead-export-check.sh +0 -61
- package/reference/scripts/generate-qc-tables.sh +0 -92
- package/reference/scripts/harness-init.sh +0 -111
- package/reference/scripts/pai-054-baseline-check.sh +0 -40
- package/reference/scripts/prove-smoke-test.sh +0 -112
- package/reference/scripts/setup-keychain-salt.sh +0 -12
- package/reference/scripts/skill-optimizer-friday.sh +0 -88
- package/reference/scripts/skill-qc-test.sh +0 -351
- package/reference/scripts/skill-synthesize-tonight.sh +0 -66
- package/reference/specs/HARNESS-EXTRACTION-SPEC.md +0 -263
- package/reference/specs/harness-v3-bash-deletion-plan.md +0 -65
- package/reference/specs/harness-v3-migration-plan.md +0 -188
- package/scripts/decision-reconcile.sh +0 -74
- package/scripts/decision-reconcile.ts +0 -152
- package/scripts/git-hooks/pre-commit +0 -76
- package/scripts/git-hooks/pre-push +0 -271
- package/scripts/harness-skill-check.sh +0 -52
- package/scripts/lib/gap-emit.sh +0 -65
- package/scripts/lib/jq-update.sh +0 -30
- package/scripts/lib/resolve-slug.sh +0 -30
- package/scripts/lib/verify-spec-compliance.sh +0 -102
- package/scripts/prove-backfill.sh +0 -87
- package/scripts/scaffold-rungate-config.ts +0 -91
- package/scripts/self-containment-check.sh +0 -109
- package/scripts/skill-qc-validator.sh +0 -402
- package/scripts/slug-resolver.sh +0 -14
- package/specs/BOOTSTRAP-DATA-FLOW-SPEC.md +0 -2493
- package/specs/BOOTSTRAP-TEST-PLAN.md +0 -571
- package/specs/HARNESS-GATES.md +0 -256
- package/specs/HARNESS-SKILL-CHAIN.md +0 -286
- package/specs/HARNESS-SKILL-CONTRACT.md +0 -93
- package/specs/HARNESS-STANDARD.md +0 -488
- package/specs/SPEC-TEMPLATE.md +0 -53
- package/specs/bootstrap-data-flow.png +0 -0
- package/specs/harness-automation-matrix.md +0 -314
- package/specs/harness-automation-matrix.rules.json +0 -64
- package/test/anti.test.ts +0 -80
- package/test/contract-negative.test.ts +0 -86
- package/test/contract.test.ts +0 -158
- package/test/external-deps.test.ts +0 -48
- package/test/fixtures/golden-project/.env.example +0 -3
- package/test/fixtures/golden-project/Makefile +0 -7
- package/test/fixtures/golden-project/docs/adr/ADR-001-framework.md +0 -23
- package/test/fixtures/golden-project/docs/setup-guide.md +0 -10
- package/test/fixtures/golden-project/package.json +0 -10
- package/test/fixtures/golden-project/specs/api-spec.md +0 -20
- package/test/fixtures/golden-project/src/auth.ts +0 -8
- package/test/fixtures/golden-project/src/db.ts +0 -11
- package/test/fixtures/golden-project/src/index.ts +0 -19
- package/test/fixtures/golden-project/src/utils/format.ts +0 -3
- package/test/fixtures/golden-project/test/auth.test.ts +0 -15
- package/test/fixtures/golden-project/tsconfig.json +0 -12
- package/test/meta-sc-coverage.test.ts +0 -159
- package/test/phase-0.test.ts +0 -846
- package/test/phase-1.test.ts +0 -617
- package/test/phase-2.test.ts +0 -620
- package/test/phase-3.test.ts +0 -99
- package/test/scaffold-conformity.test.ts +0 -8
- package/test/schema-canary.test.ts +0 -51
- package/test/spec-compliance-auto.test.ts +0 -64
- package/test/spec-compliance.test.ts +0 -295
- package/test/spec-discovery.test.ts +0 -68
- package/test/spec-drift.test.ts +0 -5
- package/test/structure.test.ts +0 -165
- package/test/unit/agent-brief-guard-ship.test.ts +0 -293
- package/test/unit/extract-constraints.test.ts +0 -145
- package/test/unit/issue-close-guard.test.ts +0 -204
- package/test/unit/scaffold-project.test.ts +0 -417
- package/test/unit/skill-cooccurrence.test.ts +0 -177
- package/test/unit/skill-sequence-logger.test.ts +0 -244
- package/test/unit/workflow-state-guard.test.ts +0 -95
- package/workflows/batch-ship.js +0 -295
- package/workflows/council.js +0 -481
- package/workflows/prove.js +0 -560
- package/workflows/ship.js +0 -789
- package/workflows/verify.js +0 -236
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
doc-type: reference
|
|
3
|
-
status: active
|
|
4
|
-
owner: jason
|
|
5
|
-
updated: 2026-09-08
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Rook Blackburn — Security Review
|
|
9
|
-
|
|
10
|
-
You are Rook Blackburn, security engineer. You scan changed files for vulnerabilities.
|
|
11
|
-
|
|
12
|
-
## What you scan
|
|
13
|
-
|
|
14
|
-
1. All files changed in the current branch vs main
|
|
15
|
-
2. Pattern siblings — files that share imports or data flow with changed files
|
|
16
|
-
3. Configuration files touched by the change
|
|
17
|
-
|
|
18
|
-
## What you look for
|
|
19
|
-
|
|
20
|
-
- Injection vulnerabilities (XSS, SQL injection, command injection)
|
|
21
|
-
- Authentication/authorization bypasses
|
|
22
|
-
- Sensitive data exposure (credentials, tokens, PII in logs)
|
|
23
|
-
- Insecure defaults or missing input validation
|
|
24
|
-
- Path traversal in file operations
|
|
25
|
-
- Unsafe deserialization
|
|
26
|
-
|
|
27
|
-
## How you report
|
|
28
|
-
|
|
29
|
-
- CLEAR or FINDINGS with severity (CRITICAL/HIGH/MEDIUM/LOW)
|
|
30
|
-
- Each finding: file, line, vulnerability type, remediation
|
|
31
|
-
- False positives noted as such with reasoning
|
|
32
|
-
|
|
33
|
-
## What you do NOT do
|
|
34
|
-
|
|
35
|
-
- Never modify source code — report only
|
|
36
|
-
- Never touch production config files
|
|
37
|
-
- Never run `make rebuild`
|
|
@@ -1,37 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
doc-type: reference
|
|
3
|
-
status: active
|
|
4
|
-
owner: jason
|
|
5
|
-
updated: 2026-09-08
|
|
6
|
-
---
|
|
7
|
-
|
|
8
|
-
# Serena Blackwood — Architecture
|
|
9
|
-
|
|
10
|
-
You are Serena Blackwood, software architect. You make structural decisions and write ADRs.
|
|
11
|
-
|
|
12
|
-
## What you do
|
|
13
|
-
|
|
14
|
-
1. Evaluate proposed architectural changes against existing ADRs
|
|
15
|
-
2. Write new ADRs for decisions that don't have one
|
|
16
|
-
3. Review module boundaries and dependency direction
|
|
17
|
-
4. Assess scalability, maintainability, and complexity tradeoffs
|
|
18
|
-
5. Design data flow and integration points
|
|
19
|
-
|
|
20
|
-
## Architecture principles
|
|
21
|
-
|
|
22
|
-
- Deep modules, thin consumers
|
|
23
|
-
- Single chokepoint for mutations (saveCustomers, saveConfig, etc.)
|
|
24
|
-
- Config-driven over hardcoded
|
|
25
|
-
- Shared logic in lib/, never duplicated across consumers
|
|
26
|
-
- Schema validation at system boundaries
|
|
27
|
-
|
|
28
|
-
## How you report
|
|
29
|
-
|
|
30
|
-
- ADR document for new decisions
|
|
31
|
-
- APPROVED or CONCERNS for reviews
|
|
32
|
-
- Specific module/file recommendations, not abstract guidance
|
|
33
|
-
|
|
34
|
-
## What you do NOT do
|
|
35
|
-
|
|
36
|
-
- Never write implementation code — provide architecture specs for Marcus
|
|
37
|
-
- Never run builds, tests, or deployments
|
|
@@ -1,170 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: Council
|
|
3
|
-
description: Multi-round parallel debate with progressive transcript passing for architecture decisions and tradeoff analysis.
|
|
4
|
-
version: 1.1.0
|
|
5
|
-
doc-type: reference
|
|
6
|
-
status: active
|
|
7
|
-
owner: jason
|
|
8
|
-
updated: 2026-09-06
|
|
9
|
-
contract:
|
|
10
|
-
input: "Topic string + optional context + optional governingSpec"
|
|
11
|
-
gateIn: "None — /council is standalone"
|
|
12
|
-
gateOut: "Synthesis with convergencePoints, recommendation, specAlignment, enforcementClassification"
|
|
13
|
-
artifact: "council-synthesis.json at ~/.rungate/{slug}/"
|
|
14
|
-
outputSchema: "schemas/council-synthesis.schema.json"
|
|
15
|
-
telemetry: "harness-telemetry.jsonl with skill=council"
|
|
16
|
-
errorRecovery:
|
|
17
|
-
timeout_seconds: 600
|
|
18
|
-
failure_mode: WARN
|
|
19
|
-
cleanup_action: "None — council is read-only"
|
|
20
|
-
resumable: false
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
# Council
|
|
24
|
-
|
|
25
|
-
Multi-round parallel debate with progressive transcript passing. Produces convergence-tested synthesis for architecture decisions, tradeoff analysis, and design reviews.
|
|
26
|
-
|
|
27
|
-
## Interface
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
/council "topic" — debate with research (default)
|
|
31
|
-
/council "topic" --noResearch — debate without codebase/external research
|
|
32
|
-
/council "topic" --governingSpec PATH — force-read a governing spec before debate
|
|
33
|
-
/council on 306 — debate issue #306 with research
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
**Research is ON by default.** Phase 0 runs parallel codebase + external research agents before the debate. Use `--noResearch` only for pure opinion/tradeoff debates with no codebase context needed.
|
|
37
|
-
|
|
38
|
-
**Governing spec (#309):** When `--governingSpec` is passed, the research agent reads that spec FIRST and extracts all design decisions. Council members must align with the spec or explicitly argue for amendment. Synthesis includes `specAlignment` field.
|
|
39
|
-
|
|
40
|
-
**Invocation:** Always use `scriptPath` to get the latest version:
|
|
41
|
-
```
|
|
42
|
-
Workflow({ scriptPath: "~/.claude/workflows/council.js", args: { topic, governingSpec, ... } })
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
## Trigger conditions
|
|
46
|
-
|
|
47
|
-
- When: `/council`, "run a council", "debate this", "get multiple perspectives"
|
|
48
|
-
- Standalone: yes — can run at any point in the harness chain
|
|
49
|
-
- Chain position: lateral (any point) — does not block or advance the main chain
|
|
50
|
-
- Skip when: single-option decisions, trivial config changes, already-decided ADRs
|
|
51
|
-
|
|
52
|
-
## Workflow
|
|
53
|
-
|
|
54
|
-
### Step 1 — Frame the question
|
|
55
|
-
|
|
56
|
-
**The DA frames the question as a PROBLEM, not a PLAN.** This is the single highest-leverage decision in the entire council process.
|
|
57
|
-
|
|
58
|
-
Bad: "Here are 7 issues. Is this right-sized?" → council can only say "fewer" or "more"
|
|
59
|
-
Good: "Bash gates still run despite migration declared complete. How should we fix this?" → council proposes solutions
|
|
60
|
-
|
|
61
|
-
**Briefing rules (mandatory):**
|
|
62
|
-
|
|
63
|
-
1. **Problem, not plan.** Give the council the failure/gap/decision. Do NOT give them your proposed solution. When you hand them a plan, they evaluate. When you hand them a problem, they think. If you already have a plan, describe the PROBLEM the plan is trying to solve, not the plan itself.
|
|
64
|
-
|
|
65
|
-
2. **Code-first, not authority-first.** Include in the brief: "Positions must cite specific file:line numbers from the codebase. Do not cite Fowler, Larson, Brooks, or industry patterns as primary evidence — reason from THIS code. External patterns may support a code-grounded argument but cannot replace one." Without this, council members pattern-match against authorities instead of reading the actual code.
|
|
66
|
-
|
|
67
|
-
3. **Include a premise-challenger.** One council member must be briefed: "Your job is to argue we should NOT do this at all. What's the case for the opposite direction? What's the simplest fix that avoids the proposed work entirely? What assumptions is everyone else making that might be wrong?" This role must be explicitly assigned — without it, all members optimize within the same frame.
|
|
68
|
-
|
|
69
|
-
4. **Constrain the output toward simplicity.** Add one of: "Your recommendation must result in fewer total lines of code than exist today" or "The simplest fix wins — justify every line you add" or "What can we DELETE instead of building?" Without a simplicity constraint, councils default to adding — more checks, more enforcement, more architecture.
|
|
70
|
-
|
|
71
|
-
5. **Ask one hard question about the code.** Not "should we port convergence.sh?" but "convergence.sh is 66 lines of state machine logic. Is this logic necessary? What breaks if we delete it entirely?" Force members to evaluate whether complexity should be ported or eliminated.
|
|
72
|
-
|
|
73
|
-
6. **No plan-shaped questions.** Questions like "Is 7 issues the right number?" or "Should #307 be a dependency?" presuppose the plan structure. Instead: "What is the minimum change that prevents this failure from recurring?"
|
|
74
|
-
|
|
75
|
-
**Anti-patterns in council briefs:**
|
|
76
|
-
- Giving 5+ questions (council optimizes for answering questions, not solving problems)
|
|
77
|
-
- Including your proposed issue structure (council evaluates it instead of proposing alternatives)
|
|
78
|
-
- Asking "should we use X?" (binary validation, not design thinking)
|
|
79
|
-
- Omitting file paths (council cites abstractions instead of code)
|
|
80
|
-
|
|
81
|
-
1. Extract the core PROBLEM from user input — not the user's proposed solution
|
|
82
|
-
2. Identify relevant context (issue, spec, prior decisions)
|
|
83
|
-
3. Set round count (default: 3 rounds)
|
|
84
|
-
|
|
85
|
-
### Step 2 — Spawn parallel debaters
|
|
86
|
-
|
|
87
|
-
1. Launch 3+ agents with distinct perspectives (e.g., pragmatist, purist, operator)
|
|
88
|
-
2. **One agent must be a premise-challenger** — briefed to argue against the assumed direction
|
|
89
|
-
3. Each agent receives: problem statement, file paths to read, role brief
|
|
90
|
-
4. Round 1: independent analysis (no cross-pollination)
|
|
91
|
-
|
|
92
|
-
### Step 3 — Progressive rounds
|
|
93
|
-
|
|
94
|
-
1. After each round, synthesize positions
|
|
95
|
-
2. Pass synthesis + all transcripts to next round
|
|
96
|
-
3. Agents respond to each other's arguments
|
|
97
|
-
4. Track convergence points and persistent disagreements
|
|
98
|
-
|
|
99
|
-
### Step 4 — Synthesize
|
|
100
|
-
|
|
101
|
-
1. Identify convergence points (all agents agree)
|
|
102
|
-
2. Identify persistent disagreements (with each side's strongest argument)
|
|
103
|
-
3. Generate recommendation with confidence level
|
|
104
|
-
4. Classify enforcement: behavioral rule, mechanical gate, or advisory
|
|
105
|
-
|
|
106
|
-
### Step 5 — Log telemetry
|
|
107
|
-
|
|
108
|
-
Append to harness-telemetry.jsonl:
|
|
109
|
-
```json
|
|
110
|
-
{"ts":"...","skill":"council","issue":0,"check":"synthesis","result":"COMPLETE","duration_ms":120000}
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### Artifact Output
|
|
114
|
-
|
|
115
|
-
After synthesis is complete, the council produces a structured artifact:
|
|
116
|
-
|
|
117
|
-
1. The council workflow returns a synthesis object matching `council-synthesis.schema.json`
|
|
118
|
-
2. Key addition from ADR-007: the `decisions[]` array with structured tracking:
|
|
119
|
-
```json
|
|
120
|
-
{
|
|
121
|
-
"id": "D-001",
|
|
122
|
-
"statement": "Use file presence for chain detection, not env vars",
|
|
123
|
-
"target": {"type": "adr", "ref": "~/.claude/PAI/ADR/ADR-007-universal-skill-contract.md", "section": "Chain Detection"},
|
|
124
|
-
"disposition": "ACCEPTED",
|
|
125
|
-
"correlationTags": ["chain-detection", "file-presence"],
|
|
126
|
-
"phase": "Phase 2b-B"
|
|
127
|
-
}
|
|
128
|
-
```
|
|
129
|
-
3. Every convergence point and recommendation becomes a decision entry
|
|
130
|
-
4. Post-council, run `decision-reconcile.sh` against the target document to verify all decisions made it into the doc
|
|
131
|
-
|
|
132
|
-
### Decision Tracking
|
|
133
|
-
|
|
134
|
-
After any council session that produces decisions targeting a specific document:
|
|
135
|
-
|
|
136
|
-
1. Save synthesis as `~/.rungate/{slug}/council-synthesis.json`
|
|
137
|
-
2. Run: `bash ~/.claude/scripts/decision-reconcile.sh ~/.rungate/{slug}/council-synthesis.json --target <doc-path>`
|
|
138
|
-
3. If MISSING count > 0: patch the document before presenting results
|
|
139
|
-
4. Report: "N decisions, N captured, M dropped" — the count forces accountability
|
|
140
|
-
|
|
141
|
-
### Research Mode with Performance Data
|
|
142
|
-
|
|
143
|
-
When council is invoked with `--research` or for skill improvement decisions, performance profiles from AgentGrit feed into the council context:
|
|
144
|
-
|
|
145
|
-
1. Load all performance profiles from `~/agentgrit/data/profiles/*.json`
|
|
146
|
-
2. Format as evidence table for council members:
|
|
147
|
-
```
|
|
148
|
-
Skill Performance Profiles (last 30 days):
|
|
149
|
-
| Skill | Execs | Hit Rate | Gap Rate | Iterations | Trend |
|
|
150
|
-
| prove | 47 | 82% | 18% | 1.3 | improving |
|
|
151
|
-
| ship | 89 | 95% | 5% | 2.1 | stable |
|
|
152
|
-
```
|
|
153
|
-
3. Council members receive profiles as part of their context — decisions are data-backed
|
|
154
|
-
4. If no profiles exist (AgentGrit not yet producing): council proceeds without, notes data gap
|
|
155
|
-
|
|
156
|
-
### Data-Driven Contract Updates
|
|
157
|
-
|
|
158
|
-
When council recommends a skill contract change:
|
|
159
|
-
1. The recommendation includes the performance data that motivated it
|
|
160
|
-
2. Example: "prove gapRate 18% on UI issues → add screenshot SC requirement to prove contract"
|
|
161
|
-
3. The change is tracked as a decision with `correlationTag: "performance-driven"`
|
|
162
|
-
4. Post-implementation: Learn phase captures new data → profiles update → next audit verifies improvement
|
|
163
|
-
|
|
164
|
-
## Error handling
|
|
165
|
-
|
|
166
|
-
- Timeout: 600 seconds total
|
|
167
|
-
- Per-agent timeout: 180 seconds
|
|
168
|
-
- On agent timeout: proceed with available responses
|
|
169
|
-
- On all agents timeout: return partial synthesis with WARN
|
|
170
|
-
- Not resumable — re-run produces fresh debate
|
|
@@ -1,235 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: Goal
|
|
3
|
-
description: Mandatory first step of the harness loop — decomposes goals into measurable GitHub issues with garbage-tested ACs.
|
|
4
|
-
version: 1.0.0
|
|
5
|
-
doc-type: reference
|
|
6
|
-
status: active
|
|
7
|
-
owner: jason
|
|
8
|
-
updated: 2026-09-06
|
|
9
|
-
contract:
|
|
10
|
-
input: "Observation, screenshot, verbal description, email, or link from user"
|
|
11
|
-
gateIn: "None — /goal is the chain entry point"
|
|
12
|
-
gateOut: "GitHub issue exists with measurable ACs + beforeState captured"
|
|
13
|
-
artifact: "GitHub issue + workflow-state.json with issueGoal, ACs, beforeState"
|
|
14
|
-
outputSchema: "schemas/goal-record.schema.json"
|
|
15
|
-
telemetry: "harness-telemetry.jsonl with skill=goal"
|
|
16
|
-
errorRecovery:
|
|
17
|
-
timeout_seconds: 300
|
|
18
|
-
failure_mode: BLOCK
|
|
19
|
-
cleanup_action: "Close draft issue if created"
|
|
20
|
-
resumable: true
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
# Goal
|
|
24
|
-
|
|
25
|
-
The mandatory first step of the PAI agentic harness loop. Every implementation task starts here — no exceptions.
|
|
26
|
-
|
|
27
|
-
Read `PAI/HARNESS-STANDARD.md` for how this skill fits into the full loop.
|
|
28
|
-
|
|
29
|
-
## Trigger conditions
|
|
30
|
-
|
|
31
|
-
- When: `/goal`, "I want to...", "we need to...", "fix this...", any new implementation request
|
|
32
|
-
- Standalone: yes — always the first skill in the chain
|
|
33
|
-
- Chain position: start (entry point)
|
|
34
|
-
- Skip when: issue already exists with ACs (use Mode 3 to validate)
|
|
35
|
-
|
|
36
|
-
## Workflow
|
|
37
|
-
|
|
38
|
-
See Three Entry Modes below for the full workflow per mode.
|
|
39
|
-
|
|
40
|
-
## Three Entry Modes
|
|
41
|
-
|
|
42
|
-
The DA determines which mode applies, then follows that mode's process.
|
|
43
|
-
|
|
44
|
-
### Mode 1: Goal, No Issues
|
|
45
|
-
|
|
46
|
-
**Trigger:** Jason states a goal in natural language and no GitHub issues exist for it yet.
|
|
47
|
-
|
|
48
|
-
**What happens:**
|
|
49
|
-
1. The DA reads project PRINCIPLES.md pre-flight questions (if the project has one) — these inform goal decomposition
|
|
50
|
-
2. The goal is decomposed into measurable success criteria (SC-1, SC-2, ...)
|
|
51
|
-
3. **Garbage test on every SC:** Each SC is tested: "Could garbage data pass this?" If yes, the SC is tightened until the answer is no
|
|
52
|
-
4. Scope boundary is defined (what's in, what's out)
|
|
53
|
-
5. Circuit breaker defaults are set (or Jason is consulted if non-default needed):
|
|
54
|
-
- Per-issue: 5 iterations max
|
|
55
|
-
- Per-goal: $20 cost ceiling, 5M token ceiling
|
|
56
|
-
6. A GitHub issue is created via `gh issue create` using the template below
|
|
57
|
-
7. A checkpoint is written to `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md`
|
|
58
|
-
|
|
59
|
-
### Mode 2: Goal, Issues Exist
|
|
60
|
-
|
|
61
|
-
**Trigger:** Jason states a goal and related GitHub issues already exist.
|
|
62
|
-
|
|
63
|
-
**What happens:**
|
|
64
|
-
1. Existing issues are searched: `gh issue list --repo hornjason/pai-config --state open --search "[keywords]"` (also checks hornjason/asaCommandCenter)
|
|
65
|
-
2. Each related issue is read — existing scope is understood
|
|
66
|
-
3. Existing issues are mapped against the goal — which success criteria do they cover?
|
|
67
|
-
4. Gaps are identified — which criteria have no issue yet?
|
|
68
|
-
5. Only gap issues are created using the template below
|
|
69
|
-
6. **Umbrella trigger (mechanical):** If 2+ issues (existing + newly created) map to this goal, an umbrella issue is auto-created:
|
|
70
|
-
- The `decomposed` label is added to the umbrella
|
|
71
|
-
- The goal issue template below is used with an additional `## Children` section:
|
|
72
|
-
```
|
|
73
|
-
## Children
|
|
74
|
-
- [ ] #N — [title]
|
|
75
|
-
- [ ] #M — [title]
|
|
76
|
-
|
|
77
|
-
max-children: 8
|
|
78
|
-
```
|
|
79
|
-
- `Parent: #UMBRELLA` is added to each child issue body at creation time
|
|
80
|
-
- The umbrella's SCs are the aggregate goal; children have decomposed ACs
|
|
81
|
-
- close-gate.sh handles rollup validation (D1: child-refs, D2: children-closed + shipped label, D3: no-orphans, D4: max-children WARN)
|
|
82
|
-
- If only 1 issue maps to the goal, umbrella creation is skipped — single-issue flow unchanged
|
|
83
|
-
7. A checkpoint is written
|
|
84
|
-
|
|
85
|
-
### Mode 3: Issue, No Goal
|
|
86
|
-
|
|
87
|
-
**Trigger:** Jason points at a specific issue number ("ship issue #33").
|
|
88
|
-
|
|
89
|
-
**What happens:**
|
|
90
|
-
1. The issue is read: `gh issue view [number] --repo [repo]`
|
|
91
|
-
2. ACs are validated against the garbage test — if any AC could be passed by garbage, the DA tightens it
|
|
92
|
-
3. Standardized structure is checked — if missing sections (Goal, Success Criteria, Scope Boundary, Circuit Breakers), they are added via `gh issue comment`
|
|
93
|
-
4. Related issues are checked: `gh issue list --search "[keywords]"`
|
|
94
|
-
5. **Governing Spec Detection:** The skill detects if the issue references a governing spec:
|
|
95
|
-
- The issue body is grepped for `ADR-`, `Governing spec:`, `spec/`, or spec file paths
|
|
96
|
-
- If found: the spec is read, the path is extracted, and it is added to GoalRecord as `governingSpec.path` with `detectedFrom: "issue-body"`
|
|
97
|
-
- If not found: `governingSpec` is omitted from GoalRecord (optional field)
|
|
98
|
-
- When governingSpec is present: each SC traces to a spec claim (or notes "no spec claim — new behavior")
|
|
99
|
-
6. A checkpoint is written
|
|
100
|
-
|
|
101
|
-
## Goal Type Classification
|
|
102
|
-
|
|
103
|
-
Before creating output, the goal type is classified using this deterministic decision tree:
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
Is this a structural/architectural decision?
|
|
107
|
-
YES → Is there an existing ADR for this area?
|
|
108
|
-
YES → type: github-issue (implement against existing ADR)
|
|
109
|
-
NO → type: adr (create ADR first, then issues)
|
|
110
|
-
NO → Is this a multi-issue initiative (L-sized)?
|
|
111
|
-
YES → Is there a clear scope + user value?
|
|
112
|
-
YES → type: prd (create PRD, then decompose to issues)
|
|
113
|
-
NO → type: research-brief (research first, then PRD)
|
|
114
|
-
NO → Is this investigative/exploratory?
|
|
115
|
-
YES → type: research-brief
|
|
116
|
-
NO → type: github-issue (default)
|
|
117
|
-
```
|
|
118
|
-
|
|
119
|
-
### Output Types
|
|
120
|
-
|
|
121
|
-
| Type | Output | When | Example |
|
|
122
|
-
|---|---|---|---|
|
|
123
|
-
| `github-issue` | GitHub issue with ACs | Default — most goals | "Fix subject duplication in batch emails" |
|
|
124
|
-
| `adr` | ADR document + GitHub issue for implementation | Structural/architectural decisions with no existing ADR | "How should skills communicate state?" |
|
|
125
|
-
| `prd` | PRD document + decomposed issues | L-sized initiatives with clear scope | "Build campaign UI with real-time preview" |
|
|
126
|
-
| `spec` | Spec document | Defining behavior for an existing system | "Document the skill chain handoff protocol" |
|
|
127
|
-
| `research-brief` | Research output document | Exploratory/investigative goals, unclear scope | "What multi-agent frameworks handle chain state?" |
|
|
128
|
-
|
|
129
|
-
### Routing Rules
|
|
130
|
-
|
|
131
|
-
- **`github-issue` (default):** Follows existing Mode 1/2/3 workflow. GoalRecord `artifactRef.type` = "github-issue".
|
|
132
|
-
- **`adr`:** The ADR is written to `PAI/ADR/ADR-NNN-{slug}.md` using ADR template. A GitHub issue is created for Phase 1 implementation. GoalRecord `artifactRef.type` = "adr", `artifactRef.locator` = ADR file path.
|
|
133
|
-
- **`prd`:** The PRD is created via `Skill("to-prd")`. Decomposition happens via `Skill("to-issues")`. GoalRecord `artifactRef.type` = "prd", `artifactRef.locator` = PRD issue number.
|
|
134
|
-
- **`spec`:** The spec is written to `PAI/specs/{name}.md`. GoalRecord `artifactRef.type` = "spec", `artifactRef.locator` = spec file path.
|
|
135
|
-
- **`research-brief`:** Research agent(s) are spawned. Output goes to `~/.rungate/{slug}/research-output.json`. GoalRecord `artifactRef.type` = "research-brief", `artifactRef.locator` = output file path.
|
|
136
|
-
|
|
137
|
-
### Phase Note
|
|
138
|
-
|
|
139
|
-
Phase 3b defines the classification and routing rules. The actual implementation of non-issue output types (ADR writing, PRD creation, spec templates) is handled by existing skills (`to-prd`, `to-issues`) or future work. The decision tree ensures consistent classification from day one.
|
|
140
|
-
|
|
141
|
-
## GitHub Issue Template
|
|
142
|
-
|
|
143
|
-
Every issue produced by this skill uses this structure. Posted as issue body (Mode 1) or as a structured comment (Mode 3 enrichment):
|
|
144
|
-
|
|
145
|
-
```markdown
|
|
146
|
-
## Goal
|
|
147
|
-
[Jason's words, verbatim — or issue's original description]
|
|
148
|
-
|
|
149
|
-
## Success Criteria
|
|
150
|
-
- [ ] SC-1: [measurable, garbage-tested — specific numbers, not "exists" or "works"]
|
|
151
|
-
- [ ] SC-2: [measurable, garbage-tested]
|
|
152
|
-
- [ ] SC-A1: [anti-criterion — must NOT happen]
|
|
153
|
-
|
|
154
|
-
## Scope Boundary
|
|
155
|
-
- In: [explicit list of what this covers]
|
|
156
|
-
- Out: [explicit list of what this does NOT cover]
|
|
157
|
-
|
|
158
|
-
## Circuit Breakers
|
|
159
|
-
- Per-issue: 5 iterations max (override: [N])
|
|
160
|
-
- Per-goal: $20 cost ceiling (override: [$N])
|
|
161
|
-
- Per-goal: 5M token ceiling (override: [NM])
|
|
162
|
-
|
|
163
|
-
## Related Issues
|
|
164
|
-
- #N — [open/closed] — [how it relates to this goal]
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
## Quality Bar
|
|
168
|
-
|
|
169
|
-
The skill does not exit until ALL of the following are true. The gate enforces these mechanically:
|
|
170
|
-
- [ ] Every SC passes the garbage test
|
|
171
|
-
- [ ] Scope boundary has at least one "In" and one "Out" item
|
|
172
|
-
- [ ] Circuit breakers are set (defaults or overrides)
|
|
173
|
-
- [ ] Related issues searched and listed (even if none found — state "none found")
|
|
174
|
-
- [ ] GitHub issue created or enriched
|
|
175
|
-
- [ ] Checkpoint written to `$RUNGATE_WORK_DIR/{slug}/CHECKPOINT.md`
|
|
176
|
-
|
|
177
|
-
## What This Skill Does NOT Do
|
|
178
|
-
|
|
179
|
-
- Does NOT size the work — sizing happens in Ship SCOPE (PLANNING step)
|
|
180
|
-
- Does NOT read project docs for context — that's DISCOVERY
|
|
181
|
-
- Does NOT write code or run tests — that's EXECUTION
|
|
182
|
-
- Does NOT decompose L-sized work into vertical slices — that's `Skill("to-issues")`
|
|
183
|
-
|
|
184
|
-
### Before-state capture
|
|
185
|
-
|
|
186
|
-
After the issue is created, the current state of the bug/feature area is captured in workflow-state.json:
|
|
187
|
-
|
|
188
|
-
- `beforeState.type`: text | screenshot | api | none
|
|
189
|
-
- `beforeState.path`: file path to captured evidence
|
|
190
|
-
- `beforeState.capturedAt`: ISO timestamp
|
|
191
|
-
|
|
192
|
-
For LIGHT tier, `type: "none"` is acceptable. /prove reads beforeState for before/after comparison.
|
|
193
|
-
|
|
194
|
-
**Test baseline (#483):** If rungate.json has a `testCmd`, the DA runs it at goal time and captures pass/fail counts in `beforeState.testBaseline`:
|
|
195
|
-
```json
|
|
196
|
-
"testBaseline": {
|
|
197
|
-
"command": "bun test --isolate test/unit/",
|
|
198
|
-
"pass": 47,
|
|
199
|
-
"fail": 7,
|
|
200
|
-
"capturedAt": "2026-09-11T..."
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
Ship gate uses this to distinguish pre-existing failures from regressions — a test count INCREASE in fails is a regression; same or fewer fails is pre-existing. Gate comparison implementation tracked separately.
|
|
204
|
-
|
|
205
|
-
### Artifact Output
|
|
206
|
-
|
|
207
|
-
After the GitHub issue is created and before-state is captured, the GoalRecord artifact is written:
|
|
208
|
-
|
|
209
|
-
1. `~/.rungate/{slug}/goal-record.json` is created with:
|
|
210
|
-
```json
|
|
211
|
-
{
|
|
212
|
-
"contractVersion": "1.0",
|
|
213
|
-
"id": "issue-{N}",
|
|
214
|
-
"goalStatement": "[issueGoal verbatim]",
|
|
215
|
-
"successCriteria": [/* SCs from issue, each with id, assertion, evidenceType, threshold */],
|
|
216
|
-
"scopeBoundary": {"in": [...], "out": [...]},
|
|
217
|
-
"artifactRef": {"type": "github-issue", "locator": "owner/repo#N"}
|
|
218
|
-
}
|
|
219
|
-
```
|
|
220
|
-
2. Validation runs via Zod schema — `writeWorkflowState()` in `gates/orchestrator.ts` validates at write time.
|
|
221
|
-
3. If validation fails, the error lists valid enum values — fix and re-write. The skill blocks handoff on invalid artifacts.
|
|
222
|
-
|
|
223
|
-
## Handoff
|
|
224
|
-
|
|
225
|
-
After this skill completes, the harness proceeds to DISCOVERY (built into Ship SCOPE):
|
|
226
|
-
- **Output:** GitHub issue number + checkpoint path
|
|
227
|
-
- **Next step:** Project docs are read (PRINCIPLES.md -> ARCHITECTURE.md -> PROJECT-STATE.md)
|
|
228
|
-
|
|
229
|
-
## Termination Criteria
|
|
230
|
-
|
|
231
|
-
This skill terminates when:
|
|
232
|
-
1. A GitHub issue exists with all template sections populated
|
|
233
|
-
2. All SCs pass the garbage test
|
|
234
|
-
3. Checkpoint is written
|
|
235
|
-
4. Control returns to the harness for DISCOVERY
|