peaks-loop 4.1.4 → 4.1.6
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 +148 -0
- package/README-en.md +47 -183
- package/README.md +24 -188
- 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/best-practice-scan-command.d.ts +11 -6
- package/dist/cli/commands/best-practice-scan-command.js +35 -20
- package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
- package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
- package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
- package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -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-command-spec.js +1 -1
- package/dist/cli/commands/dispatch-commands.js +12 -5
- package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
- package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
- package/dist/cli/commands/dispatch-preflight.js +46 -0
- package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
- package/dist/cli/commands/dispatch-prompt-composition.d.ts +7 -1
- package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
- package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
- package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
- 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/openspec-command-shared.js +2 -2
- 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/{vm-status-command.d.ts → request-retag-command.d.ts} +1 -1
- 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 +76 -7
- package/dist/cli/commands/request-transition-preflight.js +1 -1
- package/dist/cli/commands/scan-scope-commands.js +2 -2
- package/dist/cli/commands/security-audit-commands.js +26 -6
- package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
- package/dist/cli/commands/verdict-aggregate-command.js +2 -1
- package/dist/cli/commands/workflow-gate-commands.js +4 -4
- package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
- package/dist/cli/program.js +0 -2
- package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
- package/dist/services/artifacts/artifact-contract-block.js +231 -0
- package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
- package/dist/services/artifacts/artifact-prerequisites.js +65 -135
- 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/rd-transition-gates.d.ts +33 -0
- package/dist/services/artifacts/rd-transition-gates.js +71 -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 +43 -69
- package/dist/services/artifacts/request-artifact-state-helpers.d.ts +21 -1
- package/dist/services/artifacts/request-artifact-state-helpers.js +34 -8
- 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 +80 -0
- package/dist/services/audit-independent/judged-declaration-check.js +216 -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 +8 -12
- package/dist/services/context/build-dispatch-system-prompt.js +18 -18
- package/dist/services/context/collector.js +5 -1
- package/dist/services/context/post-compact-reinjection.js +1 -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/dispatch/test-tool-detection.d.ts +17 -1
- package/dist/services/dispatch/test-tool-detection.js +12 -1
- package/dist/services/evidence/evidence-generator.js +23 -12
- 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/openspec/coverage-evidence-reader.d.ts +9 -9
- package/dist/services/openspec/coverage-evidence-reader.js +8 -8
- package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
- package/dist/services/openspec/openspec-archive-service.js +6 -6
- 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 +33 -0
- package/dist/services/scan/file-size-baseline.js +173 -0
- package/dist/services/scan/file-size-scan.d.ts +35 -3
- package/dist/services/scan/file-size-scan.js +63 -42
- package/dist/services/scan/type-corroboration.d.ts +32 -0
- package/dist/services/scan/type-corroboration.js +51 -0
- package/dist/services/scan/type-sanity-service.d.ts +14 -0
- package/dist/services/scan/type-sanity-service.js +23 -22
- package/dist/services/security/safe-settings-path.d.ts +5 -0
- package/dist/services/security/safe-settings-path.js +64 -8
- package/dist/services/skill/resume-detector.js +11 -11
- 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.d.ts +24 -8
- package/dist/services/workflow/pipeline-verify-gate-support.js +34 -39
- package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
- package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
- package/dist/services/workflow/pipeline-verify-service.js +27 -28
- package/dist/services/workflow/request-type-resolution.d.ts +99 -0
- package/dist/services/workflow/request-type-resolution.js +130 -0
- package/dist/services/workflow/workflow-skip-service.d.ts +1 -20
- package/dist/services/workflow/workflow-skip-service.js +22 -25
- package/dist/services/workflow/workflow-state-store.d.ts +9 -0
- package/dist/services/workflow/workflow-state-store.js +26 -1
- 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 +33 -2
- package/dist/shared/incrementing-number.js +72 -3
- package/package.json +5 -7
- package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
- package/skills/bee/peaks-prd/SKILL.md +4 -3
- 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 +37 -17
- 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/cli/commands/vm-command-shared.d.ts +0 -23
- package/dist/cli/commands/vm-command-shared.js +0 -23
- package/dist/cli/commands/vm-commands.d.ts +0 -3
- package/dist/cli/commands/vm-commands.js +0 -45
- package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
- package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
- package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
- package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
- package/dist/cli/commands/vm-release-command.d.ts +0 -5
- package/dist/cli/commands/vm-release-command.js +0 -101
- package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
- package/dist/cli/commands/vm-spawn-command.js +0 -177
- package/dist/cli/commands/vm-status-command.js +0 -50
- 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
- package/dist/services/vm/vm-lease.d.ts +0 -40
- package/dist/services/vm/vm-lease.js +0 -160
|
@@ -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,80 @@
|
|
|
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 declare function describeJudgedRefusal(refusal: JudgedRefusal): string;
|
|
27
|
+
export type JudgedCheckResult = {
|
|
28
|
+
readonly refusals: readonly JudgedRefusal[];
|
|
29
|
+
readonly checked: number;
|
|
30
|
+
};
|
|
31
|
+
/** Where the security audit artifact may live, newest tier first. */
|
|
32
|
+
export declare function securityArtifactTiers(rid: string): readonly string[];
|
|
33
|
+
export declare function resolveSecurityArtifact(projectRoot: string, sessionId: string, rid: string): {
|
|
34
|
+
readonly relative: string;
|
|
35
|
+
readonly absolute: string;
|
|
36
|
+
} | null;
|
|
37
|
+
type TreeListing = {
|
|
38
|
+
readonly ok: true;
|
|
39
|
+
readonly files: readonly string[];
|
|
40
|
+
} | {
|
|
41
|
+
readonly ok: false;
|
|
42
|
+
readonly detail: string;
|
|
43
|
+
};
|
|
44
|
+
/**
|
|
45
|
+
* List the files git knows about under a prefix. Fail-closed: a git read that
|
|
46
|
+
* did not happen is reported, never returned as an empty list.
|
|
47
|
+
*/
|
|
48
|
+
export declare function listTreeFiles(projectRoot: string, prefix: string): TreeListing;
|
|
49
|
+
/** Compare the declaration against the tree. Returns refusals, ordered by path. */
|
|
50
|
+
export declare function checkDeclarationAgainstTree(input: {
|
|
51
|
+
readonly projectRoot: string;
|
|
52
|
+
readonly artifact: string;
|
|
53
|
+
readonly declaration: JudgedDeclaration;
|
|
54
|
+
}): readonly JudgedRefusal[];
|
|
55
|
+
/**
|
|
56
|
+
* Entry point for the transition gate. An artifact that is not there is not
|
|
57
|
+
* this check's business — the artifact-existence prerequisite owns that.
|
|
58
|
+
*
|
|
59
|
+
* LIMIT, measured rather than assumed — the hole that survives is COMPLETENESS,
|
|
60
|
+
* not tampering: the declaration is the producer's own statement, so ten files
|
|
61
|
+
* touched and one declared passes. Nothing here can know what the producer did
|
|
62
|
+
* not say. Rule: a declaration is a claim about the paths it names, never a
|
|
63
|
+
* claim that those are all the paths.
|
|
64
|
+
*
|
|
65
|
+
* Absence rule, stated where the producer reads it, and the reason it is this
|
|
66
|
+
* blunt: a security artifact that IS there must carry a declaration. No section
|
|
67
|
+
* of the artifact turns the check off, because a requirement that any section
|
|
68
|
+
* can switch off is not a requirement — an earlier draft of this file keyed the
|
|
69
|
+
* requirement on a marker line in the coverage block, and deleting that block
|
|
70
|
+
* (while keeping the declaration, and then rewriting a declared path) passed.
|
|
71
|
+
* The cost is stated rather than hidden: an artifact written before this change
|
|
72
|
+
* is refused until the audit is re-run, and the gate only fires on a
|
|
73
|
+
* transition, so nothing already committed is affected.
|
|
74
|
+
*/
|
|
75
|
+
export declare function verifyJudgedDeclaration(input: {
|
|
76
|
+
readonly projectRoot: string;
|
|
77
|
+
readonly sessionId: string;
|
|
78
|
+
readonly requestId: string;
|
|
79
|
+
}): JudgedCheckResult;
|
|
80
|
+
export {};
|
|
@@ -0,0 +1,216 @@
|
|
|
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 { JUDGED_HEADING, parseJudgedDeclaration, sha256OfFile } from './judged-declaration.js';
|
|
24
|
+
/**
|
|
25
|
+
* What a refusal means, partitioned by THE ONE QUESTION its codes answer:
|
|
26
|
+
* **did this check complete the observation its sentence would assert?** One
|
|
27
|
+
* sentence for all 17 told a producer to satisfy a declaration a `declared-path-*`
|
|
28
|
+
* refusal had already read — "name the requirement that is unmet" broken one level
|
|
29
|
+
* in, and the reason the arm has been split four times since. The partition below
|
|
30
|
+
* is stated so a reviewer checks it, rather than hunting members:
|
|
31
|
+
*
|
|
32
|
+
* A. `declaration-*` — **11 codes** (`missing`, `unfenced`, `unterminated`,
|
|
33
|
+
* `empty`, `schema`, `path`, `hash`, `duplicate`, `bare-root`, `escaped`,
|
|
34
|
+
* `unparsable`). No declaration was read at all, so the sentence is about the
|
|
35
|
+
* BLOCK and claims nothing about the tree.
|
|
36
|
+
* B. `artifact-unreadable` — **1**. The artifact was not read; nothing about its
|
|
37
|
+
* declaration is known.
|
|
38
|
+
* C. `declared-path-unreadable` — **1**. The path was reached and could not be
|
|
39
|
+
* read, so its hash is **UNKNOWN**, not mismatched. Its own arm because the
|
|
40
|
+
* remedy differs and "re-run the producer" cannot work: a re-run hashes the
|
|
41
|
+
* same unreadable path and refuses identically.
|
|
42
|
+
* D. `root-listing-failed` — **1**. A root was declared and could NOT be listed,
|
|
43
|
+
* so no file under it was compared. Its answer is "no observation", not
|
|
44
|
+
* "mismatch".
|
|
45
|
+
* E. `declared-path-gone`, `declared-path-modified`,
|
|
46
|
+
* `undeclared-path-under-root` — **3**. All three COMPLETED their observation:
|
|
47
|
+
* a declared path is absent or edited, or the listing succeeded and found a
|
|
48
|
+
* file under a declared root that the declaration does not name. Together they
|
|
49
|
+
* are the only codes that may say the tree and the declaration disagree — which
|
|
50
|
+
* is why they are a LIST and not the `else` arm.
|
|
51
|
+
* F. **0 codes today** — the fail-safe. Anything unrecognised gets a sentence that
|
|
52
|
+
* asserts only what is certain (it parsed and was read). Codes A–E are
|
|
53
|
+
* exhaustive over the 17 the two modules emit, so this arm is unreachable now;
|
|
54
|
+
* it exists so a NEW code cannot inherit an observation it did not make, which
|
|
55
|
+
* is the failure this comment records four times.
|
|
56
|
+
*
|
|
57
|
+
* A producer reads this in a refusal, so the classes are the ACTIONS, not the codes:
|
|
58
|
+
* write the block, make the path readable, or re-run the producer.
|
|
59
|
+
*/
|
|
60
|
+
/** The codes that completed a tree observation, and so may say the tree disagrees. */
|
|
61
|
+
const OBSERVED_DISAGREEMENT = new Set([
|
|
62
|
+
'declared-path-gone',
|
|
63
|
+
'declared-path-modified',
|
|
64
|
+
'undeclared-path-under-root'
|
|
65
|
+
]);
|
|
66
|
+
export function describeJudgedRefusal(refusal) {
|
|
67
|
+
const where = `Judged declaration ${refusal.code} at ${refusal.path}`;
|
|
68
|
+
if (refusal.code === 'artifact-unreadable') {
|
|
69
|
+
return `${where}: the artifact is present but could not be read, so its \`${JUDGED_HEADING}\` declaration is unverified`;
|
|
70
|
+
}
|
|
71
|
+
if (refusal.code === 'declared-path-unreadable') {
|
|
72
|
+
return `${where}: the declaration is present and parses, but a path it names is present and unreadable, so its hash is unknown — make that path readable; re-running the producer hashes the same path and refuses identically`;
|
|
73
|
+
}
|
|
74
|
+
if (refusal.code === 'root-listing-failed') {
|
|
75
|
+
return `${where}: the declaration is present and parses and names this as a root, but the root could not be listed, so no file under it was compared — re-run the producer, which declares no roots`;
|
|
76
|
+
}
|
|
77
|
+
if (refusal.code.startsWith('declaration-')) {
|
|
78
|
+
return `${where}: the artifact is present; what is unmet is its \`${JUDGED_HEADING}\` block, absent or not one this check can accept`;
|
|
79
|
+
}
|
|
80
|
+
if (OBSERVED_DISAGREEMENT.has(refusal.code)) {
|
|
81
|
+
return `${where}: the declaration was read and the tree compared against it, and the two do not agree — re-run the producer`;
|
|
82
|
+
}
|
|
83
|
+
return `${where}: the declaration is present and parses; this code records no comparison this check completed, so treat the tree as unverified and re-run the producer`;
|
|
84
|
+
}
|
|
85
|
+
/** Where the security audit artifact may live, newest tier first. */
|
|
86
|
+
export function securityArtifactTiers(rid) {
|
|
87
|
+
return [
|
|
88
|
+
`audit/security-${rid}.md`,
|
|
89
|
+
'audit/security.md',
|
|
90
|
+
`rd/security-review-${rid}.md`,
|
|
91
|
+
'rd/security-review.md'
|
|
92
|
+
];
|
|
93
|
+
}
|
|
94
|
+
export function resolveSecurityArtifact(projectRoot, sessionId, rid) {
|
|
95
|
+
const root = join(projectRoot, '.peaks', '_runtime', sessionId);
|
|
96
|
+
for (const relative of securityArtifactTiers(rid)) {
|
|
97
|
+
const absolute = join(root, ...relative.split('/'));
|
|
98
|
+
if (existsSync(absolute))
|
|
99
|
+
return { relative, absolute };
|
|
100
|
+
}
|
|
101
|
+
return null;
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* List the files git knows about under a prefix. Fail-closed: a git read that
|
|
105
|
+
* did not happen is reported, never returned as an empty list.
|
|
106
|
+
*/
|
|
107
|
+
export function listTreeFiles(projectRoot, prefix) {
|
|
108
|
+
try {
|
|
109
|
+
const raw = execFileSync('git', ['-C', projectRoot, 'ls-files', '-c', '-o', '--exclude-standard', '--', prefix], { encoding: 'utf8', windowsHide: true });
|
|
110
|
+
const files = raw
|
|
111
|
+
.split(/\r?\n/)
|
|
112
|
+
.map((line) => line.trim())
|
|
113
|
+
.filter((line) => line.length > 0);
|
|
114
|
+
return { ok: true, files };
|
|
115
|
+
}
|
|
116
|
+
catch (error) {
|
|
117
|
+
return { ok: false, detail: error instanceof Error ? error.message : String(error) };
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
function readArtifact(absolute) {
|
|
121
|
+
try {
|
|
122
|
+
return { ok: true, body: readFileSync(absolute, 'utf8') };
|
|
123
|
+
}
|
|
124
|
+
catch (error) {
|
|
125
|
+
return { ok: false, detail: error instanceof Error ? error.message : String(error) };
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
function fileRefusals(input) {
|
|
129
|
+
const refusals = [];
|
|
130
|
+
for (const file of input.files) {
|
|
131
|
+
const hashed = sha256OfFile(join(input.projectRoot, ...file.path.split('/')));
|
|
132
|
+
if (!hashed.ok) {
|
|
133
|
+
refusals.push({
|
|
134
|
+
code: hashed.code === 'missing' ? 'declared-path-gone' : 'declared-path-unreadable',
|
|
135
|
+
artifact: input.artifact,
|
|
136
|
+
path: file.path
|
|
137
|
+
});
|
|
138
|
+
}
|
|
139
|
+
else if (hashed.sha256 !== file.sha256) {
|
|
140
|
+
refusals.push({ code: 'declared-path-modified', artifact: input.artifact, path: file.path });
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
return refusals;
|
|
144
|
+
}
|
|
145
|
+
function rootRefusals(input) {
|
|
146
|
+
const refusals = [];
|
|
147
|
+
for (const root of input.roots) {
|
|
148
|
+
const listed = listTreeFiles(input.projectRoot, root.path);
|
|
149
|
+
if (!listed.ok) {
|
|
150
|
+
refusals.push({ code: 'root-listing-failed', artifact: input.artifact, path: root.path });
|
|
151
|
+
continue;
|
|
152
|
+
}
|
|
153
|
+
for (const found of listed.files) {
|
|
154
|
+
if (input.declared.has(found))
|
|
155
|
+
continue;
|
|
156
|
+
if (found !== root.path && !found.startsWith(`${root.path}/`))
|
|
157
|
+
continue;
|
|
158
|
+
refusals.push({ code: 'undeclared-path-under-root', artifact: input.artifact, path: found });
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
return refusals;
|
|
162
|
+
}
|
|
163
|
+
/** Compare the declaration against the tree. Returns refusals, ordered by path. */
|
|
164
|
+
export function checkDeclarationAgainstTree(input) {
|
|
165
|
+
const refusals = [
|
|
166
|
+
...fileRefusals({ ...input, files: input.declaration.files }),
|
|
167
|
+
...rootRefusals({
|
|
168
|
+
...input,
|
|
169
|
+
roots: input.declaration.roots,
|
|
170
|
+
declared: new Set(input.declaration.files.map((f) => f.path))
|
|
171
|
+
})
|
|
172
|
+
];
|
|
173
|
+
return refusals.sort((a, b) => (a.path < b.path ? -1 : 1));
|
|
174
|
+
}
|
|
175
|
+
/**
|
|
176
|
+
* Entry point for the transition gate. An artifact that is not there is not
|
|
177
|
+
* this check's business — the artifact-existence prerequisite owns that.
|
|
178
|
+
*
|
|
179
|
+
* LIMIT, measured rather than assumed — the hole that survives is COMPLETENESS,
|
|
180
|
+
* not tampering: the declaration is the producer's own statement, so ten files
|
|
181
|
+
* touched and one declared passes. Nothing here can know what the producer did
|
|
182
|
+
* not say. Rule: a declaration is a claim about the paths it names, never a
|
|
183
|
+
* claim that those are all the paths.
|
|
184
|
+
*
|
|
185
|
+
* Absence rule, stated where the producer reads it, and the reason it is this
|
|
186
|
+
* blunt: a security artifact that IS there must carry a declaration. No section
|
|
187
|
+
* of the artifact turns the check off, because a requirement that any section
|
|
188
|
+
* can switch off is not a requirement — an earlier draft of this file keyed the
|
|
189
|
+
* requirement on a marker line in the coverage block, and deleting that block
|
|
190
|
+
* (while keeping the declaration, and then rewriting a declared path) passed.
|
|
191
|
+
* The cost is stated rather than hidden: an artifact written before this change
|
|
192
|
+
* is refused until the audit is re-run, and the gate only fires on a
|
|
193
|
+
* transition, so nothing already committed is affected.
|
|
194
|
+
*/
|
|
195
|
+
export function verifyJudgedDeclaration(input) {
|
|
196
|
+
const resolved = resolveSecurityArtifact(input.projectRoot, input.sessionId, input.requestId);
|
|
197
|
+
if (resolved === null)
|
|
198
|
+
return { refusals: [], checked: 0 };
|
|
199
|
+
const artifact = resolved.relative;
|
|
200
|
+
const read = readArtifact(resolved.absolute);
|
|
201
|
+
if (!read.ok) {
|
|
202
|
+
return { refusals: [{ code: 'artifact-unreadable', artifact, path: artifact }], checked: 0 };
|
|
203
|
+
}
|
|
204
|
+
const parsed = parseJudgedDeclaration(read.body);
|
|
205
|
+
if (!parsed.ok) {
|
|
206
|
+
// The refusal no section can switch off: the declaration is missing, or it
|
|
207
|
+
// does not parse to the grammar.
|
|
208
|
+
return { refusals: [{ code: parsed.code, artifact, path: artifact }], checked: 0 };
|
|
209
|
+
}
|
|
210
|
+
const refusals = checkDeclarationAgainstTree({
|
|
211
|
+
projectRoot: input.projectRoot,
|
|
212
|
+
artifact,
|
|
213
|
+
declaration: parsed.declaration
|
|
214
|
+
});
|
|
215
|
+
return { refusals, checked: parsed.declaration.files.length };
|
|
216
|
+
}
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The machine-readable declaration of what an audit judged.
|
|
3
|
+
*
|
|
4
|
+
* `## Red-line scope` in the RD request is prose for a human and is read by no
|
|
5
|
+
* machine here. The declaration is the only machine-read statement of a
|
|
6
|
+
* slice's surface, and the producer that emits the artifact writes it, so a
|
|
7
|
+
* caller cannot produce the artifact without one.
|
|
8
|
+
*
|
|
9
|
+
* Grammar — exactly one fenced json block under the heading `## Judged content`:
|
|
10
|
+
*
|
|
11
|
+
* ## Judged content
|
|
12
|
+
*
|
|
13
|
+
* ```json
|
|
14
|
+
* {"schemaVersion":1,"judgedAt":"2026-10-13T00:00:00.000Z","handoffHash":"unknown",
|
|
15
|
+
* "files":[{"path":"src/a.ts","sha256":"<64 hex>"}],
|
|
16
|
+
* "roots":[{"path":"src/dir","why":"<text>"}]}
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* Rules. No backslash anywhere in the block: JSON resolves an escaped spelling
|
|
20
|
+
* to the same string, so a raw reader and a parsing reader could disagree about
|
|
21
|
+
* what was declared. A `path` is a relative POSIX path with no `..` and no
|
|
22
|
+
* leading slash; `files` is non-empty; a duplicate path is refused. A root
|
|
23
|
+
* entry must carry a non-empty `why` — a bare directory root is refused.
|
|
24
|
+
*
|
|
25
|
+
* LIMIT, recorded rather than fixed: any rule keyed on a self-reported field is
|
|
26
|
+
* closed against accidental shedding, and not against a producer that rewrites
|
|
27
|
+
* its own field.
|
|
28
|
+
*/
|
|
29
|
+
export declare const JUDGED_HEADING = "## Judged content";
|
|
30
|
+
export declare const JUDGED_SCHEMA_VERSION = 1;
|
|
31
|
+
export type JudgedFile = {
|
|
32
|
+
readonly path: string;
|
|
33
|
+
readonly sha256: string;
|
|
34
|
+
};
|
|
35
|
+
export type JudgedRoot = {
|
|
36
|
+
readonly path: string;
|
|
37
|
+
readonly why: string;
|
|
38
|
+
};
|
|
39
|
+
export type JudgedDeclaration = {
|
|
40
|
+
readonly schemaVersion: number;
|
|
41
|
+
readonly judgedAt: string;
|
|
42
|
+
readonly handoffHash: string;
|
|
43
|
+
readonly files: readonly JudgedFile[];
|
|
44
|
+
readonly roots: readonly JudgedRoot[];
|
|
45
|
+
};
|
|
46
|
+
export type JudgedParseFailure = {
|
|
47
|
+
readonly ok: false;
|
|
48
|
+
readonly code: string;
|
|
49
|
+
readonly detail: string;
|
|
50
|
+
};
|
|
51
|
+
export type JudgedParseResult = {
|
|
52
|
+
readonly ok: true;
|
|
53
|
+
readonly declaration: JudgedDeclaration;
|
|
54
|
+
} | JudgedParseFailure;
|
|
55
|
+
/**
|
|
56
|
+
* The audit service's detect result when the declaration cannot be built. It
|
|
57
|
+
* lives here so the producer can substitute it for the probe's verdict without
|
|
58
|
+
* growing the service's own branch count.
|
|
59
|
+
*/
|
|
60
|
+
export declare function declarationMissingDetect(detect: {
|
|
61
|
+
readonly handoffPresent: boolean;
|
|
62
|
+
readonly templatePresent: boolean;
|
|
63
|
+
}, failure: JudgedParseFailure): {
|
|
64
|
+
readonly state: 'declaration-missing';
|
|
65
|
+
readonly handoffPresent: boolean;
|
|
66
|
+
readonly templatePresent: boolean;
|
|
67
|
+
readonly warnings: readonly string[];
|
|
68
|
+
readonly nextActions: readonly string[];
|
|
69
|
+
};
|
|
70
|
+
export type Sha256Result = {
|
|
71
|
+
readonly ok: true;
|
|
72
|
+
readonly sha256: string;
|
|
73
|
+
} | {
|
|
74
|
+
readonly ok: false;
|
|
75
|
+
readonly code: 'missing' | 'unreadable';
|
|
76
|
+
readonly detail: string;
|
|
77
|
+
};
|
|
78
|
+
/** Hash the bytes of one file. A missing file is reported, never guessed. */
|
|
79
|
+
export declare function sha256OfFile(absPath: string): Sha256Result;
|
|
80
|
+
/** A declared path is a relative POSIX path pointing at one file. */
|
|
81
|
+
export declare function validateDeclaredPath(raw: unknown): {
|
|
82
|
+
ok: true;
|
|
83
|
+
path: string;
|
|
84
|
+
} | {
|
|
85
|
+
ok: false;
|
|
86
|
+
detail: string;
|
|
87
|
+
};
|
|
88
|
+
/** Render the declaration as the artifact section the check reads back. */
|
|
89
|
+
export declare function renderJudgedDeclaration(declaration: JudgedDeclaration): string;
|
|
90
|
+
/**
|
|
91
|
+
* Parse the declaration out of an artifact body. Strict on shape: a block that
|
|
92
|
+
* parses to something other than the grammar is a refusal, never a default.
|
|
93
|
+
*/
|
|
94
|
+
export declare function parseJudgedDeclaration(body: string): JudgedParseResult;
|