rungate 0.2.1 → 0.4.0

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.
Files changed (129) hide show
  1. package/bin/rungate.ts +70 -0
  2. package/lib/aes-calculator.ts +66 -0
  3. package/lib/agent-audit.ts +139 -0
  4. package/lib/agent-brief-validation.ts +359 -0
  5. package/lib/agents-md-refs.ts +90 -0
  6. package/lib/bash-file-read.ts +197 -0
  7. package/lib/behavioral-cache.ts +78 -0
  8. package/lib/branch-cleanup.ts +234 -0
  9. package/lib/brief-context-parser.ts +35 -0
  10. package/lib/brief-precedence.ts +114 -0
  11. package/lib/canary.ts +117 -0
  12. package/lib/check-registry.ts +226 -0
  13. package/lib/ci-checkout.ts +426 -0
  14. package/lib/cli-commands.ts +137 -0
  15. package/lib/compliance-backfill.ts +232 -0
  16. package/lib/compliance-report.ts +605 -0
  17. package/lib/compliance.ts +361 -0
  18. package/lib/config-loader.ts +255 -0
  19. package/lib/config-readers.ts +86 -0
  20. package/lib/conformity.ts +2161 -137
  21. package/lib/container-provenance.ts +230 -0
  22. package/lib/create-brief.ts +150 -0
  23. package/lib/create-sc.ts +267 -0
  24. package/lib/decomposition-waves.ts +197 -0
  25. package/lib/deep-merge.ts +69 -0
  26. package/lib/dev-liveness.ts +214 -0
  27. package/lib/directive-extractor.ts +210 -0
  28. package/lib/distribution-standing.ts +113 -0
  29. package/lib/doc-hygiene.ts +238 -0
  30. package/lib/eval-criteria.ts +6 -0
  31. package/lib/evidence-portability.ts +123 -0
  32. package/lib/evidence-prevalidator.ts +390 -0
  33. package/lib/evidence-required.ts +150 -0
  34. package/lib/evidence-satisfiability.ts +288 -0
  35. package/lib/frontmatter.ts +163 -0
  36. package/lib/gap-scanner.ts +348 -0
  37. package/lib/gate-check-audit.ts +190 -0
  38. package/lib/gate-enforcement.ts +366 -0
  39. package/lib/generators/agent-briefs.ts +136 -0
  40. package/lib/generators/agents-md.ts +511 -0
  41. package/lib/generators/code-map.ts +60 -0
  42. package/lib/generators/types.ts +184 -0
  43. package/lib/git-ref-normalizer.ts +107 -0
  44. package/lib/github.ts +539 -0
  45. package/lib/harness-identity.ts +63 -0
  46. package/lib/hill-climb.ts +164 -0
  47. package/lib/instruction-effectiveness.ts +131 -0
  48. package/lib/issue-closure-audit.ts +225 -0
  49. package/lib/issue-create-override.ts +343 -0
  50. package/lib/issue-extraction.ts +368 -0
  51. package/lib/js-top-level-code.ts +250 -0
  52. package/lib/liveness-contradiction.ts +149 -0
  53. package/lib/organize.ts +505 -0
  54. package/lib/paths.ts +197 -6
  55. package/lib/phase2-decomposition.ts +270 -0
  56. package/lib/post-fix-verify.ts +157 -0
  57. package/lib/prior-branch.ts +512 -0
  58. package/lib/project-state-shape.ts +166 -0
  59. package/lib/promote-outputs.ts +156 -0
  60. package/lib/prove-label-gate.ts +128 -0
  61. package/lib/reachability.ts +302 -0
  62. package/lib/release-preflight.ts +288 -0
  63. package/lib/rule-health-pipeline.ts +264 -0
  64. package/lib/rule-health-trend.ts +161 -0
  65. package/lib/rule-provenance.ts +149 -0
  66. package/lib/rule-registry.ts +128 -0
  67. package/lib/rungate-schema.ts +127 -5
  68. package/lib/sc-claim-forms.ts +179 -0
  69. package/lib/sc-cover.ts +150 -0
  70. package/lib/sc-guard.ts +157 -0
  71. package/lib/sc-ids.ts +344 -0
  72. package/lib/scaffold/defaults.ts +165 -0
  73. package/lib/scaffold/managed-workflow.ts +370 -0
  74. package/lib/scaffold/owned-files.ts +265 -0
  75. package/lib/scaffold/pre-push-hook.ts +165 -0
  76. package/lib/scaffold/steps.ts +2621 -0
  77. package/lib/scanner.ts +701 -0
  78. package/lib/scope-denylist.ts +258 -0
  79. package/lib/screenshot-upload.ts +73 -0
  80. package/lib/secret-patterns.ts +112 -0
  81. package/lib/security-verdict.ts +616 -0
  82. package/lib/signal-phrases.ts +1 -0
  83. package/lib/spec-change-conformity.ts +80 -0
  84. package/lib/spec-files.ts +62 -0
  85. package/lib/spec-registry.ts +133 -0
  86. package/lib/spec-updater.ts +96 -0
  87. package/lib/stale-cleanup.ts +224 -0
  88. package/lib/stale-issue-scanner.ts +36 -0
  89. package/lib/strip-js-comments.ts +269 -0
  90. package/lib/suite-measurement.ts +228 -0
  91. package/lib/task-completion-checks.ts +224 -0
  92. package/lib/test-suite-lock.ts +1136 -0
  93. package/lib/transcript-checker.ts +1140 -0
  94. package/lib/typescript-project.ts +233 -0
  95. package/lib/validators/spec-validators.ts +171 -0
  96. package/lib/verdict-capture.ts +73 -0
  97. package/lib/verified-push.ts +535 -0
  98. package/lib/workflow-security.ts +174 -0
  99. package/lib/worktree-cleanup.ts +432 -0
  100. package/lib/worktree-collect.ts +283 -0
  101. package/lib/worktree-isolation.ts +82 -0
  102. package/lib/worktree-repo.ts +300 -0
  103. package/package.json +27 -3
  104. package/prompts/ac-adversary.md +14 -2
  105. package/prompts/aditi.md +5 -0
  106. package/prompts/blast-radius.md +5 -0
  107. package/prompts/container-verify.md +5 -0
  108. package/prompts/discovery.md +4 -0
  109. package/prompts/environment.md +5 -0
  110. package/prompts/evidence-hierarchy.md +5 -0
  111. package/prompts/evidence-validator.md +11 -0
  112. package/prompts/marcus.md +5 -0
  113. package/prompts/prevention.md +5 -0
  114. package/prompts/prove-reproducer.md +12 -0
  115. package/prompts/quinn-decision-tree.md +5 -0
  116. package/prompts/quinn-ui-brief.md +5 -0
  117. package/prompts/quinn.md +5 -0
  118. package/prompts/rca.md +5 -0
  119. package/prompts/read-before-write.md +4 -0
  120. package/prompts/regression.md +5 -0
  121. package/prompts/serena.md +5 -0
  122. package/scripts/audit-specs.ts +464 -0
  123. package/scripts/convert-spec.ts +293 -0
  124. package/scripts/create-sc.ts +92 -0
  125. package/scripts/create-spec.ts +166 -0
  126. package/scripts/extract-constraints.ts +4 -3
  127. package/scripts/generate-code-map.ts +1 -1
  128. package/scripts/scaffold-project.ts +138 -1426
  129. package/scripts/sync-spec-tests.ts +211 -126
