feat: add completed test artifacts, minimal code, and tests

.github/CODEOWNERS

@@ -0,0 +1,14 @@
+*                 @MichaelsEngineering
+.github/**       @MichaelsEngineering
+plans/**         @MichaelsEngineering
+scripts/agent-orchestrator/** @MichaelsEngineering
+src/**           @MichaelsEngineering
+tests/**         @MichaelsEngineering
+traces/**        @MichaelsEngineering
+runs/**          @MichaelsEngineering
+dev/**           @MichaelsEngineering
+AGENTS.md        @MichaelsEngineering
+README.md        @MichaelsEngineering
+Makefile         @MichaelsEngineering
+pyproject.toml   @MichaelsEngineering
+LICENSE          @MichaelsEngineering

.github/ISSUE_TEMPLATE/bug_feature_report.md

@@ -0,0 +1,106 @@
+---
+name: "🐞/✨ Bug Report / Feature Request"
+about: Report a bug or suggest a new feature
+title: " "
+labels: ["bug", "enhancement"]
+assignees: ""
+---
+
+## Header
+
+- **Type**: Bug / Feature / Improvement
+- **Title**: _(Short summary)_
+
+---
+
+## Description
+Provide a clear and concise description of the issue or requested capability.
+
+---
+
+## Background & Context
+Where this occurs / why it matters / user type / business impact.
+
+---
+
+## For Bugs: Reproduction Steps
+(If Type = Bug)
+1. Step 1: _(what you did)_
+2. Step 2: _(what you did next)_
+3. …
+**Expected behavior**:
+_(What you expected to happen)_
+**Actual behavior**:
+_(What actually happened)_
+**Environment / version / configuration**:
+- Product version:
+- Platform (OS / browser / device):
+- Any special setup:
+**Attachments / logs / screenshots**:
+_(Links or embed if supported)_
+
+---
+
+## For Features: Proposal
+(If Type = Feature or Improvement)
+- **What is the request?**
+_(Describe the new capability or change)_
+- **Why is it needed?**
+_(User pain, business value, user type)_
+- **User scenario / Use-case**:
+_(“When user X does Y, they want Z”)_
+- **Acceptance criteria / Success metrics**:
+_(How will you know if it’s done / valuable?)_
+- **Alternatives considered**:
+_(If you know other options or workarounds)_
+- **Priority / Urgency**:
+_(Low / Medium / High)_
+
+---
+
+## Impact & Scope
+- **Affected users / segments**:
+- **Frequency or severity** (bugs) / **Reach & benefit** (features):
+- **Dependencies or related issues**:
+- **Estimated effort / complexity** (optional, dev can fill):
+
+---
+
+## Notes for the Dev / Product Team (Optional)
+- **Suggested implementation approach** (optional):
+- **Workarounds currently in use**:
+- **Additional comments**:
+
+---
+
+## Prompt-Engineering Note
+When converting to a Codex-style prompt for generation or summarization, you might use:
+
+analyze current prompt_guide.txt:
+Task:
+
+Context:
+- Files:
+- Logs / stack trace:
+- Constraints:
+
+Verify:
+- Run:
+- Expect:
+
+Output:
+-
+
+Task:
+
+Context:
+- Files:
+- Logs / stack trace:
+- Constraints:
+
+Verify:
+- Run:
+- Expect:
+
+Output:
+-

.github/dependabot.yml

@@ -0,0 +1,51 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:00"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "security"
+    assignees:
+      - "MichaelsEngineering"
+    reviewers:
+      - "MichaelsEngineering"
+    groups:
+      python-security:
+        applies-to: security-updates
+        patterns:
+          - "*"
+      python-routine:
+        applies-to: version-updates
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "03:15"
+      timezone: "UTC"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "security"
+    assignees:
+      - "MichaelsEngineering"
+    reviewers:
+      - "MichaelsEngineering"
+    groups:
+      actions-security:
+        applies-to: security-updates
+        patterns:
+          - "*"
+      actions-routine:
+        applies-to: version-updates
+        patterns:
+          - "*"

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+### What
+
+-
+
+### Why
+
+-
+
+### How
+
+-
+
+### Checks
+
+- [x] `make check` passes locally
+- [ ] Added/updated tests
+- [ ] Docs or README updated if needed
+- [ ] Security impact assessed (`none` or brief rationale provided below)
+- [ ] Dependency and lockfile changes explicitly listed
+- [ ] Supply-chain provenance updated (SBOM/attestation artifacts linked when applicable)
+- [ ] Threat-model delta captured for behavior/config changes
+- [ ] Rollback plan included for this change
+- [ ] Confirmed no new network/time/nondeterministic sources in core loop paths (`src/runner.py`, `src/replay.py`, `src/replay_fixtures.py`)
+
+### Security Notes
+
+- Security impact:
+- Dependency or lockfile changes:
+- Threat-model delta:
+- Rollback plan:

.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - name: Setup Python 3.11
+        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        run: python -m pip install --upgrade pip uv
+      - name: Sync dependencies
+        run: uv sync --dev
+      - name: Run check
+        run: uv run make check
+
+  gate:
+    name: gate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - name: Setup Python 3.11
+        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        run: python -m pip install --upgrade pip uv
+      - name: Sync dependencies
+        run: uv sync --dev
+      - name: Run deterministic gate
+        run: uv run make gate
+
+  smoke:
+    name: smoke
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - name: Setup Python 3.11
+        uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d
+        with:
+          python-version: "3.11"
+      - name: Install uv
+        run: python -m pip install --upgrade pip uv
+      - name: Sync dependencies
+        run: uv sync --dev
+      - name: Run smoke test
+        run: uv run make smoke

.github/workflows/codeql.yml

@@ -0,0 +1,125 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - ".github/workflows/**"
+      - ".gitignore"
+      - "Makefile"
+      - "dev/**"
+      - "scripts/**"
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - ".github/workflows/**"
+      - ".gitignore"
+      - "Makefile"
+      - "dev/**"
+      - "scripts/**"
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - "uv.lock"
+  schedule:
+    - cron: '24 19 * * 2'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    # Runner size impacts CodeQL analysis time. To learn more, please see:
+    #   - https://gh.io/recommended-hardware-resources-for-running-codeql
+    #   - https://gh.io/supported-runners-and-hardware-resources
+    #   - https://gh.io/using-larger-runners (GitHub.com only)
+    # Consider using larger runners or machines with greater resources for possible analysis time improvements.
+    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: python
+          build-mode: none
+        # CodeQL supports the following values keywords for 'language': 'actions', 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'rust', 'swift'
+        # Use `c-cpp` to analyze code written in C, C++ or both
+        # Use 'java-kotlin' to analyze code written in Java, Kotlin or both
+        # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both
+        # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis,
+        # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning.
+        # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how
+        # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+    # Add any setup steps before running the `github/codeql-action/init` action.
+    # This includes steps like installing compilers or runtimes (`actions/setup-node`
+    # or others). This is typically only required for manual builds.
+    # - name: Setup runtime (example)
+    #   uses: actions/setup-example@v1
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@a60c4df7a135c7317c1e9ddf9b5a9b07a910dda9
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+
+        # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+    # If the analyze step fails for one of the languages you are analyzing with
+    # "We were unable to automatically build your code", modify the matrix above
+    # to set the build mode to "manual" for that language. Then modify this step
+    # to build your code.
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+    - name: Run manual build steps
+      if: matrix.build-mode == 'manual'
+      shell: bash
+      run: |
+        echo 'If you are using a "manual" build mode for one or more of the' \
+          'languages you are analyzing, replace this with the commands to build' \
+          'your code, for example:'
+        echo '  make bootstrap'
+        echo '  make release'
+        exit 1
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@a60c4df7a135c7317c1e9ddf9b5a9b07a910dda9
+      with:
+        category: "/language:${{matrix.language}}"