Showcase: greenfield BEAR baseline review

.bear/ci/README.md

@@ -8,24 +8,24 @@ Files:
 - `baseline-allow.json`: exact-match allow file for approved boundary expansion
 
 Canonical outputs:
-- console summary lines for `MODE`, `CHECK`, and `PR-CHECK`
+- console summary starts with `BEAR Decision: PASS|REVIEW REQUIRED|FAIL|ALLOWED EXPANSION`, followed by the structured `MODE=... DECISION=... BASE=...` line and the `CHECK` / `PR-CHECK` lines
 - optional `ALLOW_ENTRY_CANDIDATE` block on enforce-mode boundary expansion
 - report artifact at `build/bear/ci/bear-ci-report.json`
-- markdown summary at `build/bear/ci/bear-ci-summary.md`
+- markdown summary at `build/bear/ci/bear-ci-summary.md`, using the same `BEAR Decision: ...` header near the top
 - when `GITHUB_STEP_SUMMARY` is set, the wrapper appends the exact markdown summary content there
 
 Canonical usage:
 
 PowerShell:
 
 ```powershell
-.\.bear\ci\bear-gates.ps1 --mode enforce
+.\.bear\ci\bear-gates.ps1 --mode observe
 ```
 
 bash:
 
 ```sh
-./.bear/ci/bear-gates.sh --mode enforce
+./.bear/ci/bear-gates.sh --mode observe
 ```
 
 Options:
@@ -35,11 +35,12 @@ Options:
 
 Rules:
 - wrappers run `check --all` first, then `pr-check --all` when allowed by the pinned decision matrix
+- in `observe`, clean runs report `pass`, boundary expansion reports `review-required`, and blocking repo problems report `fail`
 - `baseline-allow.json` is consulted only for `pr-check` boundary expansion in `enforce`
 - the allow-entry candidate and markdown boundary section use the full boundary-expanding delta set from `pr-check --all` repo-level plus block-level results
 - report and decision output must be reproducible from BEAR raw outputs plus wrapper mode and allow-file state
 
 Runtime note:
 - on bash-based GitHub runners, `bear-gates.sh` requires `pwsh`
 - if `pwsh` is unavailable, `bear-gates.sh` fails deterministically and tells the operator to install PowerShell 7 or run `bear-gates.ps1` directly
-- if local bash cannot launch PowerShell reliably, run `bear-gates.ps1` directly
+- if local bash cannot launch PowerShell reliably, run `bear-gates.ps1` directly

.bear/ci/bear-gates.ps1

@@ -60,6 +60,22 @@ function Get-PropertyValue($object, $name) {
     return $property.Value
 }
 
