projscan 4.13.0 → 4.15.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 (195) hide show
  1. package/README.md +90 -24
  2. package/dist/cli/commands/evidencePack.js +2 -0
  3. package/dist/cli/commands/evidencePack.js.map +1 -1
  4. package/dist/cli/commands/prove.js +253 -23
  5. package/dist/cli/commands/prove.js.map +1 -1
  6. package/dist/cli/commands/startConsole.d.ts +2 -2
  7. package/dist/cli/commands/startConsole.js +2 -260
  8. package/dist/cli/commands/startConsole.js.map +1 -1
  9. package/dist/cli/commands/startConsoleExecution.d.ts +5 -0
  10. package/dist/cli/commands/startConsoleExecution.js +108 -0
  11. package/dist/cli/commands/startConsoleExecution.js.map +1 -0
  12. package/dist/cli/commands/startConsoleMission.d.ts +6 -0
  13. package/dist/cli/commands/startConsoleMission.js +157 -0
  14. package/dist/cli/commands/startConsoleMission.js.map +1 -0
  15. package/dist/cli/commands/startMissionBundle.js +24 -27
  16. package/dist/cli/commands/startMissionBundle.js.map +1 -1
  17. package/dist/core/adoption.d.ts +8 -81
  18. package/dist/core/adoption.js +4 -549
  19. package/dist/core/adoption.js.map +1 -1
  20. package/dist/core/adoptionFirstRunDiagnostics.d.ts +20 -0
  21. package/dist/core/adoptionFirstRunDiagnostics.js +240 -0
  22. package/dist/core/adoptionFirstRunDiagnostics.js.map +1 -0
  23. package/dist/core/adoptionMcpConfig.d.ts +27 -0
  24. package/dist/core/adoptionMcpConfig.js +123 -0
  25. package/dist/core/adoptionMcpConfig.js.map +1 -0
  26. package/dist/core/adoptionMcpDoctor.d.ts +23 -0
  27. package/dist/core/adoptionMcpDoctor.js +87 -0
  28. package/dist/core/adoptionMcpDoctor.js.map +1 -0
  29. package/dist/core/adoptionWorkflowRecipes.d.ts +14 -0
  30. package/dist/core/adoptionWorkflowRecipes.js +110 -0
  31. package/dist/core/adoptionWorkflowRecipes.js.map +1 -0
  32. package/dist/core/bugHunt.js +26 -255
  33. package/dist/core/bugHunt.js.map +1 -1
  34. package/dist/core/bugHuntPreflightFindings.d.ts +2 -1
  35. package/dist/core/bugHuntPreflightFindings.js +20 -0
  36. package/dist/core/bugHuntPreflightFindings.js.map +1 -1
  37. package/dist/core/bugHuntReportAssembly.d.ts +20 -0
  38. package/dist/core/bugHuntReportAssembly.js +179 -0
  39. package/dist/core/bugHuntReportAssembly.js.map +1 -0
  40. package/dist/core/bugHuntSourceFindings.d.ts +3 -0
  41. package/dist/core/bugHuntSourceFindings.js +61 -0
  42. package/dist/core/bugHuntSourceFindings.js.map +1 -0
  43. package/dist/core/dogfood.js +4 -393
  44. package/dist/core/dogfood.js.map +1 -1
  45. package/dist/core/dogfoodMarketValidation.d.ts +5 -0
  46. package/dist/core/dogfoodMarketValidation.js +265 -0
  47. package/dist/core/dogfoodMarketValidation.js.map +1 -0
  48. package/dist/core/dogfoodRepoEvaluation.d.ts +4 -0
  49. package/dist/core/dogfoodRepoEvaluation.js +137 -0
  50. package/dist/core/dogfoodRepoEvaluation.js.map +1 -0
  51. package/dist/core/evidenceComment.js +50 -13
  52. package/dist/core/evidenceComment.js.map +1 -1
  53. package/dist/core/feedback.js +2 -252
  54. package/dist/core/feedback.js.map +1 -1
  55. package/dist/core/feedbackIntakeClassifier.d.ts +2 -0
  56. package/dist/core/feedbackIntakeClassifier.js +255 -0
  57. package/dist/core/feedbackIntakeClassifier.js.map +1 -0
  58. package/dist/core/intentRouterCatalog.js +34 -0
  59. package/dist/core/intentRouterCatalog.js.map +1 -1
  60. package/dist/core/intentRouterKeywordToolGuards.js +2 -46
  61. package/dist/core/intentRouterKeywordToolGuards.js.map +1 -1
  62. package/dist/core/intentRouterKeywordWeights.js +13 -28
  63. package/dist/core/intentRouterKeywordWeights.js.map +1 -1
  64. package/dist/core/intentRouterProductGuardSignals.d.ts +3 -0
  65. package/dist/core/intentRouterProductGuardSignals.js +59 -0
  66. package/dist/core/intentRouterProductGuardSignals.js.map +1 -0
  67. package/dist/core/intentRouterWorkflowKeywordWeights.js +29 -0
  68. package/dist/core/intentRouterWorkflowKeywordWeights.js.map +1 -1
  69. package/dist/core/markdownSafety.d.ts +3 -0
  70. package/dist/core/markdownSafety.js +14 -0
  71. package/dist/core/markdownSafety.js.map +1 -0
  72. package/dist/core/preflight.d.ts +2 -0
  73. package/dist/core/preflight.js.map +1 -1
  74. package/dist/core/preflightChangedFiles.d.ts +2 -0
  75. package/dist/core/preflightChangedFiles.js +1 -1
  76. package/dist/core/preflightChangedFiles.js.map +1 -1
  77. package/dist/core/preflightInputs.d.ts +2 -0
  78. package/dist/core/preflightInputs.js +5 -2
  79. package/dist/core/preflightInputs.js.map +1 -1
  80. package/dist/core/proofLedger.d.ts +6 -1
  81. package/dist/core/proofLedger.js +174 -15
  82. package/dist/core/proofLedger.js.map +1 -1
  83. package/dist/core/proofReplay.d.ts +9 -0
  84. package/dist/core/proofReplay.js +164 -0
  85. package/dist/core/proofReplay.js.map +1 -0
  86. package/dist/core/proofSufficiency.d.ts +19 -0
  87. package/dist/core/proofSufficiency.js +425 -0
  88. package/dist/core/proofSufficiency.js.map +1 -0
  89. package/dist/core/prove.d.ts +8 -0
  90. package/dist/core/prove.js +578 -88
  91. package/dist/core/prove.js.map +1 -1
  92. package/dist/core/qualityScorecard.js +8 -238
  93. package/dist/core/qualityScorecard.js.map +1 -1
  94. package/dist/core/qualityScorecardDimensions.d.ts +14 -0
  95. package/dist/core/qualityScorecardDimensions.js +99 -0
  96. package/dist/core/qualityScorecardDimensions.js.map +1 -0
  97. package/dist/core/qualityScorecardRisks.d.ts +8 -0
  98. package/dist/core/qualityScorecardRisks.js +107 -0
  99. package/dist/core/qualityScorecardRisks.js.map +1 -0
  100. package/dist/core/qualityScorecardSignals.d.ts +20 -0
  101. package/dist/core/qualityScorecardSignals.js +59 -0
  102. package/dist/core/qualityScorecardSignals.js.map +1 -0
  103. package/dist/core/releaseEvidence.d.ts +1 -0
  104. package/dist/core/releaseEvidence.js +15 -40
  105. package/dist/core/releaseEvidence.js.map +1 -1
  106. package/dist/core/releaseEvidenceBaseline.js +4 -1
  107. package/dist/core/releaseEvidenceBaseline.js.map +1 -1
  108. package/dist/core/releaseEvidenceProofReceipt.d.ts +6 -0
  109. package/dist/core/releaseEvidenceProofReceipt.js +140 -0
  110. package/dist/core/releaseEvidenceProofReceipt.js.map +1 -0
  111. package/dist/core/releaseEvidenceVerdict.d.ts +5 -2
  112. package/dist/core/releaseEvidenceVerdict.js +39 -1
  113. package/dist/core/releaseEvidenceVerdict.js.map +1 -1
  114. package/dist/core/repositoryScanner.d.ts +1 -0
  115. package/dist/core/repositoryScanner.js +5 -4
  116. package/dist/core/repositoryScanner.js.map +1 -1
  117. package/dist/core/sessionResources.d.ts +14 -2
  118. package/dist/core/sessionResources.js +3 -3
  119. package/dist/core/sessionResources.js.map +1 -1
  120. package/dist/core/startFixedRouteCriteria.js +4 -0
  121. package/dist/core/startFixedRouteCriteria.js.map +1 -1
  122. package/dist/core/startInputs.d.ts +1 -1
  123. package/dist/core/startIntentTargets.d.ts +1 -1
  124. package/dist/core/startIntentTargets.js +1 -16
  125. package/dist/core/startIntentTargets.js.map +1 -1
  126. package/dist/core/startMissionInputStatusPolicy.d.ts +7 -0
  127. package/dist/core/startMissionInputStatusPolicy.js +74 -0
  128. package/dist/core/startMissionInputStatusPolicy.js.map +1 -0
  129. package/dist/core/startMissionPolicy.d.ts +6 -15
  130. package/dist/core/startMissionPolicy.js +4 -305
  131. package/dist/core/startMissionPolicy.js.map +1 -1
  132. package/dist/core/startMissionProofPolicy.d.ts +6 -0
  133. package/dist/core/startMissionProofPolicy.js +84 -0
  134. package/dist/core/startMissionProofPolicy.js.map +1 -0
  135. package/dist/core/startMissionRiskPolicy.d.ts +4 -0
  136. package/dist/core/startMissionRiskPolicy.js +85 -0
  137. package/dist/core/startMissionRiskPolicy.js.map +1 -0
  138. package/dist/core/startMissionRoutingPolicy.d.ts +6 -0
  139. package/dist/core/startMissionRoutingPolicy.js +67 -0
  140. package/dist/core/startMissionRoutingPolicy.js.map +1 -0
  141. package/dist/core/startMode.d.ts +1 -2
  142. package/dist/core/startMode.js +4 -151
  143. package/dist/core/startMode.js.map +1 -1
  144. package/dist/core/startModeIntentPolicy.d.ts +12 -0
  145. package/dist/core/startModeIntentPolicy.js +41 -0
  146. package/dist/core/startModeIntentPolicy.js.map +1 -0
  147. package/dist/core/startModeRoutingPolicy.d.ts +4 -0
  148. package/dist/core/startModeRoutingPolicy.js +117 -0
  149. package/dist/core/startModeRoutingPolicy.js.map +1 -0
  150. package/dist/core/startRouteActions.js +5 -0
  151. package/dist/core/startRouteActions.js.map +1 -1
  152. package/dist/core/startSearchQueryTargets.d.ts +1 -0
  153. package/dist/core/startSearchQueryTargets.js +17 -0
  154. package/dist/core/startSearchQueryTargets.js.map +1 -0
  155. package/dist/core/workplan.d.ts +3 -2
  156. package/dist/core/workplan.js +11 -585
  157. package/dist/core/workplan.js.map +1 -1
  158. package/dist/core/workplanCoordinationTasks.d.ts +3 -0
  159. package/dist/core/workplanCoordinationTasks.js +82 -0
  160. package/dist/core/workplanCoordinationTasks.js.map +1 -0
  161. package/dist/core/workplanModeTasks.d.ts +2 -0
  162. package/dist/core/workplanModeTasks.js +192 -0
  163. package/dist/core/workplanModeTasks.js.map +1 -0
  164. package/dist/core/workplanPreflightTasks.d.ts +2 -0
  165. package/dist/core/workplanPreflightTasks.js +126 -0
  166. package/dist/core/workplanPreflightTasks.js.map +1 -0
  167. package/dist/core/workplanQualitySignals.d.ts +7 -0
  168. package/dist/core/workplanQualitySignals.js +63 -0
  169. package/dist/core/workplanQualitySignals.js.map +1 -0
  170. package/dist/core/workplanReport.d.ts +4 -0
  171. package/dist/core/workplanReport.js +79 -0
  172. package/dist/core/workplanReport.js.map +1 -0
  173. package/dist/core/workplanRiskOwnership.d.ts +5 -0
  174. package/dist/core/workplanRiskOwnership.js +97 -0
  175. package/dist/core/workplanRiskOwnership.js.map +1 -0
  176. package/dist/core/workplanSuggestedActions.d.ts +2 -0
  177. package/dist/core/workplanSuggestedActions.js +43 -0
  178. package/dist/core/workplanSuggestedActions.js.map +1 -0
  179. package/dist/mcp/tools/prove.js +24 -18
  180. package/dist/mcp/tools/prove.js.map +1 -1
  181. package/dist/projscan-sbom.cdx.json +6 -6
  182. package/dist/tool-manifest.json +3 -3
  183. package/dist/types/config.d.ts +15 -0
  184. package/dist/types/evidencePack.d.ts +21 -0
  185. package/dist/types/proofLedger.d.ts +1 -1
  186. package/dist/types/prove.d.ts +96 -1
  187. package/dist/utils/changedFiles.js +57 -16
  188. package/dist/utils/changedFiles.js.map +1 -1
  189. package/dist/utils/config.js +2 -0
  190. package/dist/utils/config.js.map +1 -1
  191. package/dist/utils/configProofRecipes.d.ts +2 -0
  192. package/dist/utils/configProofRecipes.js +91 -0
  193. package/dist/utils/configProofRecipes.js.map +1 -0
  194. package/docs/GUIDE.md +145 -25
  195. package/package.json +1 -1