package/package.json CHANGED
@@ -1,31 +1,55 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.2.1",
3
+ "version": "0.4.0",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/hornjason/pai-harness.git"
9
+ },
10
+ "homepage": "https://github.com/hornjason/pai-harness#readme",
11
+ "bugs": {
12
+ "url": "https://github.com/hornjason/pai-harness/issues"
13
+ },
6
14
  "files": [
15
+ "bin/",
7
16
  "lib/",
8
17
  "prompts/",
9
18
  "scripts/scaffold-project.ts",
10
19
  "scripts/extract-constraints.ts",
20
+ "scripts/convert-spec.ts",
11
21
  "scripts/sync-spec-tests.ts",
12
22
  "scripts/generate-code-map.ts",
23
+ "scripts/audit-specs.ts",
24
+ "scripts/create-spec.ts",
25
+ "scripts/create-sc.ts",
13
26
  "package.json"
14
27
  ],
15
28
  "exports": {
16
29
  "./lib/conformity": "./lib/conformity.ts",
17
30
  "./lib/rungate-schema": "./lib/rungate-schema.ts",
18
- "./lib/signal-phrases": "./lib/signal-phrases.ts"
31
+ "./lib/signal-phrases": "./lib/signal-phrases.ts",
32
+ "./lib/compliance": "./lib/compliance.ts",
33
+ "./scripts/audit-specs": "./scripts/audit-specs.ts"
19
34
  },