+function Get-FirstNormalizedValue($value) {
+    if ($null -eq $value) {
+        return $null
+    }
+    if ($value -is [string]) {
+        return [string]$value
+    }
+    foreach ($item in @($value)) {
+        $candidate = [string]$item
+        if (-not [string]::IsNullOrWhiteSpace($candidate)) {
+            return $candidate
+        }
+    }
+    return $null
+}
+
 function Normalize-Lines($text) {
     if ($null -eq $text -or $text.Length -eq 0) {
         return @()
@@ -117,6 +133,82 @@ function Parse-FailureFooter($text, $exitCode) {
     }
 }
 
+function Parse-AgentFailure($agentJson, $exitCode) {
+    if ($exitCode -eq 0) {
+        return [ordered]@{
+            valid = $true
+            code = $null
+            path = $null
+            remediation = $null
+        }
+    }
+    if ($null -eq $agentJson) {
+        return New-InvalidFooter
+    }
+    $nextAction = Get-PropertyValue $agentJson 'nextAction'
+    $primaryClusterId = [string](Get-PropertyValue $nextAction 'primaryClusterId')
+    $clusters = New-OrderedArray (Get-PropertyValue $agentJson 'clusters')
+    $primaryCluster = $null
+    foreach ($cluster in $clusters) {
+        if ([string](Get-PropertyValue $cluster 'clusterId') -eq $primaryClusterId) {
+            $primaryCluster = $cluster
+            break
+        }
+    }
+    if ($null -eq $primaryCluster -and $clusters.Count -gt 0) {
+        $primaryCluster = $clusters[0]
+    }
+    $problems = New-OrderedArray (Get-PropertyValue $agentJson 'problems')
+    $primaryProblem = if ($problems.Count -gt 0) { $problems[0] } else { $null }
+
+    $codeCandidates = @(
+        [string](Get-PropertyValue $primaryCluster 'reasonKey'),
+        [string](Get-PropertyValue $primaryCluster 'ruleId'),
+        [string](Get-PropertyValue $primaryCluster 'failureCode'),
+        [string](Get-PropertyValue $primaryProblem 'reasonKey'),
+        [string](Get-PropertyValue $primaryProblem 'ruleId'),
+        [string](Get-PropertyValue $primaryProblem 'failureCode'),
+        [string](Get-PropertyValue $primaryProblem 'messageKey')
+    )
+    $code = $null
+    foreach ($candidate in $codeCandidates) {
+        if (-not [string]::IsNullOrWhiteSpace($candidate)) {
+            $code = $candidate
+            break
+        }
+    }
+    if ([string]::IsNullOrWhiteSpace($code)) {
+        return New-InvalidFooter
+    }
+
+    $pathCandidates = @(
+        (Get-FirstNormalizedValue (Get-PropertyValue $primaryCluster 'files')),
+        [string](Get-PropertyValue $primaryProblem 'file')
+    )
+    $path = $null
+    foreach ($candidate in $pathCandidates) {
+        if (-not [string]::IsNullOrWhiteSpace($candidate)) {
+            $path = $candidate
+            break
+        }
+    }
+    if ([string]::IsNullOrWhiteSpace($path)) {
+        $path = 'agent.json'
+    }
+
+    $steps = New-OrderedArray (Get-PropertyValue $nextAction 'steps')
+    $remediation = if ($steps.Count -gt 0 -and -not [string]::IsNullOrWhiteSpace([string]$steps[0])) {
+        [string]$steps[0]
+    } else {
+        'Inspect BEAR agent diagnostics and apply the listed next action.'
+    }
+    return [ordered]@{
+        valid = $true
+        code = $code
+        path = $path
+        remediation = $remediation
+    }
+}
 function Try-ParseAgentJson($text) {
     if ([string]::IsNullOrWhiteSpace($text)) {
         return [ordered]@{
@@ -402,15 +494,30 @@ function Get-ClassesDisplay($classes) {
     return ($classes -join ',')
 }
 
+function Get-DecisionHeader($decision) {
+    switch ($decision) {
+        'pass' { return 'BEAR Decision: PASS' }
+        'review-required' { return 'BEAR Decision: REVIEW REQUIRED' }
+        'fail' { return 'BEAR Decision: FAIL' }
+        'allowed-expansion' { return 'BEAR Decision: ALLOWED EXPANSION' }
+        default { return 'BEAR Decision: ' + $decision.ToUpperInvariant() }
+    }
+}
+
 function New-MarkdownSummary($modeValue, $decision, $baseResolution, $checkReport, $prReport, $combinedBoundaryDeltas, $allowEntryCandidate) {
     $baseDisplay = if ($baseResolution.resolved) { $baseResolution.value } else { 'unresolved' }
     $lines = New-Object System.Collections.Generic.List[string]
     $lines.Add('# BEAR CI Governance')
     $lines.Add('')
+    $lines.Add((Get-DecisionHeader $decision))
+    $lines.Add('')
     $lines.Add('- Mode: ' + $modeValue)
     $lines.Add('- Decision: ' + $decision)
     $lines.Add('- Base SHA: ' + $baseDisplay)
     $lines.Add('- Report: build/bear/ci/bear-ci-report.json')
+    if ($decision -eq 'review-required') {
+        $lines.Add('- Review Required: boundary expansion detected.')
+    }
     $lines.Add('')
     $lines.Add('## Check')
     $lines.Add('- Exit: ' + $checkReport.exitCode)
@@ -558,6 +665,9 @@ function Invoke-BearCommand($label, $commandText, $commandPath, $commandArgs) {
     $stderrHash = if (Test-Path $stderrPath) { (Get-FileHash -Algorithm SHA256 $stderrPath).Hash.ToLowerInvariant() } else { $null }
     $agent = Try-ParseAgentJson $stdoutText
     $footer = Parse-FailureFooter $stderrText $exitCode
+    if (-not $footer.valid -and $agent.valid) {
+        $footer = Parse-AgentFailure $agent.json $exitCode
+    }
     return [ordered]@{
         label = $label
         command = $commandText
@@ -622,15 +732,21 @@ try {
     $allowEntryCandidate = Get-AllowEntryCandidate $mode $prResult $prTelemetry $baseResolution.value
 
     $decision = 'pass'
-    if ($checkResult.exitCode -in @(2, 5, 64, 70, 74)) {
+    if ($checkClasses -contains 'CI_INTERNAL_ERROR') {
+        $decision = 'fail'
+    } elseif ($mode -eq 'observe' -and $checkResult.exitCode -in @(2, 3, 4, 5, 6, 7, 64, 70, 74)) {
+        $decision = 'fail'
+    } elseif ($checkResult.exitCode -in @(2, 5, 64, 70, 74)) {
         $decision = 'fail'
     } elseif (-not $baseResolution.resolved) {
         $decision = 'fail'
     } elseif ($null -eq $prResult) {
         $decision = 'fail'
     } elseif ($mode -eq 'observe') {
-        if ($prResult.exitCode -in @(2, 64, 70, 74)) {
+        if (($prClasses -contains 'CI_INTERNAL_ERROR') -or $prResult.exitCode -in @(2, 64, 70, 74)) {
             $decision = 'fail'
+        } elseif ($prResult.exitCode -eq 5) {
+            $decision = 'review-required'
         }
     } elseif ($checkResult.exitCode -ne 0) {
         $decision = 'fail'
@@ -641,7 +757,6 @@ try {
     } else {
         $decision = 'fail'
     }
-
     $checkReport = [ordered]@{
         status = 'ran'
         exitCode = $checkResult.exitCode
@@ -708,6 +823,7 @@ try {
     $baseDisplay = if ($baseResolution.resolved) { $baseResolution.value } else { '<unresolved>' }
     $checkCodeDisplay = Get-CodeDisplay $checkResult.footer.code
     $checkClassesDisplay = Get-ClassesDisplay $checkClasses
+    Write-Output (Get-DecisionHeader $decision)
     Write-Output ('MODE=' + $mode + ' DECISION=' + $decision + ' BASE=' + $baseDisplay)
     Write-Output ('CHECK exit=' + $checkResult.exitCode + ' code=' + $checkCodeDisplay + ' classes=' + $checkClassesDisplay)
     if ($prStatus -eq 'ran') {
@@ -742,3 +858,5 @@ try {
 
 
 
+
+

.github/workflows/pr-gate.yml

@@ -5,6 +5,8 @@ on:
 
 permissions:
   contents: read
+  issues: write
+  pull-requests: write
 
 jobs:
   governance:
@@ -21,9 +23,70 @@ jobs:
           distribution: temurin
           java-version: '21'
 
+      - name: Generate BEAR artifacts
+        run: ./.bear/tools/bear-cli/bin/bear compile --all --project .
+
       - name: Run BEAR governance (observe)
         run: ./.bear/ci/bear-gates.sh --mode observe
 
+      - name: Publish BEAR PR summary
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            const marker = '<!-- bear-ci-governance -->';
+            const reportPath = 'build/bear/ci/bear-ci-report.json';
+            const summaryPath = 'build/bear/ci/bear-ci-summary.md';
+
+            let body = `${marker}\n## BEAR CI\n\nBEAR did not produce its expected CI report. Check the workflow logs.`;
+            if (fs.existsSync(reportPath) && fs.existsSync(summaryPath)) {
+              const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+              const summary = fs.readFileSync(summaryPath, 'utf8').trim();
+              const decision = String(report.decision || 'unknown').toUpperCase().replace(/-/g, ' ');
+              const mode = report.mode || 'unknown';
+              const baseSha = report.resolvedBaseSha || 'unknown';
+              body = [
+                marker,
+                '## BEAR CI',
+                '',
+                `- Decision: \`${decision}\``,
+                `- Mode: \`${mode}\``,
+                `- Base SHA: \`${baseSha}\``,
+                '',
+                '<details><summary>BEAR summary</summary>',
+                '',
+                summary,
+                '',
+                '</details>'
+              ].join('\n');
+            }
+
+            const pr = context.payload.pull_request;
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: pr.number,
+              per_page: 100
+            });
+
+            const existing = comments.find((comment) => comment.user?.type === 'Bot' && comment.body?.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: pr.number,
+                body
+              });
+            }
+
       - name: Upload BEAR CI artifacts
         if: always()
         uses: actions/upload-artifact@v4

AGENTS.md

@@ -1,12 +1,13 @@
-# AGENTS.md (Project Bootstrap)
+# AGENTS.md (Project Bootstrap)
 
 This project uses the BEAR agent profile.
 
 Startup (mandatory):
-1. Read `.bear/agent/BEAR_AGENT.md`.
-2. Follow `.bear/agent/BEAR_AGENT.md` for the full session.
+1. Read `.bear/agent/BOOTSTRAP.md`.
+2. Follow `.bear/agent/BOOTSTRAP.md` for the full session.
 
 Safety (mandatory before cleanup/delete commands):
 1. Read `doc/SAFETY_RULES.md`.
 2. Do not run ad-hoc recursive deletes.
 3. Use `scripts/safe-clean-temp.ps1` for temp cleanup.
+

README.md

@@ -20,8 +20,9 @@ CI demo:
   - `scenario/02-feature-extension -> baseline/greenfield-output`
 
 Product specification:
-- `doc/SPEC.md`
+- `spec/SPEC.md`
 
 Branch context:
-- Branch role: demo main/spec-only base
-- Use this branch as the PR target for the greenfield baseline review.
+- Branch role: greenfield implementation baseline
+- Cut from: `scenario/01-agent-greenfield-implementation`
+- Use this governance base for `pr-check`: `origin/main`