package/README.md CHANGED
@@ -79,35 +79,47 @@ projscan start --intent "does projscan read .env values?"
79
79
 
80
80
  ## Daily workflows
81
81
 
82
- Use these three workflows before scanning the full command catalog.
82
+ Use these four workflows before scanning the full command catalog.
83
83
 
84
84
  ### Before editing a feature
85
85
 
86
86
  ```bash
87
87
  projscan start --intent "what files do I need to change for auth?"
88
88
  projscan start --intent "what should we build next?" # Routes to a before-edit implementation workplan
89
+ projscan start --intent "is my agent allowed to change billing retry logic?"
89
90
  projscan understand --view change --intent "add auth token refresh" --format json
90
91
  projscan prove --intent "is my agent allowed to change billing retry logic?"
91
92
  projscan preflight --mode before_edit --format json
92
93
  ```
93
94
 
94
- You get a cited change map, read-first files, likely touched files, blocked inputs, an executable Proof Contract, and a before-edit proof gate.
95
+ You get a cited change map, read-first files, likely touched files, blocked inputs, an executable Proof Contract, and a before-edit proof gate. Agent-permission intents route to `projscan prove`, so `start` can hand the next agent a contract path instead of a broad checklist.
95
96
 
96
97
  Success criteria: the agent can name the files to read first, the likely files to touch, the forbidden files to avoid, and the proof commands to run before editing.
