GHCP -- Run: Ex1 Repo Orientation and Architecture Map

.copilot-track/crawl/README.md

@@ -0,0 +1,55 @@
+# Copilot Track – Crawl Phase
+
+This directory holds prompts, notes, and artifacts for the **Crawl** phase of the AI-assisted development track.
+
+---
+
+## What is the Crawl Phase?
+
+The track is structured as **Crawl → Walk → Run**:
+
+| Phase | Goal |
+|-------|------|
+| **Crawl** | Understand the codebase; establish conventions and tooling; low-risk changes. |
+| **Walk** | Implement features or fixes with AI assistance; write and verify tests. |
+| **Run** | Automate review, generation, and refactoring patterns at scale. |
+
+---
+
+## Chain-PRs
+
+Each exercise produces a **small, focused pull request** that builds on the previous one:
+
+1. Keep PRs scoped – one exercise per PR.
+2. Later PRs branch from the previous exercise branch so reviewers see incremental diffs.
+3. The PR description must include the **exercise number** and link to any relevant prompt file here.
+
+---
+
+## Evidence in PRs
+
+Every PR that uses AI assistance should include an **"AI Evidence" section** in the description:
+
+```
+## AI Evidence
+- Prompt file: `.copilot-track/crawl/<prompt-file>.md`
+- Model: GitHub Copilot / Claude Sonnet 4.6
+- What was generated vs. what was edited manually
+- Test output (paste or screenshot)
+```
+
+This creates an auditable record of what the AI produced and what humans reviewed.
+
+---
+
+## Prompt Usage
+
+Store reusable prompts as `.md` files in this directory.  
+Name them descriptively: `explore-cli-entrypoint.md`, `generate-unit-test.md`, etc.
+
+**Tips:**
+
+- Start prompts with a clear **role** and **goal** sentence.
+- Provide relevant file paths so Copilot has context.
+- Append `// verify before committing` comments to any AI-generated code blocks.
+- Iterate: refine the prompt and re-run rather than hand-editing generated output until you understand why it was wrong.

.github/workflows/contract-rollout-validation.yml

@@ -0,0 +1,34 @@
+permissions:
+  contents: read
+
+name: Contract - Rollout Validation
+
+on:
+  pull_request:
+    paths:
+      - 'components/main-chef-wrapper/cmd/push.go'
+      - 'components/main-chef-wrapper/cmd/push_contract_test.go'
+      - '.github/workflows/contract-rollout-validation.yml'
+  push:
+    paths:
+      - 'components/main-chef-wrapper/cmd/push.go'
+      - 'components/main-chef-wrapper/cmd/push_contract_test.go'
+      - '.github/workflows/contract-rollout-validation.yml'
+
+jobs:
+  rollout-contract-test:
+    name: Rollout env contract
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: components/main-chef-wrapper
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: components/main-chef-wrapper/go.mod
+
+      - name: Run rollout contract test
+        run: go test -tags=unit ./cmd -run TestValidateRolloutSetupContract -count=1 -v

.github/workflows/feature-flag-structured-logs.yml