20
35
  "scripts": {
21
36
  "test": "bun test",
37
+ "posttest": "bun scripts/sync-sc-status.ts",
38
+ "sync-scs": "bun scripts/sync-sc-status.ts",
39
+ "typecheck": "bun scripts/typecheck.ts",
22
40
  "test:structure": "bun test test/structure.test.ts",
23
41
  "test:external-deps": "bun test test/external-deps.test.ts"
24
42
  },
25
43
  "dependencies": {
44
+ "@octokit/rest": "^22.0.1",
45
+ "acorn": "^8.19.0",
26
46
  "zod": "^3.23.0"
27
47
  },
28
48
  "devDependencies": {
29
- "@types/bun": "latest"
49
+ "@types/bun": "latest",
50
+ "typescript": "5.9.3"
51
+ },
52
+ "bin": {
53
+ "rungate": "bin/rungate.ts"
30
54
  }
31
55
  }
@@ -1,3 +1,10 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-20
6
+ ---
7
+
1
8
  You are an adversarial AC reviewer. Your objective: find ways to pass
2
9
  every AC without actually fixing the bug.
3
10
 
@@ -10,11 +17,16 @@ For each AC, answer:
10
17
 
11
18
  Output as JSON:
12
19
  {
13
- "gameable": <number of gameable ACs>,
14
- "approved": <true if 0 gameable>,
20
+ "gameable": NUMBER_OF_GAMEABLE_ACS,
21
+ "approved": true_IF_0_GAMEABLE,
15
22
  "exploits": [
16
23
  {"acId": "SC-1", "exploit": "how to pass without fixing", "recommendation": "how to tighten"}
17
24
  ]
18
25
  }
19
26
 
20
27
  If ALL ACs are robust, output: {"gameable": 0, "approved": true, "exploits": []}
28
+
29
+ ### Never
30
+ - Never approve ACs where the evidence command can be passed by code that doesn't fix the stated problem
31
+ - Never accept self-attestation ("I verified it works") as a valid evidence method
32
+ - Never rate a structural check (file exists, grep count) as equivalent to a behavioral check (runtime output)
package/prompts/aditi.md CHANGED
@@ -27,3 +27,8 @@ You are Aditi Sharma, UI/UX designer. Specify component layouts and interaction
27
27
  ### Constraints
28
28
  - Use existing design system components first
29
29
  - shadcn/ui as component library baseline
30
+
31
+ ### Never
32
+ - Never skip accessibility requirements — every component spec must include ARIA roles and keyboard navigation
33
+ - Never ignore existing design system components in favor of custom elements — check shadcn/ui first
34
+ - Never deliver a component spec without error states and loading states
@@ -27,3 +27,8 @@ filesRead >= filesChanged — you must read more than you change.
27
27
  ### Gate enforcement
28
28
  - Read-before-write ratio >= 3:1 (read tokens / write tokens)
29
29
  - Files changed outside brief's listed files = WARN
30
+
31
+ ### Never
32
+ - Never change files not listed in the brief without explicit scope expansion approval
33
+ - Never skip reading dependent files before modifying their imports — downstream breakage is the most common blast-radius failure
34
+ - Never proceed when filesChanged > filesRead — stop and read more
@@ -26,3 +26,8 @@ After container-rebuild completes — before declaring deploy success.
26
26
  - Container HEAD: {sha}
27
27
  - Health: {response}
28
28
  - Failures: [list or "none"]