97
98
 
98
- ### Before handing work to an agent
99
+ ### Verified change workflow
99
100
 
100
101
  ```bash
102
+ projscan start --intent "is my agent allowed to change billing retry logic?"
101
103
  projscan prove --intent "is my agent allowed to change billing retry logic?" --save-contract .projscan/proof-contract.json
102
- projscan prove --record-command "npm test -- tests/billing/retry.test.ts" --exit-code 0 --duration-ms 1842 --summary "billing retry tests passed"
104
+ # Make the bounded edit, then run the proof command.
105
+ projscan prove --run -- npm test -- tests/billing/retry.test.ts
103
106
  projscan prove --changed --contract .projscan/proof-contract.json --format markdown
104
107
  ```
105
108
 
106
- You get a Proof Contract before edits and a Proof Receipt after edits. The contract names allowed files, forbidden files, risky contracts, likely tests, missing regression-test evidence, proof commands, safe change shape, rollback, confidence, and reviewer guidance. The receipt checks the real working tree against that contract and classifies changed files as allowed production, expected tests, documentation, generated proof artifacts, config/security drift, forbidden touches, or unexpected production. It also reports proof replay status, risk delta, commit readiness, and a reviewer checklist.
109
+ The command path is `start -> prove -> run -> changed`. Make the bounded edit after the contract exists and before `prove --run`. `start` chooses the contract workflow. `prove --intent` writes `.projscan/proof-contract.json` only when `--save-contract` is present. `prove --run -- <command...>` executes a local proof command, records the exit code, captures a redacted log, and fingerprints the current changed files. `prove --record-command` remains available for imported CI or external evidence when projscan did not run the command. `prove --changed` checks the current working tree against the contract and local ledger.
107
110
 
