peaks-loop 4.1.4 → 4.1.5
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/.claude-plugin/marketplace.json +7 -2
- package/CHANGELOG.md +112 -0
- package/README-en.md +1 -1
- package/README.md +1 -1
- package/dist/cli/cli-helpers.d.ts +20 -0
- package/dist/cli/cli-helpers.js +34 -0
- package/dist/cli/commands/_register.js +2 -0
- package/dist/cli/commands/code-commands.d.ts +6 -4
- package/dist/cli/commands/code-commands.js +6 -4
- package/dist/cli/commands/code-gate-command.d.ts +5 -5
- package/dist/cli/commands/code-gate-command.js +49 -9
- package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
- package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
- package/dist/cli/commands/core/memory-extract-command.js +10 -5
- package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
- package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
- package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
- package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
- package/dist/cli/commands/dispatch-commands.js +12 -5
- package/dist/cli/commands/dispatch-preflight.js +46 -0
- package/dist/cli/commands/dispatch-prompt-composition.d.ts +6 -0
- package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
- package/dist/cli/commands/doc-commands.js +1 -1
- package/dist/cli/commands/feedback-commands-helpers.js +1 -1
- package/dist/cli/commands/final-review-prepare-command.js +22 -1
- package/dist/cli/commands/gate-commands-enforce.js +3 -3
- package/dist/cli/commands/hook-handle.js +41 -20
- package/dist/cli/commands/lint-commands.js +3 -1
- package/dist/cli/commands/loop-eval-capture-index.js +2 -4
- package/dist/cli/commands/perf-audit-commands.js +15 -5
- package/dist/cli/commands/project-commands.js +9 -6
- package/dist/cli/commands/race-commands.d.ts +15 -0
- package/dist/cli/commands/race-commands.js +65 -0
- package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
- package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
- package/dist/cli/commands/request-command-options.d.ts +8 -0
- package/dist/cli/commands/request-commands.js +2 -0
- package/dist/cli/commands/request-init-command.js +67 -12
- package/dist/cli/commands/request-retag-command.d.ts +3 -0
- package/dist/cli/commands/request-retag-command.js +50 -0
- package/dist/cli/commands/request-show-command.d.ts +8 -0
- package/dist/cli/commands/request-show-command.js +14 -1
- package/dist/cli/commands/request-transition-command.js +12 -4
- package/dist/cli/commands/request-transition-failures.d.ts +14 -0
- package/dist/cli/commands/request-transition-failures.js +45 -3
- package/dist/cli/commands/scan-scope-commands.js +2 -2
- package/dist/cli/commands/security-audit-commands.js +26 -6
- package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
- package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
- package/dist/services/artifacts/artifact-contract-block.js +212 -0
- package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
- package/dist/services/artifacts/artifact-prerequisites.js +63 -133
- package/dist/services/artifacts/artifact-templates.d.ts +1 -1
- package/dist/services/artifacts/artifact-templates.js +17 -10
- package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
- package/dist/services/artifacts/prerequisite-checks.js +198 -0
- package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
- package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
- package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
- package/dist/services/artifacts/request-artifact-metadata.js +44 -0
- package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
- package/dist/services/artifacts/request-artifact-service.js +23 -51
- package/dist/services/artifacts/request-artifact-state-helpers.d.ts +12 -0
- package/dist/services/artifacts/request-artifact-state-helpers.js +28 -4
- package/dist/services/artifacts/request-retag-service.d.ts +68 -0
- package/dist/services/artifacts/request-retag-service.js +125 -0
- package/dist/services/artifacts/request-state-order.d.ts +38 -0
- package/dist/services/artifacts/request-state-order.js +99 -0
- package/dist/services/artifacts/request-type-demand.d.ts +44 -0
- package/dist/services/artifacts/request-type-demand.js +71 -0
- package/dist/services/audit/audit-goal-service.d.ts +7 -0
- package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
- package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
- package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
- package/dist/services/audit/enforcers/code-ban.js +21 -1
- package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
- package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
- package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
- package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
- package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
- package/dist/services/audit-independent/handoff-readers.js +81 -0
- package/dist/services/audit-independent/index.d.ts +6 -1
- package/dist/services/audit-independent/index.js +6 -1
- package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
- package/dist/services/audit-independent/judged-declaration-build.js +73 -0
- package/dist/services/audit-independent/judged-declaration-check.d.ts +79 -0
- package/dist/services/audit-independent/judged-declaration-check.js +155 -0
- package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
- package/dist/services/audit-independent/judged-declaration.js +218 -0
- package/dist/services/audit-independent/perf-audit-service.js +12 -14
- package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
- package/dist/services/audit-independent/security-audit-artifact.js +90 -0
- package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
- package/dist/services/audit-independent/security-audit-service.js +34 -178
- package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
- package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
- package/dist/services/context/build-dispatch-system-prompt.d.ts +3 -3
- package/dist/services/context/build-dispatch-system-prompt.js +7 -7
- package/dist/services/context/collector.js +5 -1
- package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
- package/dist/services/dispatch/active-dispatch-index.js +118 -0
- package/dist/services/dispatch/batch-counter.js +1 -2
- package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
- package/dist/services/dispatch/dispatch-record-writer.js +58 -100
- package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
- package/dist/services/dispatch/karpathy-block.d.ts +55 -0
- package/dist/services/dispatch/karpathy-block.js +101 -0
- package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
- package/dist/services/dispatch/ledger-reaper.js +131 -0
- package/dist/services/evidence/evidence-generator.js +15 -8
- package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
- package/dist/services/feedback/feedback-promotion-service.js +30 -35
- package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
- package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
- package/dist/services/feedback/promotion-artifact-missing.js +63 -0
- package/dist/services/final-review/final-review-contract.d.ts +95 -4
- package/dist/services/final-review/final-review-contract.js +64 -0
- package/dist/services/final-review/final-review-delivery.d.ts +13 -0
- package/dist/services/final-review/final-review-delivery.js +26 -12
- package/dist/services/final-review/final-review-evidence-collect.js +8 -53
- package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
- package/dist/services/final-review/final-review-evidence-records.js +67 -0
- package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
- package/dist/services/final-review/final-review-evidence-sources.js +28 -4
- package/dist/services/final-review/final-review-prompt.js +19 -6
- package/dist/services/final-review/final-review-runner.js +5 -0
- package/dist/services/final-review/final-review-service.d.ts +2 -2
- package/dist/services/final-review/index.d.ts +1 -1
- package/dist/services/final-review/pre-post-diff.d.ts +2 -75
- package/dist/services/final-review/pre-post-diff.js +60 -59
- package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
- package/dist/services/hooks/pre-tool-code-gate.js +21 -2
- package/dist/services/hooks/worktree-authorization-gate.js +6 -31
- package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
- package/dist/services/hooks/worktree-refusal-messages.js +102 -0
- package/dist/services/lint/eslint-runner-support.d.ts +1 -1
- package/dist/services/lint/eslint-runner-support.js +2 -1
- package/dist/services/lint/eslint-runner-types.d.ts +8 -0
- package/dist/services/lint/eslint-runner.js +17 -4
- package/dist/services/llm/anthropic-runner.js +24 -7
- package/dist/services/loop/loop-observability.d.ts +39 -0
- package/dist/services/loop/loop-observability.js +55 -0
- package/dist/services/loop/monotonic-guard.js +6 -9
- package/dist/services/loop/monotonic-runner.js +8 -7
- package/dist/services/loop/run-driver.js +18 -22
- package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
- package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
- package/dist/services/memory/project-memory-service/index.d.ts +2 -2
- package/dist/services/memory/project-memory-service/index.js +1 -1
- package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
- package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
- package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
- package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
- package/dist/services/memory/project-memory-service/types.d.ts +32 -0
- package/dist/services/observability/observability-service.d.ts +7 -0
- package/dist/services/observability/observability-service.js +2 -1
- package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
- package/dist/services/prd/gate-evidence-derivation.js +4 -3
- package/dist/services/qa/bdd-test-style-verifier.js +22 -8
- package/dist/services/race/gate2-evaluator.d.ts +58 -0
- package/dist/services/race/gate2-evaluator.js +111 -0
- package/dist/services/race/gate2-policy.d.ts +17 -0
- package/dist/services/race/gate2-policy.js +31 -0
- package/dist/services/race/lane-phase.d.ts +19 -0
- package/dist/services/race/lane-phase.js +113 -0
- package/dist/services/race/pilot-gate-store.d.ts +67 -0
- package/dist/services/race/pilot-gate-store.js +227 -0
- package/dist/services/scan/file-size-baseline.d.ts +26 -0
- package/dist/services/scan/file-size-baseline.js +150 -0
- package/dist/services/scan/file-size-scan.d.ts +42 -3
- package/dist/services/scan/file-size-scan.js +58 -42
- package/dist/services/scan/type-sanity-service.js +13 -3
- package/dist/services/skill/resume-detector.js +3 -3
- package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
- package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
- package/dist/services/skills/hooks-settings-service.d.ts +1 -1
- package/dist/services/skills/hooks-settings-service.js +1 -1
- package/dist/services/skills/presence-lease-order.d.ts +13 -0
- package/dist/services/skills/presence-lease-order.js +24 -0
- package/dist/services/skills/skill-conformance-service.js +1 -0
- package/dist/services/skills/skill-statusline-service.js +4 -7
- package/dist/services/slice/slice-check-service.js +8 -8
- package/dist/services/workflow/pipeline-verify-gate-support.js +2 -1
- package/dist/services/workflow/pipeline-verify-service.js +1 -1
- package/dist/services/workflow/workflow-skip-service.d.ts +0 -20
- package/dist/services/workflow/workflow-skip-service.js +3 -4
- package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
- package/dist/services/workspace/claude-settings-retirements.js +112 -0
- package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
- package/dist/services/workspace/claude-settings-template-merge.js +33 -53
- package/dist/services/workspace/claude-settings-template.d.ts +62 -12
- package/dist/services/workspace/claude-settings-template.js +58 -58
- package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
- package/dist/services/workspace/reconcile-service.js +0 -1
- package/dist/shared/incrementing-number.d.ts +10 -0
- package/dist/shared/incrementing-number.js +27 -0
- package/package.json +5 -5
- package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
- package/skills/bee/peaks-prd/SKILL.md +1 -1
- package/skills/bee/peaks-qa/SKILL.md +1 -1
- package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
- package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
- package/skills/bee/peaks-rd/SKILL.md +2 -2
- package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
- package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
- package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
- package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
- package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +1 -1
- package/skills/bee/peaks-sc/SKILL.md +1 -1
- package/skills/bee/peaks-security-audit/SKILL.md +10 -2
- package/skills/bee/peaks-txt/SKILL.md +4 -3
- package/skills/bee/peaks-ui/SKILL.md +3 -3
- package/skills/peaks-audit/SKILL.md +29 -1
- package/skills/peaks-code/SKILL.md +5 -2
- package/skills/peaks-code/references/fast-lane-norm.md +42 -0
- package/skills/peaks-code/references/fast-mode.md +3 -2
- package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
- package/skills/peaks-code/references/micro-cycle.md +3 -3
- package/skills/peaks-code/references/resume-detection.md +1 -1
- package/skills/peaks-code/references/runbook.md +12 -6
- package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
- package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
- package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
- package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
- package/skills/peaks-code/references/worktree-governance.md +4 -4
- package/skills/peaks-content/SKILL.md +1 -1
- package/skills/peaks-doctor/SKILL.md +1 -1
- package/skills/peaks-final-review/SKILL.md +31 -11
- package/skills/peaks-ide/SKILL.md +1 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
- package/skills/peaks-race-code/SKILL.md +185 -0
- package/skills/peaks-resume/SKILL.md +1 -1
- package/skills/peaks-slice-decompose/SKILL.md +1 -1
- package/skills/peaks-solo/SKILL.md +1 -1
- package/skills/peaks-sop/SKILL.md +1 -1
- package/skills/peaks-status/SKILL.md +1 -1
- package/skills/peaks-test/SKILL.md +7 -4
- package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
- package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
|
@@ -21,6 +21,19 @@ function buildShowPayload(result, options) {
|
|
|
21
21
|
const transformed = applyPerArtifactFormat(result, override ?? format);
|
|
22
22
|
return transformed === result ? { ...result, format } : transformed;
|
|
23
23
|
}
|
|
24
|
+
/**
|
|
25
|
+
* The type a `request show` reports is the EFFECTIVE one: an artifact that
|
|
26
|
+
* records no type still reads as `feature`, and a reader who cannot tell that
|
|
27
|
+
* from a chosen `feature` cannot tell which prerequisite table the next gate
|
|
28
|
+
* will apply. The field says which; this line says it in words.
|
|
29
|
+
*/
|
|
30
|
+
export function typeProvenanceWarning(result) {
|
|
31
|
+
if (result.requestTypeSource !== 'default')
|
|
32
|
+
return [];
|
|
33
|
+
return [
|
|
34
|
+
`request type '${result.requestType}' is the DEFAULT — this artifact records no type, so the '${result.requestType}' prerequisite table applies. Set one with: peaks request retag <request-id> --role ${result.role} --type <type> --project <path>`
|
|
35
|
+
];
|
|
36
|
+
}
|
|
24
37
|
async function runRequestShow(requestId, options, io) {
|
|
25
38
|
try {
|
|
26
39
|
const showOptions = {
|
|
@@ -36,7 +49,7 @@ async function runRequestShow(requestId, options, io) {
|
|
|
36
49
|
failShowNotFound(io, options, requestId);
|
|
37
50
|
return;
|
|
38
51
|
}
|
|
39
|
-
printResult(io, ok('request.show', buildShowPayload(result, options)), options.json);
|
|
52
|
+
printResult(io, ok('request.show', buildShowPayload(result, options), typeProvenanceWarning(result)), options.json);
|
|
40
53
|
}
|
|
41
54
|
catch (error) {
|
|
42
55
|
printResult(io, fail('request.show', 'REQUEST_SHOW_FAILED', getErrorMessage(error), { role: options.role, requestId }, ['Check role, request id, and project path before retrying']), options.json);
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { transitionRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
|
|
2
2
|
import { parseRole, parseStateForRole, VALID_ROLES } from './request-format-helpers.js';
|
|
3
3
|
import { fail, ok } from 'peaks-loop-shared/result';
|
|
4
|
-
import { addJsonOption, printResult } from '../cli-helpers.js';
|
|
4
|
+
import { addJsonOption, printableWarningText, printResult } from '../cli-helpers.js';
|
|
5
5
|
import { runTransitionPreflight } from './request-transition-preflight.js';
|
|
6
|
-
import { reportTransitionFailure } from './request-transition-failures.js';
|
|
6
|
+
import { reportTransitionFailure, softWarningExpiryClause } from './request-transition-failures.js';
|
|
7
7
|
import { buildPrdHandoffResult, collectQaHandoffHooks, preCompactNote } from './request-transition-hooks.js';
|
|
8
8
|
const TRANSITION_DESCRIPTION = 'Move a per-request artifact to a new state defined by its role state machine';
|
|
9
9
|
const TRANSITION_REQUEST_ID_HELP = 'request id, e.g. 2026-05-23-add-foo';
|
|
@@ -11,7 +11,7 @@ const TRANSITION_STATE_HELP = 'new state name; allowed values depend on role';
|
|
|
11
11
|
const TRANSITION_PROJECT_HELP = 'target project root';
|
|
12
12
|
const TRANSITION_SESSION_HELP = 'restrict to a specific session id';
|
|
13
13
|
const TRANSITION_REASON_HELP = 'reason appended as a transition note; required when --allow-incomplete is set';
|
|
14
|
-
const TRANSITION_ALLOW_INCOMPLETE_HELP = 'bypass
|
|
14
|
+
const TRANSITION_ALLOW_INCOMPLETE_HELP = 'bypass the prerequisite, lint, file-size and state-order checks; requires --reason and records the bypass in the artifact';
|
|
15
15
|
const TRANSITION_CONFIRM_HELP = 'skip the confirmation gate (for non-interactive / LLM contexts)';
|
|
16
16
|
const TRANSITION_FORCE_CONFIRM_HELP = 'bypass mode-enforced confirmation (use with caution)';
|
|
17
17
|
function buildTransitionOptions(requestId, role, newState, options) {
|
|
@@ -71,7 +71,15 @@ function printTransitionResult(io, options, result, hooks) {
|
|
|
71
71
|
codegraphRefresh: hooks.codegraphRefresh
|
|
72
72
|
}, [
|
|
73
73
|
...(note === null ? [] : [note]),
|
|
74
|
-
...(hooks.codegraphWarning === null ? [] : [hooks.codegraphWarning])
|
|
74
|
+
...(hooks.codegraphWarning === null ? [] : [hooks.codegraphWarning]),
|
|
75
|
+
// A soft-passed prerequisite is a warning, not a silent pass: the
|
|
76
|
+
// envelope carries it (and `printResult` puts it on stderr for a human
|
|
77
|
+
// run). `data.prerequisiteWarnings` holds the structured entries.
|
|
78
|
+
// `softWarningExpiryClause` adds the one thing the entry cannot say
|
|
79
|
+
// without `message` moving: whether the window it names has closed.
|
|
80
|
+
...(result.prerequisiteWarnings ?? []).map((warning) => `Soft prerequisite (not enforced): ${printableWarningText(warning.path)} ` +
|
|
81
|
+
`[${printableWarningText(warning.code)}] — ${printableWarningText(warning.message)}` +
|
|
82
|
+
softWarningExpiryClause(warning))
|
|
75
83
|
]), options.json);
|
|
76
84
|
}
|
|
77
85
|
async function runRequestTransition(requestId, options, io) {
|
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
import { type ProgramIO } from '../cli-helpers.js';
|
|
2
2
|
import type { RequestTransitionOptions } from './request-command-options.js';
|
|
3
|
+
/**
|
|
4
|
+
* The clause a soft-pass warning gains once its back-compat window has closed.
|
|
5
|
+
* It renders the `expiredWindow` the resolver set (the release the table
|
|
6
|
+
* declared, plus the build it was compared against) and is empty while the
|
|
7
|
+
* window is open — an open window is already the future tense the warning's own
|
|
8
|
+
* message uses, so it needs no clause.
|
|
9
|
+
*
|
|
10
|
+
* Shared with `printTransitionResult` in `request-transition-command.ts`: the
|
|
11
|
+
* success arm and this refusal arm render one fact one way, so an operator who
|
|
12
|
+
* sees the same soft pass through either arm reads the same sentence.
|
|
13
|
+
*/
|
|
14
|
+
export declare function softWarningExpiryClause(warning: {
|
|
15
|
+
expiredWindow?: string;
|
|
16
|
+
}): string;
|
|
3
17
|
/**
|
|
4
18
|
* Map a thrown transition error to its envelope. `InvalidArgumentError` is
|
|
5
19
|
* re-thrown: Commander raises it for an unparsable `--state`, and swallowing it
|
|
@@ -4,9 +4,26 @@
|
|
|
4
4
|
// readable and every branch keeps setting `process.exitCode = 1`.
|
|
5
5
|
import { InvalidArgumentError } from 'commander';
|
|
6
6
|
import { PrerequisitesNotSatisfiedError, LintGateError, TypeSanityViolationError, FileSizeViolationError } from '../../services/artifacts/request-artifact-service.js';
|
|
7
|
+
import { StateOrderViolationError } from '../../services/artifacts/request-state-order.js';
|
|
7
8
|
import { ConfirmationRequiredError } from '../../services/mode/mode-enforcement.js';
|
|
8
9
|
import { fail } from 'peaks-loop-shared/result';
|
|
9
|
-
import { getErrorMessage, printResult } from '../cli-helpers.js';
|
|
10
|
+
import { getErrorMessage, printableWarningText, printResult } from '../cli-helpers.js';
|
|
11
|
+
/**
|
|
12
|
+
* The clause a soft-pass warning gains once its back-compat window has closed.
|
|
13
|
+
* It renders the `expiredWindow` the resolver set (the release the table
|
|
14
|
+
* declared, plus the build it was compared against) and is empty while the
|
|
15
|
+
* window is open — an open window is already the future tense the warning's own
|
|
16
|
+
* message uses, so it needs no clause.
|
|
17
|
+
*
|
|
18
|
+
* Shared with `printTransitionResult` in `request-transition-command.ts`: the
|
|
19
|
+
* success arm and this refusal arm render one fact one way, so an operator who
|
|
20
|
+
* sees the same soft pass through either arm reads the same sentence.
|
|
21
|
+
*/
|
|
22
|
+
export function softWarningExpiryClause(warning) {
|
|
23
|
+
return warning.expiredWindow === undefined
|
|
24
|
+
? ''
|
|
25
|
+
: ` — past expiry: ${printableWarningText(warning.expiredWindow)}`;
|
|
26
|
+
}
|
|
10
27
|
function reportPrerequisitesFailure(io, options, error) {
|
|
11
28
|
// The `warnings` list is surfaced inside the 1-minor-release back-compat
|
|
12
29
|
// window (e.g. MUT_REPORT) so the operator sees both the hard-blocked
|
|
@@ -20,7 +37,11 @@ function reportPrerequisitesFailure(io, options, error) {
|
|
|
20
37
|
warnings: error.warnings
|
|
21
38
|
}, [
|
|
22
39
|
...error.missing.map((entry) => `Produce ${entry.path}: ${entry.description}`),
|
|
23
|
-
|
|
40
|
+
// Sanitised for the same reason the success branch sanitises: a
|
|
41
|
+
// `gateEvidence.<key>` warning can carry a control character decoded out
|
|
42
|
+
// of the handoff frontmatter, and `printResult` puts these on stderr.
|
|
43
|
+
...error.warnings.map((w) => `Soft-blocked (v2.13.3 back-compat window): ${printableWarningText(w.path)} — ` +
|
|
44
|
+
`${printableWarningText(w.message)}${softWarningExpiryClause(w)}`),
|
|
24
45
|
'Once every required artifact exists, rerun this transition.',
|
|
25
46
|
'For exceptional cases (docs-only / config-only change), bypass with: --allow-incomplete --reason "<justification>"'
|
|
26
47
|
]), options.json);
|
|
@@ -34,6 +55,21 @@ function reportLintGateFailure(io, options, error) {
|
|
|
34
55
|
]), options.json);
|
|
35
56
|
process.exitCode = 1;
|
|
36
57
|
}
|
|
58
|
+
function reportStateOrderFailure(io, options, error) {
|
|
59
|
+
printResult(io, fail('request.transition', error.code, error.message, {
|
|
60
|
+
role: error.role,
|
|
61
|
+
from: error.from,
|
|
62
|
+
newState: error.to,
|
|
63
|
+
skipped: error.skipped
|
|
64
|
+
}, [
|
|
65
|
+
error.kind === 'unreadable'
|
|
66
|
+
? "Restore the artifact's '- state:' line: an unreadable state fails this gate closed"
|
|
67
|
+
: `Walk the states in order — from '${error.from}' the next legal state is ` +
|
|
68
|
+
`'${error.skipped[0] ?? error.to}'`,
|
|
69
|
+
'Or bypass with: --allow-incomplete --reason "<justification>"'
|
|
70
|
+
]), options.json);
|
|
71
|
+
process.exitCode = 1;
|
|
72
|
+
}
|
|
37
73
|
function reportTypeSanityFailure(io, options, error) {
|
|
38
74
|
printResult(io, fail('request.transition', error.code, error.message, {
|
|
39
75
|
declaredType: error.declaredType,
|
|
@@ -47,7 +83,9 @@ function reportTypeSanityFailure(io, options, error) {
|
|
|
47
83
|
}
|
|
48
84
|
function reportFileSizeFailure(io, options, error) {
|
|
49
85
|
printResult(io, fail('request.transition', error.code, error.message, { violations: error.violations }, [
|
|
50
|
-
...error.violations.map((v) =>
|
|
86
|
+
...error.violations.map((v) => v.previousLines === null
|
|
87
|
+
? `Split ${v.file} (${v.lines} lines) below its ${v.cap}-line cap — this change created it over the cap`
|
|
88
|
+
: `Split ${v.file} back below its ${v.cap}-line cap, or at least down to the ${v.previousLines} lines it had at the base ref (grew +${v.lines - v.previousLines})`),
|
|
51
89
|
'Or bypass with: --allow-incomplete --reason "<justification>"'
|
|
52
90
|
]), options.json);
|
|
53
91
|
process.exitCode = 1;
|
|
@@ -73,6 +111,10 @@ export function reportTransitionFailure(io, options, requestId, error) {
|
|
|
73
111
|
reportLintGateFailure(io, options, error);
|
|
74
112
|
return;
|
|
75
113
|
}
|
|
114
|
+
if (error instanceof StateOrderViolationError) {
|
|
115
|
+
reportStateOrderFailure(io, options, error);
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
76
118
|
if (error instanceof TypeSanityViolationError) {
|
|
77
119
|
reportTypeSanityFailure(io, options, error);
|
|
78
120
|
return;
|
|
@@ -16,7 +16,7 @@ import { acceptanceCoverageNextActions, diffVsScopeNextActions, printAcceptanceC
|
|
|
16
16
|
const REQUEST_TYPE_SANITY_DESCRIPTION = 'Cross-verify a declared --type against the actual git diff file mix (catches "feature mis-declared as docs" workflow violations)';
|
|
17
17
|
const ACCEPTANCE_COVERAGE_DESCRIPTION = 'Verify every PRD "Acceptance criteria" item has at least one linked QA test case (via `- **Acceptance:** A1, A2` field in qa/test-cases/<rid>.md)';
|
|
18
18
|
const DIFF_VS_SCOPE_DESCRIPTION = 'Verify every file in the git diff matches the RD artifact "Red-line scope" patterns; flags out-of-scope writes and unclassified files';
|
|
19
|
-
const FILE_SIZE_DESCRIPTION = 'Check git diff for files
|
|
19
|
+
const FILE_SIZE_DESCRIPTION = 'Check git diff for files this change grew past the line-count cap, or created over it (karpathy-skills "Simplicity First"; a file already over cap at the base ref is accepted, as the gate baseline ratchets it; a rename is measured against its pre-rename size; tool output, lockfiles and append-only records such as CHANGELOG.md excluded)';
|
|
20
20
|
function runScanRequestTypeSanity(options, io) {
|
|
21
21
|
try {
|
|
22
22
|
const serviceOptions = {
|
|
@@ -108,7 +108,7 @@ function runScanFileSize(options, io) {
|
|
|
108
108
|
});
|
|
109
109
|
const nextActions = [];
|
|
110
110
|
if (!result.ok) {
|
|
111
|
-
nextActions.push(`${result.violations.length} file(s) exceed their file-size cap. Split into smaller modules.`);
|
|
111
|
+
nextActions.push(`${result.violations.length} file(s) exceed their file-size cap because this change grew them past it (or created them over it). Split into smaller modules.`);
|
|
112
112
|
}
|
|
113
113
|
printResult(io, ok('scan.file-size', result, [], nextActions), options.json);
|
|
114
114
|
if (!result.ok) {
|
|
@@ -2,6 +2,14 @@ import { readFileSync } from 'node:fs';
|
|
|
2
2
|
import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit } from '../../services/audit-independent/index.js';
|
|
3
3
|
import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
|
|
4
4
|
import { fail, ok } from 'peaks-loop-shared/result';
|
|
5
|
+
/**
|
|
6
|
+
* The judged paths as the service takes them. A call, not a `??` inside the
|
|
7
|
+
* action, because the action's branch budget is already at its cap and a second
|
|
8
|
+
* operator there is a `complexity` finding on the whole command.
|
|
9
|
+
*/
|
|
10
|
+
function resolveJudgedPaths(judged) {
|
|
11
|
+
return judged ?? [];
|
|
12
|
+
}
|
|
5
13
|
function resolveEnvelope(envelopePath) {
|
|
6
14
|
if (envelopePath === undefined || envelopePath === '-') {
|
|
7
15
|
// Read from stdin
|
|
@@ -19,9 +27,7 @@ function readStdinSync() {
|
|
|
19
27
|
// Node 22: read stdin synchronously via fs.readFileSync(0, 'utf8').
|
|
20
28
|
// We use the file descriptor 0 convention.
|
|
21
29
|
try {
|
|
22
|
-
|
|
23
|
-
const { readFileSync: rfs } = require('node:fs');
|
|
24
|
-
const raw = rfs(0, 'utf8');
|
|
30
|
+
const raw = readFileSync(0, 'utf8');
|
|
25
31
|
if (raw.trim().length === 0) {
|
|
26
32
|
throw new Error('stdin was empty; expected JSON envelope on stdin or --envelope <path>');
|
|
27
33
|
}
|
|
@@ -63,7 +69,14 @@ export function registerSecurityAuditCommands(program, io) {
|
|
|
63
69
|
});
|
|
64
70
|
const envelope = detect.state === 'ready'
|
|
65
71
|
? ok('security-audit.detect', detect, [...detect.warnings], [...detect.nextActions])
|
|
66
|
-
:
|
|
72
|
+
: {
|
|
73
|
+
// `fail()` builds `warnings: []`, so the detector's own diagnosis is
|
|
74
|
+
// spread over it. Without this the human-readable refusal drops the
|
|
75
|
+
// sentence saying WHY the run is not ready, while `--json` keeps it
|
|
76
|
+
// at `data.detect.warnings` — the 9.2 shape, one surface over.
|
|
77
|
+
...fail('security-audit.detect', detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${detect.state}`, detect, [...detect.nextActions]),
|
|
78
|
+
warnings: [...detect.warnings]
|
|
79
|
+
};
|
|
67
80
|
printResult(io, envelope, options.json);
|
|
68
81
|
if (detect.state !== 'ready') {
|
|
69
82
|
process.exitCode = 1;
|
|
@@ -86,7 +99,8 @@ export function registerSecurityAuditCommands(program, io) {
|
|
|
86
99
|
.option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
|
|
87
100
|
.option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
|
|
88
101
|
.option('--project <path>', 'project root (default: cwd)')
|
|
89
|
-
.option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')
|
|
102
|
+
.option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')
|
|
103
|
+
.option('--judged <paths...>', 'project-relative paths this audit judged; written into the artifact as the declaration the rd:qa-handoff gate reads back. Not enforced by the parser: an empty or unhashable list is refused by the run itself, which exits 1 and writes nothing.')).action((options) => {
|
|
90
104
|
const projectRoot = options.project ?? process.cwd();
|
|
91
105
|
const sid = options.sid;
|
|
92
106
|
const rid = options.rid;
|
|
@@ -115,10 +129,16 @@ export function registerSecurityAuditCommands(program, io) {
|
|
|
115
129
|
sessionId: sid,
|
|
116
130
|
rid,
|
|
117
131
|
generatedAt: new Date().toISOString(),
|
|
132
|
+
judgedPaths: resolveJudgedPaths(options.judged),
|
|
118
133
|
envelope: envelopeValue
|
|
119
134
|
});
|
|
120
135
|
if (result.detect.state !== 'ready' || result.artifactPath === null) {
|
|
121
|
-
printResult(io,
|
|
136
|
+
printResult(io, {
|
|
137
|
+
// Same spread as the detect arm: the run's refusal is the only place
|
|
138
|
+
// the detector's warning would reach a person, and `fail()` empties it.
|
|
139
|
+
...fail('security-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]),
|
|
140
|
+
warnings: [...result.detect.warnings]
|
|
141
|
+
}, options.json);
|
|
122
142
|
process.exitCode = 1;
|
|
123
143
|
return;
|
|
124
144
|
}
|
|
@@ -66,7 +66,7 @@ function printGcOk(io, options, ctx) {
|
|
|
66
66
|
dryRun
|
|
67
67
|
? `[dry-run] Would gc ${swept.length} lease(s); no filesystem changes were made.`
|
|
68
68
|
: `Gc'd ${swept.length} lease(s).`,
|
|
69
|
-
'For per-lease detail, run `peaks worktree status --lease-id <id>`.'
|
|
69
|
+
'For per-lease detail, run `peaks worktree lease-status --lease-id <id>`.'
|
|
70
70
|
]), options.json);
|
|
71
71
|
}
|
|
72
72
|
function printGcFailed(io, options, err, sessionId) {
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import { type RequestType } from './artifact-prerequisites.js';
|
|
2
|
+
import { type RequestTypeSource } from './request-artifact-metadata.js';
|
|
3
|
+
/**
|
|
4
|
+
* The block, or `''` when this role has nothing gated to say under this type.
|
|
5
|
+
* The empty string is the whole byte-identity contract: callers concatenate it,
|
|
6
|
+
* and a role with no gated artifacts must add zero bytes to the prompt.
|
|
7
|
+
*/
|
|
8
|
+
export declare function buildArtifactContractBlock(input: {
|
|
9
|
+
role: string;
|
|
10
|
+
requestType: RequestType;
|
|
11
|
+
requestTypeSource: RequestTypeSource;
|
|
12
|
+
requestId: string;
|
|
13
|
+
}): string;
|
|
14
|
+
/**
|
|
15
|
+
* Append the block unless the text already carries one.
|
|
16
|
+
*
|
|
17
|
+
* Idempotent for the same reason `ensureKarpathyBlock` is: a caller prompt can
|
|
18
|
+
* already hold a copy — a re-dispatch, or a resume from a stored prompt — and
|
|
19
|
+
* two sections can DISAGREE (the type may have been declared between the two
|
|
20
|
+
* runs), so a reader cannot tell which contract is authoritative. The presence
|
|
21
|
+
* test is the block's own heading, which nothing else emits.
|
|
22
|
+
*
|
|
23
|
+
* An empty block adds zero bytes even when the text already carries one, so an
|
|
24
|
+
* unaffected dispatch stays byte-identical.
|
|
25
|
+
*/
|
|
26
|
+
export declare function ensureArtifactContractBlock(text: string, block: string): string;
|
|
27
|
+
export type ArtifactTypeReading = {
|
|
28
|
+
requestType: RequestType;
|
|
29
|
+
requestTypeSource: RequestTypeSource;
|
|
30
|
+
};
|
|
31
|
+
/**
|
|
32
|
+
* The type recorded for `requestId`, read through the same reader the rest of
|
|
33
|
+
* the CLI uses. Every request artifact of the id is a candidate because the
|
|
34
|
+
* dispatched role's own file frequently does not exist yet at dispatch time —
|
|
35
|
+
* a dated snapshot over the dispatch records of the 2026-10-12 session (77 of
|
|
36
|
+
* them at the time of writing, a count the session is still growing): 18 had any
|
|
37
|
+
* request artifact for the id on disk before the dispatch and 10 had one that
|
|
38
|
+
* declared a type — while a sibling role may have recorded the type already. A
|
|
39
|
+
* `default` result is a real answer — nothing declared it.
|
|
40
|
+
*/
|
|
41
|
+
export declare function readArtifactType(input: {
|
|
42
|
+
projectRoot: string;
|
|
43
|
+
sessionId: string;
|
|
44
|
+
requestId: string;
|
|
45
|
+
role: string;
|
|
46
|
+
}): Promise<ArtifactTypeReading>;
|
|
47
|
+
/** The composed block for a dispatch, reading the type from disk first. */
|
|
48
|
+
export declare function readArtifactContractBlock(input: {
|
|
49
|
+
projectRoot: string;
|
|
50
|
+
sessionId: string;
|
|
51
|
+
requestId: string;
|
|
52
|
+
role: string;
|
|
53
|
+
}): Promise<string>;
|
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
// The artifact contract block a dispatched sub-agent receives: for its own role
|
|
2
|
+
// and the request's type, every artifact the prerequisite gate will demand and
|
|
3
|
+
// the literal body markers each one must carry.
|
|
4
|
+
//
|
|
5
|
+
// Generated from the table the gate reads (`getPrerequisitesFor`), never from a
|
|
6
|
+
// second hand-written list: the markers are matched as case-insensitive
|
|
7
|
+
// substrings of the artifact body, so a list kept in prose drifts the moment a
|
|
8
|
+
// marker changes and the gate then refuses a producer it never told.
|
|
9
|
+
import { DEFAULT_REQUEST_TYPE, getPrerequisitesFor } from './artifact-prerequisites.js';
|
|
10
|
+
import { ALLOWED_STATES_PER_ROLE } from './request-artifact-state-helpers.js';
|
|
11
|
+
import { extractMetadata } from './request-artifact-metadata.js';
|
|
12
|
+
import { REQUEST_ID_PATTERN, showRequestArtifact } from './request-artifact-service.js';
|
|
13
|
+
import { isUnsafePathInput } from '../../shared/path-safety.js';
|
|
14
|
+
/** Roles whose request artifact may carry a `- type:` line, in search order. */
|
|
15
|
+
const TYPE_SOURCE_ROLES = ['rd', 'prd', 'qa', 'ui', 'sc'];
|
|
16
|
+
/** True for the five roles the state table is keyed on. */
|
|
17
|
+
function isRequestArtifactRole(role) {
|
|
18
|
+
return Object.prototype.hasOwnProperty.call(ALLOWED_STATES_PER_ROLE, role);
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The prerequisite's path with the request id substituted for its `<rid>`.
|
|
22
|
+
*
|
|
23
|
+
* Deliberately NOT exported. A test that called this would no longer be
|
|
24
|
+
* independent of the renderer it checks, and that independence is the whole
|
|
25
|
+
* value of the pinning case.
|
|
26
|
+
*/
|
|
27
|
+
function resolveContractPath(prerequisite, requestId) {
|
|
28
|
+
return prerequisite.relativePath.replace('<rid>', requestId);
|
|
29
|
+
}
|
|
30
|
+
function quoteAll(markers) {
|
|
31
|
+
return markers.map((marker) => `\`${marker}\``).join(', ');
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* The marker fields, in the order the block renders them. A table rather than a
|
|
35
|
+
* chain of `if`s: the three fields are independent and uniform, so listing them
|
|
36
|
+
* keeps the renderer's complexity flat as the vocabulary grows.
|
|
37
|
+
*/
|
|
38
|
+
const MARKER_CLAUSES = [
|
|
39
|
+
{ markers: (candidate) => candidate.mustContain, label: 'must contain' },
|
|
40
|
+
{ markers: (candidate) => candidate.mustContainAny, label: 'must contain at least one of' },
|
|
41
|
+
{
|
|
42
|
+
markers: (candidate) => candidate.headingMustContain,
|
|
43
|
+
label: 'must appear as markdown headings'
|
|
44
|
+
}
|
|
45
|
+
];
|
|
46
|
+
/**
|
|
47
|
+
* One line's worth of "what this file must carry", or the explicit statement
|
|
48
|
+
* that there is nothing to carry. `mustContainAny` is rendered as an
|
|
49
|
+
* alternative set rather than as three requirements — the gate passes on one.
|
|
50
|
+
*/
|
|
51
|
+
function describePrerequisite(prerequisite) {
|
|
52
|
+
const clauses = MARKER_CLAUSES.flatMap(({ markers, label }) => {
|
|
53
|
+
const list = markers(prerequisite) ?? [];
|
|
54
|
+
return list.length === 0 ? [] : [`${label}: ${quoteAll(list)}`];
|
|
55
|
+
});
|
|
56
|
+
if (prerequisite.backCompat === true) {
|
|
57
|
+
const until = prerequisite.backCompatUntil ?? 'the window closes';
|
|
58
|
+
clauses.push(`a missing file only warns until ${until}`);
|
|
59
|
+
}
|
|
60
|
+
return clauses.length === 0 ? 'the file must exist; it has no body markers' : clauses.join('; ');
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* The command that reaches a state, spelled with every option
|
|
64
|
+
* `src/cli/commands/request-transition-command.ts` registers as MANDATORY.
|
|
65
|
+
* `--project` is one of them, and an earlier revision of this line omitted it —
|
|
66
|
+
* the prompt therefore handed the producer a command the CLI refuses for a
|
|
67
|
+
* missing option, which is this block's own defect class turned on itself. The
|
|
68
|
+
* pinning test now compares the emitted options against the command's own
|
|
69
|
+
* `mandatory` set, so a newly required flag fails the suite rather than reaching
|
|
70
|
+
* a prompt. `.` because a dispatched sub-agent's working directory is the
|
|
71
|
+
* project root.
|
|
72
|
+
*/
|
|
73
|
+
function transitionCommand(role, state, requestId) {
|
|
74
|
+
return `peaks request transition ${requestId} --role ${role} --state ${state} --project .`;
|
|
75
|
+
}
|
|
76
|
+
function renderStateRow(role, state, prerequisites, requestId) {
|
|
77
|
+
const lines = prerequisites.map((entry) => `- \`${resolveContractPath(entry, requestId)}\` — ${describePrerequisite(entry)}`);
|
|
78
|
+
const reached = transitionCommand(role, state, requestId);
|
|
79
|
+
return {
|
|
80
|
+
state,
|
|
81
|
+
text: `\nAt \`${role}:${state}\` (reached with \`${reached}\`):\n${lines.join('\n')}\n`
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* One row per state of `role` that demands at least one artifact under
|
|
86
|
+
* `requestType`. A state with an empty row (`rd:implemented` for a feature, for
|
|
87
|
+
* instance) is left out rather than rendered as "nothing required" — the block
|
|
88
|
+
* is a list of obligations, and a state with none is not an obligation.
|
|
89
|
+
*/
|
|
90
|
+
function stateRows(role, requestType, requestId) {
|
|
91
|
+
if (!isRequestArtifactRole(role))
|
|
92
|
+
return [];
|
|
93
|
+
const rows = [];
|
|
94
|
+
for (const state of ALLOWED_STATES_PER_ROLE[role]) {
|
|
95
|
+
const prerequisites = getPrerequisitesFor(role, state, requestType);
|
|
96
|
+
if (prerequisites.length === 0)
|
|
97
|
+
continue;
|
|
98
|
+
rows.push(renderStateRow(role, state, prerequisites, requestId));
|
|
99
|
+
}
|
|
100
|
+
return rows;
|
|
101
|
+
}
|
|
102
|
+
const BODY_RULE = 'The gate matches each marker below as a case-insensitive substring of the artifact body, and a ' +
|
|
103
|
+
'heading marker must be a real markdown heading. Content under a different spelling is refused, ' +
|
|
104
|
+
'so write the marker literally. Paths are relative to `.peaks/_runtime/<session-id>/`.';
|
|
105
|
+
/**
|
|
106
|
+
* The scope bound, always true of the block regardless of what the gate does:
|
|
107
|
+
* it says what the rows ARE (necessary) and not what they are not (sufficient).
|
|
108
|
+
*/
|
|
109
|
+
const SCOPE_BASE = 'This block is generated from the prerequisite table alone, so the rows below are necessary and are ' +
|
|
110
|
+
'not a complete contract.';
|
|
111
|
+
/**
|
|
112
|
+
* The addendum for a state the gate really does guard with more than the table.
|
|
113
|
+
* Measured on a probe project and again on this slice's own rid: an artifact set
|
|
114
|
+
* satisfying every `rd:qa-handoff` row was still refused once, on a declaration
|
|
115
|
+
* outside the table. The earlier wording said a gate "may also check something
|
|
116
|
+
* the table does not carry", which under-claims a systematic gap at exactly the
|
|
117
|
+
* state this block guides a producer to.
|
|
118
|
+
*/
|
|
119
|
+
const SCOPE_HANDOFF = ' At `rd:qa-handoff` the gate also runs checks that are not rows of this table, so satisfying every ' +
|
|
120
|
+
'row below does not by itself open that transition.';
|
|
121
|
+
const ARTIFACT_CONTRACT_HEADING = '## Artifact contract (generated from the prerequisite table)';
|
|
122
|
+
/**
|
|
123
|
+
* The block, or `''` when this role has nothing gated to say under this type.
|
|
124
|
+
* The empty string is the whole byte-identity contract: callers concatenate it,
|
|
125
|
+
* and a role with no gated artifacts must add zero bytes to the prompt.
|
|
126
|
+
*/
|
|
127
|
+
export function buildArtifactContractBlock(input) {
|
|
128
|
+
const rows = stateRows(input.role, input.requestType, input.requestId);
|
|
129
|
+
if (rows.length === 0)
|
|
130
|
+
return '';
|
|
131
|
+
const typeLine = input.requestTypeSource === 'declared'
|
|
132
|
+
? `request type \`${input.requestType}\` (recorded by a \`- type:\` line)`
|
|
133
|
+
: `request type \`${input.requestType}\` — the DEFAULT, not a recorded choice: this request ` +
|
|
134
|
+
'records no `- type:` line, so the gate applies the default table. If the work is really a ' +
|
|
135
|
+
'different type, the demand set below is the wrong one';
|
|
136
|
+
// Conditional on the ROWS, not on a hand-written type list: whichever types
|
|
137
|
+
// render an `rd:qa-handoff` row are exactly the ones the extra checks run for.
|
|
138
|
+
const guardedHandoff = input.role === 'rd' && rows.some((row) => row.state === 'qa-handoff');
|
|
139
|
+
return (`\n${ARTIFACT_CONTRACT_HEADING}\n` +
|
|
140
|
+
`Role \`${input.role}\`, ${typeLine}.\n` +
|
|
141
|
+
`${BODY_RULE}\n` +
|
|
142
|
+
`${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}\n` +
|
|
143
|
+
rows.map((row) => row.text).join('') +
|
|
144
|
+
'\n');
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Append the block unless the text already carries one.
|
|
148
|
+
*
|
|
149
|
+
* Idempotent for the same reason `ensureKarpathyBlock` is: a caller prompt can
|
|
150
|
+
* already hold a copy — a re-dispatch, or a resume from a stored prompt — and
|
|
151
|
+
* two sections can DISAGREE (the type may have been declared between the two
|
|
152
|
+
* runs), so a reader cannot tell which contract is authoritative. The presence
|
|
153
|
+
* test is the block's own heading, which nothing else emits.
|
|
154
|
+
*
|
|
155
|
+
* An empty block adds zero bytes even when the text already carries one, so an
|
|
156
|
+
* unaffected dispatch stays byte-identical.
|
|
157
|
+
*/
|
|
158
|
+
export function ensureArtifactContractBlock(text, block) {
|
|
159
|
+
if (block.length === 0 || text.includes(ARTIFACT_CONTRACT_HEADING))
|
|
160
|
+
return text;
|
|
161
|
+
return `${text}${block}`;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* The type recorded for `requestId`, read through the same reader the rest of
|
|
165
|
+
* the CLI uses. Every request artifact of the id is a candidate because the
|
|
166
|
+
* dispatched role's own file frequently does not exist yet at dispatch time —
|
|
167
|
+
* a dated snapshot over the dispatch records of the 2026-10-12 session (77 of
|
|
168
|
+
* them at the time of writing, a count the session is still growing): 18 had any
|
|
169
|
+
* request artifact for the id on disk before the dispatch and 10 had one that
|
|
170
|
+
* declared a type — while a sibling role may have recorded the type already. A
|
|
171
|
+
* `default` result is a real answer — nothing declared it.
|
|
172
|
+
*/
|
|
173
|
+
export async function readArtifactType(input) {
|
|
174
|
+
const fallback = {
|
|
175
|
+
requestType: DEFAULT_REQUEST_TYPE,
|
|
176
|
+
requestTypeSource: 'default'
|
|
177
|
+
};
|
|
178
|
+
if (isUnsafePathInput(input.sessionId) || !REQUEST_ID_PATTERN.test(input.requestId)) {
|
|
179
|
+
return fallback;
|
|
180
|
+
}
|
|
181
|
+
const candidates = [];
|
|
182
|
+
for (const candidate of [input.role, ...TYPE_SOURCE_ROLES]) {
|
|
183
|
+
if (isRequestArtifactRole(candidate) && !candidates.includes(candidate)) {
|
|
184
|
+
candidates.push(candidate);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
for (const role of candidates) {
|
|
188
|
+
const found = await showRequestArtifact({
|
|
189
|
+
projectRoot: input.projectRoot,
|
|
190
|
+
sessionId: input.sessionId,
|
|
191
|
+
role,
|
|
192
|
+
requestId: input.requestId
|
|
193
|
+
});
|
|
194
|
+
if (found === null)
|
|
195
|
+
continue;
|
|
196
|
+
const metadata = extractMetadata(found.content);
|
|
197
|
+
if (metadata.requestTypeSource === 'declared') {
|
|
198
|
+
return { requestType: metadata.requestType, requestTypeSource: 'declared' };
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
return fallback;
|
|
202
|
+
}
|
|
203
|
+
/** The composed block for a dispatch, reading the type from disk first. */
|
|
204
|
+
export async function readArtifactContractBlock(input) {
|
|
205
|
+
const reading = await readArtifactType(input);
|
|
206
|
+
return buildArtifactContractBlock({
|
|
207
|
+
role: input.role,
|
|
208
|
+
requestId: input.requestId,
|
|
209
|
+
requestType: reading.requestType,
|
|
210
|
+
requestTypeSource: reading.requestTypeSource
|
|
211
|
+
});
|
|
212
|
+
}
|
|
@@ -55,6 +55,10 @@ export type ArtifactPrerequisite = {
|
|
|
55
55
|
* the last of those, so the oldest tier still has to resolve.
|
|
56
56
|
*/
|
|
57
57
|
legacyRelativePaths?: ReadonlyArray<string>;
|
|
58
|
+
/** Back-compat window — a missing file warns instead of failing; see `prerequisite-checks.ts`. */
|
|
59
|
+
backCompat?: boolean;
|
|
60
|
+
/** The release that CLOSES that window (e.g. `v2.14.0`); the warning code's suffix. */
|
|
61
|
+
backCompatUntil?: string;
|
|
58
62
|
};
|
|
59
63
|
export type PrerequisiteCheckResult = {
|
|
60
64
|
ok: boolean;
|
|
@@ -63,15 +67,19 @@ export type PrerequisiteCheckResult = {
|
|
|
63
67
|
description: string;
|
|
64
68
|
}>;
|
|
65
69
|
/**
|
|
66
|
-
*
|
|
67
|
-
*
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
+
* Missing files inside a back-compat window (see
|
|
71
|
+
* `ArtifactPrerequisite.backCompat`). NOT a failure — the gate does not throw
|
|
72
|
+
* on these, so legacy callers keep working. They ARE reported:
|
|
73
|
+
* `transitionRequestArtifact` copies the list onto its success result and
|
|
74
|
+
* `peaks request transition` prints each one as an envelope warning, so a
|
|
75
|
+
* soft-passed prerequisite is not read as a passed one. `code` is derived per
|
|
76
|
+
* prerequisite (`prerequisite-checks.ts`), so it names which artifact.
|
|
70
77
|
*/
|
|
71
78
|
warnings: Array<{
|
|
72
79
|
path: string;
|
|
73
80
|
code: string;
|
|
74
81
|
message: string;
|
|
82
|
+
expiredWindow?: string;
|
|
75
83
|
}>;
|
|
76
84
|
};
|
|
77
85
|
export type CheckPrerequisitesOptions = {
|
|
@@ -85,20 +93,20 @@ export type CheckPrerequisitesOptions = {
|
|
|
85
93
|
role: RequestArtifactRole;
|
|
86
94
|
newState: RequestArtifactState;
|
|
87
95
|
requestId: string;
|
|
88
|
-
|
|
96
|
+
/**
|
|
97
|
+
* Required, with no default. The `?? DEFAULT_REQUEST_TYPE` that used to sit in
|
|
98
|
+
* `getPrerequisitesFor`'s signature let a caller silently select the `feature`
|
|
99
|
+
* table by omitting an argument; a caller that wants the default now has to
|
|
100
|
+
* write it, and the one place that legitimately substitutes it is the artifact
|
|
101
|
+
* reader (`request-artifact-metadata.ts`), which labels the substitution.
|
|
102
|
+
*/
|
|
103
|
+
requestType: RequestType;
|
|
104
|
+
/**
|
|
105
|
+
* False for a caller that is not a state move — the retag command's impact
|
|
106
|
+
* probe reads the table without transitioning anything, and the event stream
|
|
107
|
+
* is read as a record of transitions.
|
|
108
|
+
*/
|
|
109
|
+
emitEvents?: boolean;
|
|
89
110
|
};
|
|
90
|
-
export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType
|
|
91
|
-
/**
|
|
92
|
-
* The contract's BODY checks for one prerequisite, applied to `body`. Returns
|
|
93
|
-
* one human-readable message per failed check, empty when the body satisfies
|
|
94
|
-
* the contract.
|
|
95
|
-
*
|
|
96
|
-
* Exported because this contract has a SECOND enforcer: `peaks workflow
|
|
97
|
-
* verify-pipeline` probes the same table for the paths it checks
|
|
98
|
-
* (`pipeline-verify-gate-support.ts`), and a resolver that probed only
|
|
99
|
-
* `existsSync` passed files this function rejects — a guard laxer than the
|
|
100
|
-
* contract it claims to read. Both callers now share this one implementation,
|
|
101
|
-
* so the checker cannot drift from the table again.
|
|
102
|
-
*/
|
|
103
|
-
export declare function prerequisiteBodyViolations(prerequisite: ArtifactPrerequisite, body: string): string[];
|
|
111
|
+
export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType: RequestType): ReadonlyArray<ArtifactPrerequisite>;
|
|
104
112
|
export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;
|