29
+
30
+ ### Never
31
+ - Never skip the health endpoint check — a running container is not the same as a healthy container
32
+ - Never declare container verified without completing smoke tests on critical endpoints
33
+ - Never report "verified" when the container HEAD doesn't match the expected commit SHA
@@ -25,3 +25,7 @@ DISCOVERY phase of ship cycle — before writing any code.
25
25
  - Key constraints discovered
26
26
  - Files that will be touched
27
27
  - Risks or unknowns to flag
28
+
29
+ ### Never
30
+ - Never write code before completing the discovery read list — implementation without context produces scope violations
31
+ - Never skip reading AGENTS.md — it contains project identity, constraints, and commands that govern all work
@@ -26,3 +26,8 @@ Ship DISCOVERY phase — after reading docs, before coding.
26
26
  - Environment: ready / blocked
27
27
  - Baseline test results: N pass, N fail
28
28
  - Blockers: [list or "none"]
29
+
30
+ ### Never
31
+ - Never skip environment verification and proceed directly to coding — a broken baseline wastes the entire session
32
+ - Never assume dependencies are installed — run the checks and capture actual output
33
+ - Never report "ready" with failing type checks or missing env vars
@@ -29,3 +29,8 @@ Gate enforcement — maps evidence types to tiers per AC type.
29
29
  - UI → B (browser verification)
30
30
  - BUG-FIX → S (negative control)
31
31
  - Static analysis → C supplementary only
32
+
33
+ ### Never
34
+ - Never accept tier F (self-attestation) evidence for any AC — it is always rejected
35
+ - Never mix evidence tiers to inflate a verdict — the weakest piece of evidence governs the tier
36
+ - Never use static grep (tier D) as the sole evidence for more than 25% of ACs
@@ -1,3 +1,10 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-20
6
+ ---
7
+
1
8
  You are an evidence validator. Your objective: run evidence commands
2
9
  independently and report whether results meet AC thresholds.
3
10
 
@@ -20,3 +27,7 @@ Report as JSON:
20
27
 
21
28
  Do not infer, assume, or extrapolate. If the command fails to run,
22
29
  verdict is FAIL with the error message as rawOutput.
30
+
31
+ ### Never
32
+ - Never infer or extrapolate evidence from partial command output — if the command didn't produce a clear result, verdict is FAIL
33
+ - Never modify source code — you run in a read-only worktree and exist solely to validate evidence
package/prompts/marcus.md CHANGED
@@ -27,3 +27,8 @@ You are Marcus Webb, principal engineer. You implement code changes, write tests
27
27
 
28
28
  ### Report format
29
29
  For each AC, provide evidence: file:line, grep output, or test result.
30
+
31
+ ### Never
32
+ - Never skip reading AGENTS.md as the first action — it contains project constraints that govern implementation
33
+ - Never report done without running the full test suite and capturing pass/fail counts
34
+ - Never implement without writing a failing test first (TDD is mandatory)
@@ -24,3 +24,8 @@ After identifying root cause — before implementing the fix.
24
24
  ### Example
25
25
  Bad: `if (x) doThing(x)` — fixes one caller
26
26
  Good: `function doThing(x: NonNullable<T>)` — prevents all callers
27
+
28
+ ### Never
29
+ - Never fix only the immediate instance without auditing sibling files for the same pattern
30
+ - Never skip the regression test — a fix without a test that would have caught it is incomplete
31
+ - Never add a guard without narrowing the type — runtime checks that the compiler can't enforce will recur
@@ -1,3 +1,10 @@
1
+ ---
2
+ doc-type: reference
3
+ status: active
4
+ owner: jason
5
+ updated: 2026-09-20
6
+ ---
7
+
1
8
  You are a prove reproducer. Your objective: reproduce the bug described
2
9
  in the issue, verify the fix works, and capture evidence.
3
10
 
@@ -41,3 +48,8 @@ Verdict rules:
41
48
  - PROVEN: bug was reproduced in before-state AND fix verified in after-state
42
49
  - UNPROVEN: fix does not resolve the issue (evidence shows problem persists)
43
50
  - INCONCLUSIVE: could not reproduce the bug or connect to dev server