108
- Proof Replay records command, exit code, duration, changed-file fingerprint, redacted summary, and optional log path in `.projscan/proof-ledger.jsonl`. `prove --changed` marks proof as passed, missing, failed, partial, or stale. If the agent edits new files after proof ran, the receipt says the proof is stale before a reviewer reads the diff.
111
+ You get a Proof Contract before edits and a Proof Receipt after edits. The contract names allowed files, forbidden files, risky contracts, likely tests, missing regression-test evidence, proof commands, safe change shape, rollback, confidence, reviewer guidance, and `proofRequirements` for each risk surface. The receipt checks the real working tree against that contract and classifies changed files as allowed production, expected tests, documentation, generated proof artifacts, config/security drift, forbidden touches, or unexpected production. The receipt reports proof replay status, Proof Sufficiency, risk delta, commit readiness, and a reviewer checklist.
109
112
 
110
- Success criteria: the reviewer sees whether the agent stayed inside the contract, whether the right proof ran, and whether that proof is still fresh.
113
+ Proof Replay records command, exit code, duration, changed-file fingerprint, redacted summary, log path, and source in `.projscan/proof-ledger.jsonl`. Executed proof logs stay under `.projscan/proof-logs/`. `prove --changed` marks proof as passed, missing, failed, partial, or stale. The receipt JSON includes `proofReplay` with a replay timeline, `changedAfterProof`, replay command, and local receipt fingerprint. If the agent edits new files after proof ran, the receipt says the proof is stale before a reviewer reads the diff.
114
+
115
+ Proof Sufficiency estimates whether the local ledger covers each changed surface. `proofSufficiency` marks rows as strong, adequate, weak, missing, stale, or failed, then lists the exact gaps reviewers need to resolve.
116
+
117
+ Team Proof Recipes let a repo encode required proof for sensitive paths in `proofRecipes`; when a matching recipe is configured, `prove --intent` adds that recipe's commands, reviewers, and forbidden files to the Proof Contract. `prove --changed` and `projscan evidence-pack --pr-comment` then show missing recipe proof, required reviewers, and recipe drift in the Proof Receipt. The recipe does not run proof commands by itself; use `prove --run -- <command...>` or `prove --record-command` to add evidence to the local ledger.
118
+ Saved contracts are the source of truth for `prove --changed`; update the contract when a team recipe changes.
119
+
120
+ Every `prove` report includes `verifiedWorkflow`, a compact JSON summary for agents and MCP clients. It names the phase, next action, next command, scope status, proof status, proof sufficiency status, risk delta direction, reviewer decision, and stale/missing/failed proof flags.
121
+
122
+ Success criteria: the reviewer sees scope, proof execution, proof freshness, and sufficiency for the changed risk surface.
111
123
 