@@ -0,0 +1,46 @@
+permissions:
+  contents: read
+
+name: Feature Flag Validation - Structured Logs
+
+on:
+  pull_request:
+    paths:
+      - 'components/chef-automate-collect/commands/cli_io.go'
+      - 'components/chef-automate-collect/commands/cli_io_test.go'
+      - 'components/chef-automate-collect/commands/environment_variables.go'
+      - '.github/workflows/feature-flag-structured-logs.yml'
+      - 'ai-track-docs/logging.md'
+  push:
+    branches: [ main ]
+    paths:
+      - 'components/chef-automate-collect/commands/cli_io.go'
+      - 'components/chef-automate-collect/commands/cli_io_test.go'
+      - 'components/chef-automate-collect/commands/environment_variables.go'
+      - '.github/workflows/feature-flag-structured-logs.yml'
+      - 'ai-track-docs/logging.md'
+
+jobs:
+  structured-logs-flag-on-off:
+    name: Structured logs flag=${{ matrix.structured_logs }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        structured_logs: ["true", "false"]
+    env:
+      CHEF_AC_STRUCTURED_LOGS: ${{ matrix.structured_logs }}
+    defaults:
+      run:
+        working-directory: components/chef-automate-collect
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          # Tests use io.ReadAll (1.16+), t.Setenv (1.17+), b.Loop (1.24+);
+          # pin to a modern toolchain regardless of go.mod minimum.
+          go-version: '1.26.x'
+
+      - name: Validate structured logging behavior for flag mode
+        run: go test ./commands -run TestStructuredVerboseHonorsProcessEnvToggle -count=1 -v

.github/workflows/refresh-diagram.yml

@@ -0,0 +1,31 @@
+permissions:
+  contents: read
+
+name: Architecture Diagram Refresh
+
+on:
+  pull_request:
+    paths:
+      - 'components/**/*.go'
+      - 'scripts/refresh-diagram.sh'
+      - 'ai-track-docs/architecture.mmd'
+      - '.github/workflows/refresh-diagram.yml'
+
+jobs:
+  diagram-drift-check:
+    name: Diagram drift check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run diagram refresh / drift check
+        id: drift
+        run: |
+          bash scripts/refresh-diagram.sh | tee /tmp/drift-report.txt
+
+      - name: Post drift report to job summary
+        if: always()
+        run: |
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          cat /tmp/drift-report.txt >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"

.github/workflows/secret-scan.yml

@@ -0,0 +1,28 @@
+permissions:
+  contents: read
+
+name: Secret Scan
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  gitleaks:
+    name: Gitleaks workspace scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install gitleaks CLI
+        run: |
+          set -euo pipefail
+          version="8.30.1"
+          curl -sSL "https://github.com/gitleaks/gitleaks/releases/download/v${version}/gitleaks_${version}_linux_x64.tar.gz" -o /tmp/gitleaks.tgz
+          tar -xzf /tmp/gitleaks.tgz -C /tmp
+          chmod +x /tmp/gitleaks
+          echo "/tmp" >> "$GITHUB_PATH"
+
+      - name: Run gitleaks
+        run: gitleaks detect --source . --no-git --config .gitleaks.toml --redact --verbose

.github/workflows/soft-evidence-summary.yml

@@ -0,0 +1,65 @@
+permissions:
+  contents: read
+
+name: CI Soft Evidence Summary
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  soft-coverage-summary:
+    name: Soft coverage summary (advisory)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: components/main-chef-wrapper/go.mod
+
+      - name: Collect coverage evidence (non-blocking)
+        shell: bash
+        run: |
+          set +e
+
+          output="$(cd components/main-chef-wrapper && go test -tags=unit -cover -count=1 ./cmd 2>&1)"
+          cmd_exit=$?
+
+          coverage="$(printf "%s\n" "$output" | sed -n 's/.*coverage: \([0-9.]*%\) of statements.*/\1/p' | tail -1)"
+          if [[ -z "$coverage" ]]; then
+            coverage="N/A"
+          fi
+
+          if [[ $cmd_exit -eq 0 ]]; then
+            status="PASS"
+          else
+            status="SOFT-FAIL"
+          fi
+
+          {
+            echo "## Soft Gate Evidence"
+            echo
+            echo "| Metric | Value |"
+            echo "|--------|-------|"
+            echo "| Validation | main-chef-wrapper unit coverage |"
+            echo "| Status | ${status} (advisory) |"
+            echo "| Coverage | ${coverage} |"
+            echo "| Command | \`cd components/main-chef-wrapper && go test -tags=unit -cover -count=1 ./cmd\` |"
+            echo
+            echo "This job is intentionally non-blocking and provides evidence only."
+            echo
+            echo "### Command Output"
+            echo '```text'
+            printf "%s\n" "$output"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+          echo "=== SOFT GATE SUMMARY ==="
+          echo "status=${status} coverage=${coverage}"
+          printf "%s\n" "$output"
+
+          # Always succeed: this is advisory-only by design.
+          exit 0

.github/workflows/validate-diagram.yml

@@ -0,0 +1,34 @@
+permissions:
+  contents: read
+
+name: Validate Architecture Diagram
+
+on:
+  push:
+    branches: main
+    paths:
+      - 'ai-track-docs/architecture.mmd'
+      - 'scripts/validate-diagram.sh'
+  pull_request:
+    branches: main
+    paths:
+      - 'ai-track-docs/architecture.mmd'
+      - 'scripts/validate-diagram.sh'
+
+jobs:
+  validate-diagram:
+    name: Mermaid diagram validation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Mermaid CLI
+        run: npm install -g @mermaid-js/mermaid-cli
+
+      - name: Validate diagram
+        run: bash scripts/validate-diagram.sh

.gitignore

@@ -2,11 +2,25 @@
 test_results/
 tags
 .DS_Store
+coverage.out
+coverage.html
 
 # ruby / bundler
 Gemfile.lock
 */vendor/*
 
+# local secrets and credentials
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.p12
+*.pfx
+.netrc
+secrets.yml
+secrets.local.yml
+
 # vi
 *.swp
 

.gitleaks.toml

@@ -0,0 +1,13 @@
+title = "chef-workstation gitleaks config"
+
+[extend]
+useDefault = true
+
+[[allowlists]]
+description = "Known non-production licensing API key fixture used for workstation licensing acceptance tests"
+paths = [
+  '''components/main-chef-wrapper/dist/licensingConfig.json''',
+]
+regexes = [
+  '''yDblv75Xt84wULmc8qTM88a3Dr2OuuKxa6GDXxH5''',
+]