51
+
52
+ ### Never
53
+ - Never claim UI verification without browser tools — output SKIP with reason "no browser tools — requires Quinn"
54
+ - Never infer evidence — every verdict needs captured command output, API response, or grep result
55
+ - Never report PROVEN without both reproducing the bug in before-state AND verifying the fix in after-state
@@ -29,3 +29,8 @@ Embedded in Quinn's brief — referenced during journey execution.
29
29
  ### Circuit breaker
30
30
  3 consecutive FAIL steps → abort journey, report partial results.
31
31
  Max 8 steps per journey — split longer flows.
32
+
33
+ ### Never
34
+ - Never skip pre-conditions — if the page isn't loaded or shows errors, report FAIL immediately without testing ACs
35
+ - Never report PASS without a11y snapshot or screenshot evidence backing the assertion
36
+ - Never use screenshots as the primary assertion method — browser_snapshot (a11y tree) is always primary
@@ -93,6 +93,11 @@ Overall: PASS | FAIL
93
93
  {If FAIL: blocking issues listed}
94
94
  ```
95
95
 
96
+ ### Never
97
+ - Never guess URLs — always use the pages map from rungate.json for target URLs
98
+ - Never skip viewport setup (browser_resize) before testing — assertions against wrong viewport produce false passes
99
+ - Never report PASS without attaching snapshot or screenshot evidence for each AC
100
+
96
101
  ## Interpolation Variables
97
102
 
98
103
  | Variable | Source |
package/prompts/quinn.md CHANGED
@@ -27,3 +27,8 @@ Each step: action → wait_for → assertion → on_fail
27
27
 
28
28
  ### Circuit breaker
29
29
  3 consecutive FAIL steps → abort journey with partial results.
30
+
31
+ ### Never
32
+ - Never trust prior test results — always run fresh browser assertions in the current state
33
+ - Never skip anti-checks even when all AC journey steps pass
34
+ - Never report PASS without snapshot or screenshot evidence attached
package/prompts/rca.md CHANGED
@@ -26,3 +26,8 @@ Marcus brief for bug-fix issues — required RCA section.
26
26
  3. Identify the exact line where behavior diverges from expected
27
27
  4. State root cause as "X happens because Y at file:line"
28
28
  5. Predict the fix outcome before implementing
29
+
30
+ ### Never
31
+ - Never implement a fix without first reproducing the bug — an unreproduced bug means you're guessing at root cause
32
+ - Never skip the prediction step — state what will happen after the fix before implementing it
33
+ - Never fix at the symptom level when the root cause is upstream in the data flow
@@ -28,3 +28,7 @@ Read-to-write ratio >= 3:1 (measured in tokens).
28
28
 
29
29
  ### Gate check
30
30
  `readTokens / writeTokens >= 3.0` — FAIL if under.
31
+
32
+ ### Never
33
+ - Never write code before reading at least 3x the tokens you plan to write — the gate enforces this mechanically
34
+ - Never skip reading dependency files that import the files you'll change — downstream breakage from unread dependents is the top failure mode
@@ -24,3 +24,8 @@ After implementing a fix — before marking AC complete.
24
24
  ### Gate enforcement
25
25
  - Test count post >= test count pre — decrease = FAIL
26
26
  - Zero test removals without explicit rationale
27
+
28
+ ### Never
29
+ - Never delete existing tests to make a new fix pass — test removals require explicit rationale
30
+ - Never skip the negative control (reverting the fix to confirm the test fails without it)
31
+ - Never write a test that covers only the symptom — test the root cause
package/prompts/serena.md CHANGED
@@ -26,3 +26,8 @@ You are Serena Blackwood, architect. Evaluate structural decisions before implem
26
26
 
27
27
  ### Output
28
28
  ADR recommendation or architecture approval with cited file:line evidence.
29
+
30
+ ### Never
31
+ - Never approve shallow wrappers that add indirection without information hiding — demand deep modules
32
+ - Never skip contract test coverage for shared interfaces — untested contracts break silently at integration
33
+ - Never approve an architectural change without citing file:line evidence from the current codebase