112
124
  ### Before handoff or commit
113
125
 
@@ -118,7 +130,7 @@ projscan preflight --mode before_commit --format json
118
130
  projscan evidence-pack --pr-comment
119
131
  ```
120
132
 
121
- You get the changed-file risk, one or two trusted next actions, manual review gates, owner routing, baseline trend memory, and exact proof commands for the reviewer. Use `projscan bug-hunt --format json` when you want the raw fix queue behind the assessment.
133
+ You get changed-file risk, one or two ranked next actions, manual review gates, owner routing, baseline trend memory, and exact proof commands for the reviewer. Use `projscan bug-hunt --format json` when you want the raw fix queue behind the assessment.
122
134
 
123
135
  Success criteria: the reviewer sees the top fix, the remaining proof, and any manual sign-off gate without reading the full scan output.
124
136
 
@@ -191,33 +203,72 @@ npm run docs:screenshots
191
203
  npm run docs:demos
192
204
  ```
193
205
 
194
- ## 4.13.0 Notes
206
+ ## 4.15.0 Notes
195
207
 
196
- 4.13.0 ships Proof Replay for Executable Proof Contracts:
208
+ 4.15.0 strengthens the proof-first change loop:
197
209
 
198
210
  - `projscan prove --intent "<change>"` creates a local Proof Contract before
199
211
  editing. It names allowed files, forbidden files, risky contracts, likely
200
212
  tests, missing regression-test evidence, proof commands, rollback, confidence,
