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
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
export type AuditRole = 'security' | 'perf';
|
|
2
|
+
export interface HandoffMissingRefusal {
|
|
3
|
+
readonly warnings: readonly string[];
|
|
4
|
+
readonly nextActions: readonly string[];
|
|
5
|
+
}
|
|
6
|
+
/**
|
|
7
|
+
* Build the refusal payload for a `handoff-missing` detect result.
|
|
8
|
+
*
|
|
9
|
+
* `envelopeValidated` is a MEASUREMENT, not an assumption — pass
|
|
10
|
+
* `envelope !== undefined && is<Role>AuditEnvelope(envelope)`. The load-bearing
|
|
11
|
+
* sentence is emitted only when it is true: the read-only `detect` surface
|
|
12
|
+
* carries no envelope at all, so claiming there that the envelope was valid
|
|
13
|
+
* would be a claim stronger than the code.
|
|
14
|
+
*
|
|
15
|
+
* An omitted `requestId` is the un-scoped probe: `resolveHandoffPath` could only
|
|
16
|
+
* have tried `prd/handoff.md`, so the refusal must not name the slice-scoped path
|
|
17
|
+
* as the missing one, and must say that the creating command needs a `--rid`
|
|
18
|
+
* this run does not have.
|
|
19
|
+
*/
|
|
20
|
+
export declare function handoffMissingRefusal(opts: {
|
|
21
|
+
readonly role: AuditRole;
|
|
22
|
+
readonly projectRoot: string;
|
|
23
|
+
readonly sessionId: string;
|
|
24
|
+
readonly requestId?: string;
|
|
25
|
+
readonly envelopeValidated: boolean;
|
|
26
|
+
}): HandoffMissingRefusal;
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The `handoff-missing` refusal text, in one module so the security and perf
|
|
3
|
+
* arms cannot drift apart.
|
|
4
|
+
*
|
|
5
|
+
* WHY THIS EXISTS. Both audit services read `prd/handoff-<rid>.md` and refuse
|
|
6
|
+
* with detect state `handoff-missing` when it is absent — writing nothing. The
|
|
7
|
+
* refusal used to name only the DIRECTORY and never said the audit itself had
|
|
8
|
+
* succeeded. Measured twice on 2026-10-13, once per slice, by four independent
|
|
9
|
+
* reviewers — the two slice ids are named in the RD request artifact, not here,
|
|
10
|
+
* so this comment carries the fact without carrying provenance that rots:
|
|
11
|
+
* each produced an envelope that PASSED `isSecurityAuditEnvelope` /
|
|
12
|
+
* `isPerfAuditEnvelope` — so the run got past validation to this gate — and then
|
|
13
|
+
* could not land it. The refusal named a file they had never been told they
|
|
14
|
+
* would need, and the real order is handoff → audit.
|
|
15
|
+
*
|
|
16
|
+
* So the refusal now states the order: the envelope was valid, only the write is
|
|
17
|
+
* blocked, here is the missing path, here is the one command that creates it.
|
|
18
|
+
*
|
|
19
|
+
* NOT DONE HERE, deliberately: creating the handoff. An audit must not author
|
|
20
|
+
* its own input — synthesising the capsule would make the audit's premise
|
|
21
|
+
* self-supplied — so this module names the creating command and stops.
|
|
22
|
+
*/
|
|
23
|
+
import { join } from 'node:path';
|
|
24
|
+
import { handoffRelativePath } from '../prd/handoff-service.js';
|
|
25
|
+
/** Per-role names, so the two arms differ by data rather than by copy-paste. */
|
|
26
|
+
const ROLE = {
|
|
27
|
+
security: { skill: 'peaks-security-audit', validator: 'isSecurityAuditEnvelope' },
|
|
28
|
+
perf: { skill: 'peaks-perf-audit', validator: 'isPerfAuditEnvelope' }
|
|
29
|
+
};
|
|
30
|
+
/** The replaced range, by name: C0 … DEL … C1. */
|
|
31
|
+
const LAST_C0_CODE_POINT = 0x1f;
|
|
32
|
+
const DEL_CODE_POINT = 0x7f;
|
|
33
|
+
const FIRST_C1_CODE_POINT = 0x80;
|
|
34
|
+
const LAST_C1_CODE_POINT = 0x9f;
|
|
35
|
+
const isControlCodePoint = (code) => code <= LAST_C0_CODE_POINT ||
|
|
36
|
+
code === DEL_CODE_POINT ||
|
|
37
|
+
(code >= FIRST_C1_CODE_POINT && code <= LAST_C1_CODE_POINT);
|
|
38
|
+
/**
|
|
39
|
+
* A value as it may be PRINTED: control code points replaced with `?`, never
|
|
40
|
+
* truncated — the same set `printableWarningText` (`src/cli/cli-helpers.ts`) and
|
|
41
|
+
* `printableToken` (`.husky/pipeline/contract-verdict.mjs`) replace, and the same
|
|
42
|
+
* code-point comparison `printableWarningText` uses to find them.
|
|
43
|
+
*
|
|
44
|
+
* `requestId` is safe without this (`handoffRelativePath` enforces
|
|
45
|
+
* `REQUEST_ID_PATTERN`), but `sessionId` is guarded only by `isUnsafePathInput`,
|
|
46
|
+
* which rejects traversal and drive paths and NOT C0/C1 control characters. A
|
|
47
|
+
* newline in a `--sid` would otherwise split a refusal line and forge one of its
|
|
48
|
+
* own — on the very surface this module exists to make readable.
|
|
49
|
+
*/
|
|
50
|
+
function printable(value) {
|
|
51
|
+
let rendered = '';
|
|
52
|
+
for (const char of value) {
|
|
53
|
+
rendered += isControlCodePoint(char.codePointAt(0) ?? 0) ? '?' : char;
|
|
54
|
+
}
|
|
55
|
+
return rendered;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Build the refusal payload for a `handoff-missing` detect result.
|
|
59
|
+
*
|
|
60
|
+
* `envelopeValidated` is a MEASUREMENT, not an assumption — pass
|
|
61
|
+
* `envelope !== undefined && is<Role>AuditEnvelope(envelope)`. The load-bearing
|
|
62
|
+
* sentence is emitted only when it is true: the read-only `detect` surface
|
|
63
|
+
* carries no envelope at all, so claiming there that the envelope was valid
|
|
64
|
+
* would be a claim stronger than the code.
|
|
65
|
+
*
|
|
66
|
+
* An omitted `requestId` is the un-scoped probe: `resolveHandoffPath` could only
|
|
67
|
+
* have tried `prd/handoff.md`, so the refusal must not name the slice-scoped path
|
|
68
|
+
* as the missing one, and must say that the creating command needs a `--rid`
|
|
69
|
+
* this run does not have.
|
|
70
|
+
*/
|
|
71
|
+
export function handoffMissingRefusal(opts) {
|
|
72
|
+
const { skill, validator } = ROLE[opts.role];
|
|
73
|
+
// The real paths are built from the RAW ids, so `handoffRelativePath`'s guard
|
|
74
|
+
// runs on exactly the bytes `resolveHandoffPath` would probe. Each value is
|
|
75
|
+
// sanitised at the point it is interpolated, below — not here — so the render
|
|
76
|
+
// is the only thing that changes.
|
|
77
|
+
const prdDir = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId, 'prd');
|
|
78
|
+
// The path the creating command WRITES. With a rid that is the slice-scoped
|
|
79
|
+
// capsule; `resolveHandoffPath` already ran `handoffRelativePath` for these
|
|
80
|
+
// same ids on the way in, so this join cannot throw where that one did not.
|
|
81
|
+
const missingPath = opts.requestId === undefined
|
|
82
|
+
? join(prdDir, 'handoff.md')
|
|
83
|
+
: join(opts.projectRoot, handoffRelativePath(opts.sessionId, opts.requestId));
|
|
84
|
+
const createCommand = opts.requestId === undefined
|
|
85
|
+
? `peaks prd handoff init --rid <request-id> --sid ${opts.sessionId} --body <body> --apply`
|
|
86
|
+
: `peaks prd handoff init --rid ${opts.requestId} --sid ${opts.sessionId} --body <body> --apply`;
|
|
87
|
+
return {
|
|
88
|
+
warnings: [
|
|
89
|
+
`peaks-prd handoff not found under ${printable(prdDir)}`,
|
|
90
|
+
...(opts.requestId === undefined
|
|
91
|
+
? [
|
|
92
|
+
"No --rid was supplied, so only the pre-rid-scoping `prd/handoff.md` could be probed. Pass --rid to resolve this slice's `prd/handoff-<rid>.md`."
|
|
93
|
+
]
|
|
94
|
+
: [])
|
|
95
|
+
],
|
|
96
|
+
nextActions: [
|
|
97
|
+
...(opts.envelopeValidated
|
|
98
|
+
? [
|
|
99
|
+
`The audit envelope passed validation (${validator}); only the artifact write is blocked.`
|
|
100
|
+
]
|
|
101
|
+
: []),
|
|
102
|
+
opts.requestId === undefined
|
|
103
|
+
? `The only handoff path probed was: ${printable(missingPath)}`
|
|
104
|
+
: `Missing peaks-prd handoff: ${printable(missingPath)}`,
|
|
105
|
+
`Create it with: ${printable(createCommand)}`,
|
|
106
|
+
`Until the handoff exists, ${skill} cannot start (gate fail).`
|
|
107
|
+
]
|
|
108
|
+
};
|
|
109
|
+
}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading the sha256-locked PRD handoff capsule and the project-level security
|
|
3
|
+
* template. Split out of `security-audit-service.ts` so the audit service and
|
|
4
|
+
* the declaration's producer can both depend on the readers without depending
|
|
5
|
+
* on each other.
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Handoff frontmatter — minimal projection of the peaks-prd v2.11.0 handoff
|
|
9
|
+
* frontmatter. We only need sha256 for verification; the rest of the handoff
|
|
10
|
+
* body is consumed by the parent LLM, not by this service.
|
|
11
|
+
*/
|
|
12
|
+
export interface HandoffFrontmatter {
|
|
13
|
+
readonly sha256: string;
|
|
14
|
+
readonly schemaVersion: number;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Read the peaks-prd handoff frontmatter + body, verify sha256 matches
|
|
18
|
+
* the body. Returns null on missing file or sha256 mismatch; otherwise
|
|
19
|
+
* returns the parsed frontmatter + body string.
|
|
20
|
+
*
|
|
21
|
+
* Defensive: we read frontmatter via a 1-line regex match, not via
|
|
22
|
+
* a YAML parser. The handoff service (`src/services/prd/handoff-service.ts`)
|
|
23
|
+
* is the canonical writer; we only consume its output here.
|
|
24
|
+
*/
|
|
25
|
+
export declare function readAndVerifyHandoff(handoffPath: string, projectRoot: string): {
|
|
26
|
+
frontmatter: HandoffFrontmatter;
|
|
27
|
+
body: string;
|
|
28
|
+
} | null;
|
|
29
|
+
/**
|
|
30
|
+
* Read the project-level security-template.md. Returns the body
|
|
31
|
+
* string (with frontmatter stripped) or null if the file is absent.
|
|
32
|
+
* Does NOT validate the template content; the parent LLM validates
|
|
33
|
+
* by reading.
|
|
34
|
+
*/
|
|
35
|
+
export declare function readSecurityTemplate(projectRoot: string): string | null;
|
|
36
|
+
/** The verified handoff's sha256, or `unknown` when there is no capsule. */
|
|
37
|
+
export declare function resolveHandoffHash(projectRoot: string, sessionId: string, rid: string): string;
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Reading the sha256-locked PRD handoff capsule and the project-level security
|
|
3
|
+
* template. Split out of `security-audit-service.ts` so the audit service and
|
|
4
|
+
* the declaration's producer can both depend on the readers without depending
|
|
5
|
+
* on each other.
|
|
6
|
+
*/
|
|
7
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
8
|
+
import { join, resolve, isAbsolute } from 'node:path';
|
|
9
|
+
import { createHash } from 'node:crypto';
|
|
10
|
+
import { resolveHandoffPath } from '../prd/handoff-service.js';
|
|
11
|
+
/**
|
|
12
|
+
* Read the peaks-prd handoff frontmatter + body, verify sha256 matches
|
|
13
|
+
* the body. Returns null on missing file or sha256 mismatch; otherwise
|
|
14
|
+
* returns the parsed frontmatter + body string.
|
|
15
|
+
*
|
|
16
|
+
* Defensive: we read frontmatter via a 1-line regex match, not via
|
|
17
|
+
* a YAML parser. The handoff service (`src/services/prd/handoff-service.ts`)
|
|
18
|
+
* is the canonical writer; we only consume its output here.
|
|
19
|
+
*/
|
|
20
|
+
export function readAndVerifyHandoff(handoffPath, projectRoot) {
|
|
21
|
+
if (!handoffPath || !isAbsolute(handoffPath)) {
|
|
22
|
+
const absolutePath = resolve(projectRoot, handoffPath);
|
|
23
|
+
if (!existsSync(absolutePath))
|
|
24
|
+
return null;
|
|
25
|
+
return readAndVerifyHandoff(absolutePath, projectRoot);
|
|
26
|
+
}
|
|
27
|
+
if (!existsSync(handoffPath))
|
|
28
|
+
return null;
|
|
29
|
+
let raw;
|
|
30
|
+
try {
|
|
31
|
+
raw = readFileSync(handoffPath, 'utf8');
|
|
32
|
+
}
|
|
33
|
+
catch {
|
|
34
|
+
// TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
// Frontmatter pattern: `---` line, then key: value pairs, then `---` line.
|
|
38
|
+
const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
|
|
39
|
+
if (match === null)
|
|
40
|
+
return null;
|
|
41
|
+
const frontmatterRaw = match[1];
|
|
42
|
+
const body = match[2];
|
|
43
|
+
const sha256Match = frontmatterRaw.match(/^sha256:\s*([a-f0-9]{64})\s*$/m);
|
|
44
|
+
const schemaVersionMatch = frontmatterRaw.match(/^schemaVersion:\s*(\d+)\s*$/m);
|
|
45
|
+
if (sha256Match === null || schemaVersionMatch === null)
|
|
46
|
+
return null;
|
|
47
|
+
const sha256Expected = sha256Match[1];
|
|
48
|
+
const schemaVersion = parseInt(schemaVersionMatch[1], 10);
|
|
49
|
+
const sha256Actual = createHash('sha256').update(body, 'utf8').digest('hex');
|
|
50
|
+
if (sha256Expected !== sha256Actual)
|
|
51
|
+
return null;
|
|
52
|
+
return {
|
|
53
|
+
frontmatter: { sha256: sha256Expected, schemaVersion },
|
|
54
|
+
body
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Read the project-level security-template.md. Returns the body
|
|
59
|
+
* string (with frontmatter stripped) or null if the file is absent.
|
|
60
|
+
* Does NOT validate the template content; the parent LLM validates
|
|
61
|
+
* by reading.
|
|
62
|
+
*/
|
|
63
|
+
export function readSecurityTemplate(projectRoot) {
|
|
64
|
+
const templatePath = join(projectRoot, '.peaks', 'project-scan', 'security-template.md');
|
|
65
|
+
if (!existsSync(templatePath))
|
|
66
|
+
return null;
|
|
67
|
+
try {
|
|
68
|
+
return readFileSync(templatePath, 'utf8');
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
// TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
|
|
72
|
+
return null;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
/** The verified handoff's sha256, or `unknown` when there is no capsule. */
|
|
76
|
+
export function resolveHandoffHash(projectRoot, sessionId, rid) {
|
|
77
|
+
const handoffPath = resolveHandoffPath({ projectRoot, sessionId, requestId: rid });
|
|
78
|
+
if (handoffPath === null)
|
|
79
|
+
return 'unknown';
|
|
80
|
+
return readAndVerifyHandoff(handoffPath, projectRoot)?.frontmatter.sha256 ?? 'unknown';
|
|
81
|
+
}
|
|
@@ -1,2 +1,7 @@
|
|
|
1
|
-
export { runSecurityAudit, isSecurityAuditEnvelope, detectSecurityAudit,
|
|
1
|
+
export { runSecurityAudit, isSecurityAuditEnvelope, detectSecurityAudit, type SecurityAuditEnvelope, type SecurityAuditViolation, type SecurityAuditVerdict, type SecurityAuditDetectState, type SecurityAuditDetectResult } from './security-audit-service.js';
|
|
2
|
+
export { readSecurityTemplate, readAndVerifyHandoff, resolveHandoffHash, type HandoffFrontmatter } from './handoff-readers.js';
|
|
3
|
+
export { renderSecurityAuditArtifact, writeSecurityAuditArtifact } from './security-audit-artifact.js';
|
|
4
|
+
export { parseJudgedDeclaration, renderJudgedDeclaration, sha256OfFile, type JudgedDeclaration } from './judged-declaration.js';
|
|
5
|
+
export { buildJudgedDeclaration, buildJudgedDeclarationFor } from './judged-declaration-build.js';
|
|
6
|
+
export { verifyJudgedDeclaration, resolveSecurityArtifact, type JudgedCheckResult, type JudgedRefusal } from './judged-declaration-check.js';
|
|
2
7
|
export { runPerfAudit, isPerfAuditEnvelope, detectPerfAudit, readPerfTemplate, renderPerfAuditArtifact, type PerfAuditEnvelope, type PerfAuditViolation, type PerfAuditVerdict, type PerfAuditDetectState, type PerfAuditDetectResult } from './perf-audit-service.js';
|
|
@@ -1,2 +1,7 @@
|
|
|
1
|
-
export { runSecurityAudit, isSecurityAuditEnvelope, detectSecurityAudit
|
|
1
|
+
export { runSecurityAudit, isSecurityAuditEnvelope, detectSecurityAudit } from './security-audit-service.js';
|
|
2
|
+
export { readSecurityTemplate, readAndVerifyHandoff, resolveHandoffHash } from './handoff-readers.js';
|
|
3
|
+
export { renderSecurityAuditArtifact, writeSecurityAuditArtifact } from './security-audit-artifact.js';
|
|
4
|
+
export { parseJudgedDeclaration, renderJudgedDeclaration, sha256OfFile } from './judged-declaration.js';
|
|
5
|
+
export { buildJudgedDeclaration, buildJudgedDeclarationFor } from './judged-declaration-build.js';
|
|
6
|
+
export { verifyJudgedDeclaration, resolveSecurityArtifact } from './judged-declaration-check.js';
|
|
2
7
|
export { runPerfAudit, isPerfAuditEnvelope, detectPerfAudit, readPerfTemplate, renderPerfAuditArtifact } from './perf-audit-service.js';
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Building a declaration: hashing the judged paths against the tree, and the
|
|
3
|
+
* detect result the producer substitutes when that build fails. Split from
|
|
4
|
+
* `judged-declaration.ts`, which carries the grammar and the parser.
|
|
5
|
+
*/
|
|
6
|
+
import { type JudgedDeclaration, type JudgedParseFailure } from './judged-declaration.js';
|
|
7
|
+
/**
|
|
8
|
+
* Build the declaration for one audit run from the slice's own identifiers.
|
|
9
|
+
* The caller passes its own input object straight through, so the producer
|
|
10
|
+
* needs one call rather than an argument list it would have to grow a branch
|
|
11
|
+
* to guard.
|
|
12
|
+
*/
|
|
13
|
+
export declare function buildJudgedDeclarationFor(input: {
|
|
14
|
+
readonly projectRoot: string;
|
|
15
|
+
readonly sessionId: string;
|
|
16
|
+
readonly rid: string;
|
|
17
|
+
readonly generatedAt: string;
|
|
18
|
+
readonly judgedPaths: readonly string[];
|
|
19
|
+
}): {
|
|
20
|
+
ok: true;
|
|
21
|
+
declaration: JudgedDeclaration;
|
|
22
|
+
handoffHash: string;
|
|
23
|
+
} | JudgedParseFailure;
|
|
24
|
+
/** Build a declaration from concrete paths, hashing each against the tree.
|
|
25
|
+
* `roots` is always empty here: no producer in this repo emits a directory
|
|
26
|
+
* root yet, so the gained-path arm is reachable only through the grammar, not
|
|
27
|
+
* through a run. The check supports it and tests it; this builder does not
|
|
28
|
+
* offer it. */
|
|
29
|
+
export declare function buildJudgedDeclaration(input: {
|
|
30
|
+
readonly projectRoot: string;
|
|
31
|
+
readonly judgedAt: string;
|
|
32
|
+
readonly handoffHash: string;
|
|
33
|
+
readonly paths: readonly string[];
|
|
34
|
+
}): {
|
|
35
|
+
ok: true;
|
|
36
|
+
declaration: JudgedDeclaration;
|
|
37
|
+
} | {
|
|
38
|
+
ok: false;
|
|
39
|
+
code: string;
|
|
40
|
+
detail: string;
|
|
41
|
+
};
|
|
42
|
+
/**
|
|
43
|
+
* The rendered section for a set of paths, for a producer that has a project
|
|
44
|
+
* root and a file list but no handoff capsule. Returns an empty string when
|
|
45
|
+
* nothing can be declared — the artifact is then refused by the check, which is
|
|
46
|
+
* the contract's whole point rather than a fallback to fix here.
|
|
47
|
+
*/
|
|
48
|
+
export declare function renderJudgedSection(projectRoot: string, paths: readonly string[]): string;
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Building a declaration: hashing the judged paths against the tree, and the
|
|
3
|
+
* detect result the producer substitutes when that build fails. Split from
|
|
4
|
+
* `judged-declaration.ts`, which carries the grammar and the parser.
|
|
5
|
+
*/
|
|
6
|
+
import { join } from 'node:path';
|
|
7
|
+
import { JUDGED_SCHEMA_VERSION, renderJudgedDeclaration, sha256OfFile, validateDeclaredPath } from './judged-declaration.js';
|
|
8
|
+
import { resolveHandoffHash } from './handoff-readers.js';
|
|
9
|
+
/**
|
|
10
|
+
* Build the declaration for one audit run from the slice's own identifiers.
|
|
11
|
+
* The caller passes its own input object straight through, so the producer
|
|
12
|
+
* needs one call rather than an argument list it would have to grow a branch
|
|
13
|
+
* to guard.
|
|
14
|
+
*/
|
|
15
|
+
export function buildJudgedDeclarationFor(input) {
|
|
16
|
+
const handoffHash = resolveHandoffHash(input.projectRoot, input.sessionId, input.rid);
|
|
17
|
+
const built = buildJudgedDeclaration({
|
|
18
|
+
projectRoot: input.projectRoot,
|
|
19
|
+
judgedAt: input.generatedAt,
|
|
20
|
+
handoffHash,
|
|
21
|
+
paths: input.judgedPaths
|
|
22
|
+
});
|
|
23
|
+
return built.ok ? { ...built, handoffHash } : built;
|
|
24
|
+
}
|
|
25
|
+
/** Build a declaration from concrete paths, hashing each against the tree.
|
|
26
|
+
* `roots` is always empty here: no producer in this repo emits a directory
|
|
27
|
+
* root yet, so the gained-path arm is reachable only through the grammar, not
|
|
28
|
+
* through a run. The check supports it and tests it; this builder does not
|
|
29
|
+
* offer it. */
|
|
30
|
+
export function buildJudgedDeclaration(input) {
|
|
31
|
+
const files = [];
|
|
32
|
+
const seen = new Set();
|
|
33
|
+
for (const raw of input.paths) {
|
|
34
|
+
const checked = validateDeclaredPath(raw);
|
|
35
|
+
if (!checked.ok)
|
|
36
|
+
return { ok: false, code: 'declaration-path', detail: checked.detail };
|
|
37
|
+
if (seen.has(checked.path))
|
|
38
|
+
continue;
|
|
39
|
+
seen.add(checked.path);
|
|
40
|
+
const hashed = sha256OfFile(join(input.projectRoot, ...checked.path.split('/')));
|
|
41
|
+
if (!hashed.ok)
|
|
42
|
+
return { ok: false, code: `declared-path-${hashed.code}`, detail: checked.path };
|
|
43
|
+
files.push({ path: checked.path, sha256: hashed.sha256 });
|
|
44
|
+
}
|
|
45
|
+
if (files.length === 0)
|
|
46
|
+
return { ok: false, code: 'declaration-empty', detail: 'no judged paths' };
|
|
47
|
+
files.sort((a, b) => (a.path < b.path ? -1 : 1));
|
|
48
|
+
return {
|
|
49
|
+
ok: true,
|
|
50
|
+
declaration: {
|
|
51
|
+
schemaVersion: JUDGED_SCHEMA_VERSION,
|
|
52
|
+
judgedAt: input.judgedAt,
|
|
53
|
+
handoffHash: input.handoffHash,
|
|
54
|
+
files,
|
|
55
|
+
roots: []
|
|
56
|
+
}
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* The rendered section for a set of paths, for a producer that has a project
|
|
61
|
+
* root and a file list but no handoff capsule. Returns an empty string when
|
|
62
|
+
* nothing can be declared — the artifact is then refused by the check, which is
|
|
63
|
+
* the contract's whole point rather than a fallback to fix here.
|
|
64
|
+
*/
|
|
65
|
+
export function renderJudgedSection(projectRoot, paths) {
|
|
66
|
+
const built = buildJudgedDeclaration({
|
|
67
|
+
projectRoot,
|
|
68
|
+
judgedAt: new Date(0).toISOString(),
|
|
69
|
+
handoffHash: 'unknown',
|
|
70
|
+
paths
|
|
71
|
+
});
|
|
72
|
+
return built.ok ? `\n${renderJudgedDeclaration(built.declaration)}` : '';
|
|
73
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The check that reads a declaration back and refuses when the tree moved.
|
|
3
|
+
*
|
|
4
|
+
* It hashes the bytes of every declared path. A commit does not change bytes,
|
|
5
|
+
* so the check is commitment-invariant by construction rather than by way of a
|
|
6
|
+
* git ref. A rename or a delete removes the path, and a rewrite changes its
|
|
7
|
+
* hash; each is refused by name. A path that appears under a declared root and
|
|
8
|
+
* was not declared is refused too, which is the one arm that needs a tree
|
|
9
|
+
* listing rather than a hash.
|
|
10
|
+
*
|
|
11
|
+
* The listing is `git ls-files -c -o --exclude-standard`, which is invariant
|
|
12
|
+
* under a commit: a commit redistributes tracked and untracked entries, it does
|
|
13
|
+
* not change the set of files on disk.
|
|
14
|
+
*
|
|
15
|
+
* Absence rule, stated where the producer reads it: an artifact that is present
|
|
16
|
+
* but carries no declaration is refused. There is no back-compat window,
|
|
17
|
+
* because this check is reached only from a transition that a slice in flight
|
|
18
|
+
* can re-run.
|
|
19
|
+
*/
|
|
20
|
+
import { type JudgedDeclaration } from './judged-declaration.js';
|
|
21
|
+
export type JudgedRefusal = {
|
|
22
|
+
readonly code: string;
|
|
23
|
+
readonly artifact: string;
|
|
24
|
+
readonly path: string;
|
|
25
|
+
};
|
|
26
|
+
export type JudgedCheckResult = {
|
|
27
|
+
readonly refusals: readonly JudgedRefusal[];
|
|
28
|
+
readonly checked: number;
|
|
29
|
+
};
|
|
30
|
+
/** Where the security audit artifact may live, newest tier first. */
|
|
31
|
+
export declare function securityArtifactTiers(rid: string): readonly string[];
|
|
32
|
+
export declare function resolveSecurityArtifact(projectRoot: string, sessionId: string, rid: string): {
|
|
33
|
+
readonly relative: string;
|
|
34
|
+
readonly absolute: string;
|
|
35
|
+
} | null;
|
|
36
|
+
type TreeListing = {
|
|
37
|
+
readonly ok: true;
|
|
38
|
+
readonly files: readonly string[];
|
|
39
|
+
} | {
|
|
40
|
+
readonly ok: false;
|
|
41
|
+
readonly detail: string;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* List the files git knows about under a prefix. Fail-closed: a git read that
|
|
45
|
+
* did not happen is reported, never returned as an empty list.
|
|
46
|
+
*/
|
|
47
|
+
export declare function listTreeFiles(projectRoot: string, prefix: string): TreeListing;
|
|
48
|
+
/** Compare the declaration against the tree. Returns refusals, ordered by path. */
|
|
49
|
+
export declare function checkDeclarationAgainstTree(input: {
|
|
50
|
+
readonly projectRoot: string;
|
|
51
|
+
readonly artifact: string;
|
|
52
|
+
readonly declaration: JudgedDeclaration;
|
|
53
|
+
}): readonly JudgedRefusal[];
|
|
54
|
+
/**
|
|
55
|
+
* Entry point for the transition gate. An artifact that is not there is not
|
|
56
|
+
* this check's business — the artifact-existence prerequisite owns that.
|
|
57
|
+
*
|
|
58
|
+
* LIMIT, measured rather than assumed — the hole that survives is COMPLETENESS,
|
|
59
|
+
* not tampering: the declaration is the producer's own statement, so ten files
|
|
60
|
+
* touched and one declared passes. Nothing here can know what the producer did
|
|
61
|
+
* not say. Rule: a declaration is a claim about the paths it names, never a
|
|
62
|
+
* claim that those are all the paths.
|
|
63
|
+
*
|
|
64
|
+
* Absence rule, stated where the producer reads it, and the reason it is this
|
|
65
|
+
* blunt: a security artifact that IS there must carry a declaration. No section
|
|
66
|
+
* of the artifact turns the check off, because a requirement that any section
|
|
67
|
+
* can switch off is not a requirement — an earlier draft of this file keyed the
|
|
68
|
+
* requirement on a marker line in the coverage block, and deleting that block
|
|
69
|
+
* (while keeping the declaration, and then rewriting a declared path) passed.
|
|
70
|
+
* The cost is stated rather than hidden: an artifact written before this change
|
|
71
|
+
* is refused until the audit is re-run, and the gate only fires on a
|
|
72
|
+
* transition, so nothing already committed is affected.
|
|
73
|
+
*/
|
|
74
|
+
export declare function verifyJudgedDeclaration(input: {
|
|
75
|
+
readonly projectRoot: string;
|
|
76
|
+
readonly sessionId: string;
|
|
77
|
+
readonly requestId: string;
|
|
78
|
+
}): JudgedCheckResult;
|
|
79
|
+
export {};
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The check that reads a declaration back and refuses when the tree moved.
|
|
3
|
+
*
|
|
4
|
+
* It hashes the bytes of every declared path. A commit does not change bytes,
|
|
5
|
+
* so the check is commitment-invariant by construction rather than by way of a
|
|
6
|
+
* git ref. A rename or a delete removes the path, and a rewrite changes its
|
|
7
|
+
* hash; each is refused by name. A path that appears under a declared root and
|
|
8
|
+
* was not declared is refused too, which is the one arm that needs a tree
|
|
9
|
+
* listing rather than a hash.
|
|
10
|
+
*
|
|
11
|
+
* The listing is `git ls-files -c -o --exclude-standard`, which is invariant
|
|
12
|
+
* under a commit: a commit redistributes tracked and untracked entries, it does
|
|
13
|
+
* not change the set of files on disk.
|
|
14
|
+
*
|
|
15
|
+
* Absence rule, stated where the producer reads it: an artifact that is present
|
|
16
|
+
* but carries no declaration is refused. There is no back-compat window,
|
|
17
|
+
* because this check is reached only from a transition that a slice in flight
|
|
18
|
+
* can re-run.
|
|
19
|
+
*/
|
|
20
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
21
|
+
import { execFileSync } from 'node:child_process';
|
|
22
|
+
import { join } from 'node:path';
|
|
23
|
+
import { parseJudgedDeclaration, sha256OfFile } from './judged-declaration.js';
|
|
24
|
+
/** Where the security audit artifact may live, newest tier first. */
|
|
25
|
+
export function securityArtifactTiers(rid) {
|
|
26
|
+
return [
|
|
27
|
+
`audit/security-${rid}.md`,
|
|
28
|
+
'audit/security.md',
|
|
29
|
+
`rd/security-review-${rid}.md`,
|
|
30
|
+
'rd/security-review.md'
|
|
31
|
+
];
|
|
32
|
+
}
|
|
33
|
+
export function resolveSecurityArtifact(projectRoot, sessionId, rid) {
|
|
34
|
+
const root = join(projectRoot, '.peaks', '_runtime', sessionId);
|
|
35
|
+
for (const relative of securityArtifactTiers(rid)) {
|
|
36
|
+
const absolute = join(root, ...relative.split('/'));
|
|
37
|
+
if (existsSync(absolute))
|
|
38
|
+
return { relative, absolute };
|
|
39
|
+
}
|
|
40
|
+
return null;
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* List the files git knows about under a prefix. Fail-closed: a git read that
|
|
44
|
+
* did not happen is reported, never returned as an empty list.
|
|
45
|
+
*/
|
|
46
|
+
export function listTreeFiles(projectRoot, prefix) {
|
|
47
|
+
try {
|
|
48
|
+
const raw = execFileSync('git', ['-C', projectRoot, 'ls-files', '-c', '-o', '--exclude-standard', '--', prefix], { encoding: 'utf8', windowsHide: true });
|
|
49
|
+
const files = raw
|
|
50
|
+
.split(/\r?\n/)
|
|
51
|
+
.map((line) => line.trim())
|
|
52
|
+
.filter((line) => line.length > 0);
|
|
53
|
+
return { ok: true, files };
|
|
54
|
+
}
|
|
55
|
+
catch (error) {
|
|
56
|
+
return { ok: false, detail: error instanceof Error ? error.message : String(error) };
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
function readArtifact(absolute) {
|
|
60
|
+
try {
|
|
61
|
+
return { ok: true, body: readFileSync(absolute, 'utf8') };
|
|
62
|
+
}
|
|
63
|
+
catch (error) {
|
|
64
|
+
return { ok: false, detail: error instanceof Error ? error.message : String(error) };
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
function fileRefusals(input) {
|
|
68
|
+
const refusals = [];
|
|
69
|
+
for (const file of input.files) {
|
|
70
|
+
const hashed = sha256OfFile(join(input.projectRoot, ...file.path.split('/')));
|
|
71
|
+
if (!hashed.ok) {
|
|
72
|
+
refusals.push({
|
|
73
|
+
code: hashed.code === 'missing' ? 'declared-path-gone' : 'declared-path-unreadable',
|
|
74
|
+
artifact: input.artifact,
|
|
75
|
+
path: file.path
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
else if (hashed.sha256 !== file.sha256) {
|
|
79
|
+
refusals.push({ code: 'declared-path-modified', artifact: input.artifact, path: file.path });
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
return refusals;
|
|
83
|
+
}
|
|
84
|
+
function rootRefusals(input) {
|
|
85
|
+
const refusals = [];
|
|
86
|
+
for (const root of input.roots) {
|
|
87
|
+
const listed = listTreeFiles(input.projectRoot, root.path);
|
|
88
|
+
if (!listed.ok) {
|
|
89
|
+
refusals.push({ code: 'root-listing-failed', artifact: input.artifact, path: root.path });
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
for (const found of listed.files) {
|
|
93
|
+
if (input.declared.has(found))
|
|
94
|
+
continue;
|
|
95
|
+
if (found !== root.path && !found.startsWith(`${root.path}/`))
|
|
96
|
+
continue;
|
|
97
|
+
refusals.push({ code: 'undeclared-path-under-root', artifact: input.artifact, path: found });
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return refusals;
|
|
101
|
+
}
|
|
102
|
+
/** Compare the declaration against the tree. Returns refusals, ordered by path. */
|
|
103
|
+
export function checkDeclarationAgainstTree(input) {
|
|
104
|
+
const refusals = [
|
|
105
|
+
...fileRefusals({ ...input, files: input.declaration.files }),
|
|
106
|
+
...rootRefusals({
|
|
107
|
+
...input,
|
|
108
|
+
roots: input.declaration.roots,
|
|
109
|
+
declared: new Set(input.declaration.files.map((f) => f.path))
|
|
110
|
+
})
|
|
111
|
+
];
|
|
112
|
+
return refusals.sort((a, b) => (a.path < b.path ? -1 : 1));
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Entry point for the transition gate. An artifact that is not there is not
|
|
116
|
+
* this check's business — the artifact-existence prerequisite owns that.
|
|
117
|
+
*
|
|
118
|
+
* LIMIT, measured rather than assumed — the hole that survives is COMPLETENESS,
|
|
119
|
+
* not tampering: the declaration is the producer's own statement, so ten files
|
|
120
|
+
* touched and one declared passes. Nothing here can know what the producer did
|
|
121
|
+
* not say. Rule: a declaration is a claim about the paths it names, never a
|
|
122
|
+
* claim that those are all the paths.
|
|
123
|
+
*
|
|
124
|
+
* Absence rule, stated where the producer reads it, and the reason it is this
|
|
125
|
+
* blunt: a security artifact that IS there must carry a declaration. No section
|
|
126
|
+
* of the artifact turns the check off, because a requirement that any section
|
|
127
|
+
* can switch off is not a requirement — an earlier draft of this file keyed the
|
|
128
|
+
* requirement on a marker line in the coverage block, and deleting that block
|
|
129
|
+
* (while keeping the declaration, and then rewriting a declared path) passed.
|
|
130
|
+
* The cost is stated rather than hidden: an artifact written before this change
|
|
131
|
+
* is refused until the audit is re-run, and the gate only fires on a
|
|
132
|
+
* transition, so nothing already committed is affected.
|
|
133
|
+
*/
|
|
134
|
+
export function verifyJudgedDeclaration(input) {
|
|
135
|
+
const resolved = resolveSecurityArtifact(input.projectRoot, input.sessionId, input.requestId);
|
|
136
|
+
if (resolved === null)
|
|
137
|
+
return { refusals: [], checked: 0 };
|
|
138
|
+
const artifact = resolved.relative;
|
|
139
|
+
const read = readArtifact(resolved.absolute);
|
|
140
|
+
if (!read.ok) {
|
|
141
|
+
return { refusals: [{ code: 'artifact-unreadable', artifact, path: artifact }], checked: 0 };
|
|
142
|
+
}
|
|
143
|
+
const parsed = parseJudgedDeclaration(read.body);
|
|
144
|
+
if (!parsed.ok) {
|
|
145
|
+
// The refusal no section can switch off: the declaration is missing, or it
|
|
146
|
+
// does not parse to the grammar.
|
|
147
|
+
return { refusals: [{ code: parsed.code, artifact, path: artifact }], checked: 0 };
|
|
148
|
+
}
|
|
149
|
+
const refusals = checkDeclarationAgainstTree({
|
|
150
|
+
projectRoot: input.projectRoot,
|
|
151
|
+
artifact,
|
|
152
|
+
declaration: parsed.declaration
|
|
153
|
+
});
|
|
154
|
+
return { refusals, checked: parsed.declaration.files.length };
|
|
155
|
+
}
|