yam-flow 2.7.0 → 2.8.1

package/src/lib/trust-kernel.ts

@@ -1,4 +1,6 @@
 import { verifyStrictGateResult } from './gate-result.js';
+import { buildNextStep } from './next-step.js';
+import type { NextStepInput, NextStepReceipt } from './next-step.js';
 
 export const TRUTH_STATUSES = Object.freeze([
   'verified',
@@ -273,6 +275,7 @@ export interface LoopReport {
   side_effects: string[];
   avoidance_note: string;
   study_note: StudyNote;
+  next_step: NextStepReceipt | null;
 }
 
 export interface UeyeRunReport {
@@ -784,13 +787,32 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
   const uncoveredRequirements = asList(input.uncovered_requirements || input.uncovered_requirement);
   const blockers = asList(input.blockers || input.blocked);
   const blockedBy = asList(input.blocked_by);
-  const blockedKind = shortText(input.blocked_kind || (readinessState === 'blocked' ? 'readiness_blocked' : uncoveredRequirements.length ? 'requirement_uncovered' : blockers.length || blockedBy.length ? 'evidence_missing' : ''));
+  const requestedBlockedKind = shortText(input.blocked_kind);
   const failureCause = shortText(input.failure_cause);
   const recoveryHint = shortText(input.recovery_hint);
   const avoidanceNote = shortText(input.avoidance_note);
   const evidenceStamp = shortText(input.evidence_stamp || input.source_digest, 320);
   const sourceDigest = shortText(input.source_digest || input.evidence_stamp, 320);
   const hasBlockedStage = stages.some((stage) => stage.status === 'blocked' || stage.status === 'failed');
+  const nextStepSupplied = input.next_step !== undefined && input.next_step !== null;
+  const nextStep = nextStepSupplied ? buildNextStep(input.next_step as unknown as NextStepInput) : null;
+  const nextStepRequired = touchedFiles.length > 0;
+  const nextStepBlocked = (nextStepRequired && !nextStep)
+    || Boolean(nextStep && (!nextStep.contract_valid || nextStep.truth_status === 'blocked'));
+  if (nextStepBlocked) {
+    blockers.push(!nextStep
+      ? 'next_step_missing_for_changed_artifacts'
+      : `next_step_contract_blocked: ${nextStep.contract_errors[0] || nextStep.truth_status}`);
+  }
+  const blockedKind = shortText(requestedBlockedKind || (
+    readinessState === 'blocked'
+      ? 'readiness_blocked'
+      : uncoveredRequirements.length
+        ? 'requirement_uncovered'
+        : blockers.length || blockedBy.length
+          ? 'evidence_missing'
+          : ''
+  ));
   const hasBlockerSignal = Boolean(blockers.length || blockedBy.length || blockedKind || uncoveredRequirements.length || readinessState === 'blocked');
   const requestedTruth = isTruthStatus(input.truth_status) ? input.truth_status : '';
   const derivedTruth: TruthStatus = hasBlockerSignal || hasBlockedStage ? 'blocked'
@@ -844,7 +866,8 @@ export function buildLoopReport(input: Partial<LoopReport> & Record<string, unkn
     scope_owner: normalizeOwnerRoute(input.scope_owner || input.owner),
     side_effects: asList(input.side_effects || input.side_effect),
     avoidance_note: avoidanceNote,
-    study_note: studyNote
+    study_note: studyNote,
+    next_step: nextStep
   };
 }
 

package/templates/security-check-note.md

@@ -0,0 +1,42 @@
+# Yam note security-check starter
+
+Copy the block below into the project's Yam note for each run. Replace every placeholder with actual scope/evidence; do not infer a pass from the template. The authoritative status and gate rules are in [Security check contract v1](../references/security-check.md).
+
+```text
+-- Security check --
+
+Contract: security-check-v1
+Run: <unique run ID>; Time: <ISO timestamp with timezone>
+Stage: <commit | push | deploy>; Policy: <stage-policy version>
+Environment: <target environment or explicit local/not-applicable reason>
+Binding: <commit: staged tree and base revision | push: outgoing commit IDs and destination | deploy: artifact digest, source commit, environment and configuration revision>
+Scope: <changed paths and connected security boundaries>
+Checker: <tool/version or named reviewer>; Evidence: <sanitized evidence references>
+
+1. SEC-01 : "사용자·관리자·외부 서비스·DB·파일 사이의 신뢰 경계와 보호할 데이터·작업을 식별한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+2. SEC-02 : "명시적으로 허용한 접근만 열고, 사용자·서비스 계정에 필요한 최소 권한만 부여한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+3. SEC-03 : "화면을 우회한 API·서버 함수·DB·파일·백그라운드 작업에서도 사용자·조직·대상별 권한을 확인한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+4. SEC-04 : "계정 정지·승인 철회·탈퇴·소속 변경 후 기존 세션·토큰·캐시에서도 권한 회수가 반영된다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+5. SEC-05 : "코드의 보안 정책·migration·ACL·환경 설정이 대상 배포 환경의 실제 상태와 일치한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+6. SEC-06 : "로그인·관리자 인증·세션 만료·로그아웃·비밀번호 재설정·계정 복구가 계정 탈취를 막도록 동작한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+7. SEC-07 : "외부 입력·파일 업로드·출력의 형식·크기·경로를 검증하고 SQL 주입·XSS·SSRF·CSRF 등 해당 공격을 방어한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+8. SEC-08 : "API 키·토큰·개인키·개인정보가 코드·브라우저 번들·로그·점검 기록에 불필요하게 노출되지 않는다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+9. SEC-09 : "의존성·CI/CD 권한·배포 자격증명·릴리스 산출물의 출처와 무결성을 확인해 공급망 위험을 통제한다." : 미검증
+   - Required at: <stages>; Target/evidence/result/time: <actual check details or missing evidence>
+
+Result: BLOCKED
+Blocking: <required-at-current-stage unresolved IDs/subchecks or invalid record fields>
+Deferred: <later-stage missing evidence, required stage, owner and action; none if absent>
+Retry of: <prior run ID or none>
+-- End Security check --
+```
+
+For `점검 완료 - 보완 필요` or `점검 실패`, add a concrete finding, severity, owner, follow-up action/date and mitigation. For `해당 없음`, add a project/stage-specific reason. Keep missing evidence as `미검증`. All applicable conditional subchecks must appear in the details; one passing test cannot cover an untested requirement.

package/templates/security-gate.yml

@@ -0,0 +1,44 @@
+# Copy to the target project after configuring trusted repository variables.
+# Require this job in branch protection and make deployment jobs depend on it.
+name: Security check
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: 22.14.0
+      # The caller provisions reviewed yam code, policy and evidence before this step.
+      # Do not execute PR-supplied code with deployment credentials.
+      - name: Validate security evidence for exact revisions
+        env:
+          SECURITY_POLICY_DIGEST: ${{ vars.SECURITY_POLICY_DIGEST }}
+          SECURITY_SOURCE: ${{ github.event.pull_request.head.sha || github.sha }}
+          SECURITY_BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
+        run: >-
+          node /opt/trusted-yam/dist/bin/yam.js security check
+          --stage ci --source "$SECURITY_SOURCE" --base "$SECURITY_BASE"
+          --policy security/policy.json --policy-digest "$SECURITY_POLICY_DIGEST"
+          --evidence security/check.json --json
+      - name: Preserve sanitized security notes on success and failure
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: security-check-note
+          include-hidden-files: true
+          path: |
+            .yam/security/notes.md
+            .yam/security/runs/
+          retention-days: 14
+          if-no-files-found: error

package/yam.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "yam",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "principles": [
     "Direction before execution.",
     "Start fast.",
@@ -17,7 +17,8 @@
     "Explain what changed, what role it has, where it runs or is read, what was wrong or missing when relevant, before/after behavior, expected behavior, and one useful syntax or structure insight in short non-specialist language.",
     "When relevant, include architecture hygiene: avoid dumping unrelated logic into page.tsx, one-off component CSS into global.css, or structured product data into broad DB jsonb blobs when better project boundaries exist.",
     "Use handoff notes for fix-first items, remaining tasks, recommended next direction, requirement coverage, blocker kind, failure cause, recovery hint, safe retry, evidence level, and owner scope when useful.",
-    "Use bounded heavy verification for serious claims, with explicit stop conditions instead of endless proof loops."
+    "Use bounded heavy verification for serious claims, with explicit stop conditions instead of endless proof loops.",
+    "After changed artifacts, put an evidence-bound Next step immediately after Study Note with a whole-process scan, critical opinion, recommendations, and fix-first-before-planned ordering."
   ],
   "defaultHooks": false,
   "routes": [
@@ -39,7 +40,7 @@
     {
       "id": "scout",
       "stage": "v0.2",
-      "purpose": "Investigation, wide search, evidence-led source mapping, blocked-source fallback, opposition pass, and recommendation without code changes by default."
+      "purpose": "Investigation, canonical-entity resolution, four-clock freshness checks, evidence-led source mapping, blocked-source fallback, immutable source/claim receipts for repeated scans, opposition pass, and recommendation without code changes by default."
     },
     {
       "id": "deep",