201
- Trust Memory signals, evidence gaps, and reviewer guidance. Noisy feedback or
202
- missing-signal feedback lowers the confidence reason instead of hiding it.
213
+ Trust Memory signals, evidence gaps, reviewer guidance, and
214
+ `proofRequirements` for each risk surface.
215
+ - `projscan start --intent "is my agent allowed to change billing retry logic?"`
216
+ routes directly to `projscan prove`, so agent-permission prompts start with a
217
+ bounded contract instead of a broad checklist.
218
+ - `projscan prove --run -- <command...>` executes an explicit local proof
219
+ command with shell execution disabled, writes a redacted log under
220
+ `.projscan/proof-logs/`, appends a `prove-run` ledger row, and lets
221
+ `prove --changed` replay executed proof instead of self-reported evidence.
203
222
  - `projscan prove --changed` validates the current working tree against a saved
204
223
  contract and emits a Proof Receipt for PRs, agents, and CI. Its changed-file
205
224
  classes separate allowed production edits, expected tests, documentation,
206
225
  generated proof artifacts, config/security drift, forbidden touches, and
207
226
  unexpected production changes before giving a copyable reviewer decision.
227
+ The receipt also includes `proofReplay` with replay status, timeline events,
228
+ `changedAfterProof`, replay command, and receipt fingerprint. Proof
229
+ Sufficiency shows whether each `proofRequirements` row has strong, adequate,
230
+ weak, missing, stale, or failed proof.
231
+ - Team Proof Recipes let a repo add path-matched `proofRecipes` to
232
+ `.projscanrc.json`. Matching recipes add required commands, reviewers, and
233
+ forbidden drift to the Proof Contract and Proof Receipt.
208
234
  - `projscan prove --record-command "<command>" --exit-code <code>` appends a
209
235
  local Proof Ledger row with command, duration, changed-file fingerprint,
210
- redacted output summary, and optional log path. `prove --changed` replays
211
- those rows and reports passed, missing, failed, partial, or stale proof.
236
+ redacted output summary, and optional log path when importing proof from CI or
237
+ another runner.
238
+ - Every `prove` JSON report includes `verifiedWorkflow`, so agents can read the
239
+ next action, next command, scope status, proof status, `proofSufficiency`
240
+ status, reviewer decision, and stale/missing/failed proof flags without
241
+ parsing Markdown.
212
242
  - Saved Mission Control bundles append Proof Ledger rows while `mission.sh`
213
243
  runs the existing proof queue. The script still writes proof logs and status
214
244
  JSONL for humans.
215
245
  - `projscan evidence-pack --pr-comment` includes the latest Proof Receipt
216
246
  summary when a contract and ledger are available, so PR comments show proof
217
- status, reviewer decision, scope, stale proof, failed proof, and the replay
218
- command.
247
+ status, proof replay, reviewer decision, scope, stale proof, failed proof,
248
+ proof sufficiency, recipe gaps, required reviewers, changed-after-proof files,
249
+ receipt fingerprint, and the replay command.
250
+ - Proof artifacts are harder to spoof: Proof Contract and Proof Ledger reads
251
+ reject symlink escapes, proof logs redact more standalone token/key shapes,
252
+ and generated mission scripts reject shell control syntax before running.
253
+ - The codebase behind the proof workflow is smaller and easier to review:
254
+ source hotspots in Mission Control, bug-hunt, quality-scorecard, workplan,
255
+ adoption, start-mode routing, and intent routing were split into focused
256
+ helpers with architecture tests.
219
257
  - MCP now includes `projscan_prove`, bringing the MCP surface to 48 tools.
220
258
 
259
+ ## 4.14.0 Notes
260
+
261
+ 4.14.0 ships the Verified Change Workflow and Executed Proof Runner:
262
+
263
+ - `projscan prove --intent "<change>"` creates a local Proof Contract before
264
+ editing.
265
+ - `projscan prove --run -- <command...>` executes an explicit local proof
266
+ command with shell execution disabled and writes a redacted Proof Ledger row.
267
+ - `projscan prove --changed` emits a Proof Receipt for PRs, agents, and CI.
268
+ - `projscan evidence-pack --pr-comment` includes the latest Proof Receipt
269
+ summary when a contract and ledger are available.
270
+ - MCP includes `projscan_prove`, bringing the MCP surface to 48 tools.
271
+
221
272
  ## 4.12.1 Notes
222
273
 
223
274
  4.12.1 is the simulator precision patch for the Proof Cards V2 release:
@@ -248,7 +299,7 @@ npm run docs:demos
248
299
 
249
300
  - Added a dedicated Proof Cards screenshot for `projscan assess` and
250
301
  `projscan simulate`.
251
- - Regenerated README screenshots so public media shows the current 47-tool MCP
302
+ - Regenerated README screenshots so public media showed the 47-tool MCP
252
303
  surface.
253
304
  - Updated website handoff guidance to use immutable `v4.11.1` media URLs.
254
305
 
@@ -300,7 +351,7 @@ npx -y projscan mcp --watch
300
351
  | What should I fix first? | `projscan bug-hunt --format json` |
301
352
  | What is risky and worth fixing this week? | `projscan assess --goal "make this repo safer to ship this week"` |
302
353
  | Is this refactor worth doing? | `projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"` |
303
- | Is my agent allowed to make this change? | `projscan prove --intent "is my agent allowed to change billing retry logic?"` |
354
+ | Is my agent allowed to make this change? | `projscan start --intent "is my agent allowed to change billing retry logic?"` |
304
355
  | Did the change stay inside scope? | `projscan prove --changed --contract .projscan/proof-contract.json --format markdown` |
305
356
  | Which files have high risk and low coverage? | `projscan coverage --format json` |
306
357
  | What should my agent do next? | `projscan workplan --format json` |
@@ -316,8 +367,8 @@ npx -y projscan mcp --watch
316
367
  | `projscan preflight` | proceed, caution, or block gate for edit, commit, or merge |
317
368
  | `projscan assess` | proof-first assessment with Proof Cards, risk delta, and fix-first guidance |
318
369
  | `projscan simulate` | risk delta simulator for a proposed change plan before editing |
319
- | `projscan prove` | executable Proof Contracts and reviewer-ready Proof Receipts |
320
- | `projscan evidence-pack` | PR-ready proof with risks, owners, and next commands |
370
+ | `projscan prove` | executable Proof Contracts, Verified Workflow JSON, and Proof Receipts |
371
+ | `projscan evidence-pack` | review evidence with risks, owners, proof receipts, and next commands |
321
372
  | `projscan bug-hunt` | ranked fix queue from health, hotspots, session, and preflight evidence |
322
373
  | `projscan workplan` | ordered agent tasks with proof and handoff text |
323
374
  | `projscan doctor` | project health, tooling gaps, dead code, and supply-chain signals |
@@ -384,6 +435,15 @@ Create a `.projscanrc.json` when repo defaults should live in source control:
384
435
  "severityOverrides": {
385
436
  "missing-prettier": "info"
386
437
  },
438
+ "proofRecipes": [
439
+ {
440
+ "id": "billing-critical",
441
+ "matches": ["src/billing/**"],
442
+ "requiredCommands": ["npm test -- tests/billing/retry.test.ts"],
443
+ "requiredReviewers": ["@platform"],
444
+ "forbiddenFiles": ["src/auth/**"]
445
+ }
446
+ ],
387
447
  "reportPolicies": {
388
448
  "apiEvidence": {
389
449
  "reportScope": ["src/api", "packages/backend"],
@@ -400,6 +460,12 @@ the rule everywhere. For one line, add an inline directive next to the value:
400
460
  const firebaseKey = 'AIza...'; // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers
401
461
  ```
402
462
 
463
+ Use `proofRecipes` when a path needs team-specific proof; when a matching recipe
464
+ is configured, `projscan prove` adds its proof commands, reviewers, and forbidden
465
+ files to the contract and receipt. It does not run proof commands by itself.
466
+ Recipes without `requiredCommands` are skipped, and duplicate recipe IDs keep the
467
+ first valid recipe.
468
+
403
469
  Config docs live in [docs/GUIDE.md](docs/GUIDE.md#configuration-projscanrc).
404
470
 
405
471
  ## CI
@@ -475,7 +541,7 @@ Plugin docs:
475
541
 
476
542
  ## Supported Repos
477
543
 
478
- projscan reads TypeScript, JavaScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, C, and C++ with AST-aware adapters where available. It also detects file-level signals for Shell, CSS, HTML, SQL, Dart, Lua, Scala, R, and related project files.
544
+ projscan reads TypeScript, JavaScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++ with AST-aware adapters where available. It also detects file-level signals for C, Shell, CSS, HTML, SQL, Dart, Lua, Scala, R, and related project files.
479
545
 
480
546
  Framework signals cover React, Next.js, Vue, Nuxt, Svelte, Angular, Express, Fastify, NestJS, Vite, Tailwind CSS, Prisma, Remix, SvelteKit, Astro, Hono, Koa, and common monorepo layouts.
481
547
 
@@ -491,7 +557,7 @@ JavaScript and TypeScript use `@babel/parser`. Non-JS languages use packaged tre
491
557
  | Network | `audit`, registry checks, opt-in telemetry, and optional semantic model download can contact the network. |
492
558
  | Telemetry | Off until you run `projscan telemetry enable` or accept the `init team` prompt. |
493
559
  | Plugins | Local plugin code runs after `PROJSCAN_PLUGINS_PREVIEW=1` and an execution path such as `doctor`, `ci`, `analyze`, or `plugin test --execute`. |
494
- | Repo writes | Source writes require explicit fix commands. Cache and mission proof files stay under local projscan directories. |
560
+ | Repo writes | Source writes require explicit fix commands. Caches, saved missions, Proof Contracts, Proof Ledger rows, and proof logs stay under `.projscan*` local directories. |
495
561
 
496
562
  Audit helpers:
497
563
 
@@ -506,7 +572,7 @@ Supply-chain scanners may flag package strings or APIs used by `git`, `npm audit
506
572
 
507
573
  ## Install Notes
508
574
 
509
- `projscan@4.13.0` has seven direct runtime dependencies:
575
+ `projscan@4.15.0` has seven direct runtime dependencies:
510
576
 
511
577
  - `@babel/parser`
512
578
  - `@babel/types`
@@ -516,7 +582,7 @@ Supply-chain scanners may flag package strings or APIs used by `git`, `npm audit
516
582
  - `ora`
517
583
  - `web-tree-sitter`
518
584
 
519
- If npm prints `allow-scripts` warnings during a global install, check which package names it lists. projscan core does not need `node-gyp` grammar builds at runtime in 4.13.0. Open an issue with the warning text if npm reports install scripts from `projscan@latest`, or run `projscan feedback intake --text "<warning text>" --format json` to turn it into a focused setup-trust task.
585
+ If npm prints `allow-scripts` warnings during a global install, check which package names it lists. projscan core does not need `node-gyp` grammar builds at runtime in 4.15.0. Open an issue with the warning text if npm reports install scripts from `projscan@latest`, or run `projscan feedback intake --text "<warning text>" --format json` to turn it into a focused setup-trust task.
520
586
 
521
587
  The grammar packages are build-time sources, not global-install dependencies. Published grammar assets include `tree-sitter-python.wasm` and `tree-sitter-c_sharp.wasm`.
522
588
 
@@ -8,6 +8,7 @@ export function registerEvidencePack() {
8
8
  .option('--line <line>', 'product line to include, repeatable (default: next six minor lines)', collectLine, [])
9
9
  .option('--website-prompt', 'include website-update prompt text')
10
10
  .option('--pr-comment', 'print a GitHub PR comment markdown artifact')
11
+ .option('--base-ref <ref>', 'explicit git base ref for review evidence')
11
12
  .option('--max-findings <count>', 'maximum bug-hunt findings to include', parsePositiveInt)
12
13
  .action(async (cmdOpts) => {
13
14
  setupLogLevel();
@@ -18,6 +19,7 @@ export function registerEvidencePack() {
18
19
  lines: cmdOpts.line,
19
20
  includeWebsitePrompt: cmdOpts.websitePrompt === true,
20
21
  includePrComment: cmdOpts.prComment === true,
22
+ baseRef: cmdOpts.baseRef,
21
23
  maxFindings: cmdOpts.maxFindings,
22
24
  });
23
25
  if (format === 'json') {
@@ -1 +1 @@
1
- {"version":3,"file":"evidencePack.js","sourceRoot":"","sources":["../../../src/cli/commands/evidencePack.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"evidencePack.js","sourceRoot":"","sources":["../../../src/cli/commands/evidencePack.ts"],"names":[],"mappings":"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"}