chore: refresh stackchain-hackathon tracking files

2026-07-12 12:11:10 +00:00 · 2026-07-12 12:11:10 +00:00 · 6c359d793a
commit 6c359d793a
4 changed files with 403 additions and 0 deletions
--- a/REPORT.md
+++ b/REPORT.md
@ -0,0 +1,101 @@
+# Agent Engineering Report — 2026-07-08
+
+**Audience:** agent engineers  
+**Status:** Operations active, prototypes shipping, release candidates pending human test only
+
+---
+
+## Current State
+
+**Infra:** Gitea 1.22.0 on VPS, Caddy-free routing  
+**Public URL:** <https://forge.alexanderwhitestone.com/git/>  
+**Org:** [stackchain](https://forge.alexanderwhitestone.com/git/org/stackchain)  
+**Repos:** 4 active (`hackathon`, `dashboard`, `agent-todo-tracker`, `project-template`)  
+**Active users:** 5 (rockachopa, timmy, grepples, john52galt, turdbot) — 4 admins, 1 bot user  
+**Pipeline:** CI + RC workflows in `.gitea/workflows` — pushed and live  
+**Loop:** Issue → PR → review → merge/no-spam; stale 72h / close +24h; velocity in `#Velocity`  
+**Creative agent:** Hou3 profile (Tencent Hy3) active; assigned to #16, #17, #18
+
+---
+
+## Operational Constraints
+
+| Constraint | Rule |
+|---|---|
+| Caddy | No changes for Gitea work |
+| Human touchpoints | Prototype review + RC test only |
+| Config | `ROOT_URL=https://forge.alexanderwhitestone.com/git/` |
+| Assets | `/var/lib/gitea/public/assets/` verified present |
+| Pages API | Returns 404; enablement gated on human config handoff |
+| Cleanup | Dupe users removed, admins promoted |
+
+---
+
+## Queue Snapshot
+
+- **Open issues:** 19 items in `stackchain-hackathon`
+- **P0/P1:** Pages enablement (blocked on human handoff), #8 adaptive UI, #10 context, #11 engine, #12 frontend panels
+- **P2:** #13 cache, #5 agent-todo, #6 scaffolder
+- **Creative:** #16 README, #17 overlays, #18 release notes
+- **Open PRs:** 0
+- **Hou3:** Actively composing deliverable drafts
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Mitigation |
+|---|---|---|
+| Gitea Pages auth | Medium | Surface as explicit handoff in #14; do not block |
+| 8GB RAM exhaustion | Medium | Watchdog + serialize worker starts |
+| Auth drift | Low | Single admin path through Timmy; audit weekly |
+| Workflow drift | Medium | One canonical workflow source |
+| Hou3 spam | Low | Seen-state tracking + max-comment guard |
+
+---
+
+## Market Fit Matrix
+
+| Product | Market Signal | Fit | Build Order |
+|---|---|---|---|
+| Adaptive UI dashboard | Context-aware developer surfaces are emerging category | Strong | P0 |
+| Agent Task Harness | Deterministic multi-agent orchestration is foundational | Strong | P1 |
+| Agent Memory Store | Cross-session memory is table stakes for useful agents | Strong | P1 |
+| PR Review Agent | Automated review reduces human load | Strong | P1 |
+| Repo Scaffolder Agent | NL project generation lowers onboarding friction | Medium | P2 |
+| Hou3 creative pipeline | Launch docs/content automation | Medium | P2 |
+| Kanban-to-issue sync | Single pane of glass | Medium | Wired |
+
+---
+
+## Recommended Sequencing
+
+### Phase A — 0–48h
+1. Ship adaptive dashboard panels from #8–#13
+2. Wire Hou3 output to issues/PRs as real comments
+3. Run first full autonomous cycle: branch, implement, PR, self-review, merge
+
+### Phase B — 48h–2w
+4. Fill test suites in dashboard + agent-todo-tracker
+5. Automate token rotation via cron/Hermes job
+6. Profile memory usage before adding more workers
+
+### Phase C — 2w+
+7. Multi-repo issue queue across `stackchain/*`
+8. Unique staging targets per RC
+9. Separate Hou3 creative queue from code queue
+
+---
+
+## Human Gates (Only Human Actions Needed)
+
+| Human Action | Trigger | What to Do |
+|---|---|---|
+| Prototype review | PR includes preview link | Click, test, comment feedback |
+| RC approval | Automated tests pass, draft release created | Verify locally, merge release PR |
+| Pages handoff | Issue #14 is `blocked` | Enable Gitea Pages in UI; confirm URL |
+| 3 consecutive failed reviews | Auto-pause in loop | Surface in issue, triage, decide path |
+
+---
+
+**One-liner direction:** Ship adaptive UI, prove the loop, harden tests, keep humans on prototype/RC gate only.
--- a/docs/agent-engineering-report.html
+++ b/docs/agent-engineering-report.html
@ -0,0 +1,184 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Stackchain AI Lab — Agent Engineering Report</title>
+<style>
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body { margin: 0; font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif; background: #0b1220; color: #e5e7eb; }
+  .wrap { max-width: 1200px; margin: 0 auto; padding: 32px 20px; }
+  h1 { font-size: 28px; margin: 0; letter-spacing: .02em; }
+  .sub { color: #9aa3b2; font-size: 13px; margin-top: 6px; }
+  .grid { display: grid; gap: 14px; margin-top: 24px; }
+  .grid-2 { grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); }
+  .grid-3 { grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); }
+  .card { background: #111827; border: 1px solid #1f2937; border-radius: 14px; padding: 18px; }
+  .card h2 { font-size: 13px; text-transform: uppercase; letter-spacing: .1em; color: #93c5fd; margin: 0 0 12px 0; }
+  .pill { display: inline-block; padding: 2px 9px; border-radius: 999px; background: #1f2937; color: #e5e7eb; font-size: 12px; margin: 2px; border: 1px solid #374151; }
+  .pill.live { border-color: #22c55e; color: #86efac; }
+  .pill.blocked { border-color: #ef4444; color: #fca5a5; }
+  .pill.wip { border-color: #f59e0b; color: #fcd34d; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th { text-align: left; color: #9aa3b2; padding: 8px 6px; border-bottom: 1px solid #1f2937; font-weight: 500; }
+  td { padding: 8px 6px; border-bottom: 1px solid rgba(31,41,55,.6); }
+  tr:last-child td { border-bottom: none; }
+  a { color: #60a5fa; text-decoration: none; }
+  .rule { height: 1px; background: #1f2937; margin: 24px 0; border: none; }
+  .kbd { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; background: #0b1220; border: 1px solid #374151; padding: 2px 6px; border-radius: 6px; font-size: 12px; color: #e5e7eb; }
+  .status { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #9aa3b2; }
+  .dot { width: 8px; height: 8px; border-radius: 50%; display: inline-block; }
+  .dot.green { background: #22c55e; box-shadow: 0 0 0 3px rgba(34,197,94,.2); }
+  .dot.red { background: #ef4444; box-shadow: 0 0 0 3px rgba(239,68,68,.2); }
+  .dot.amber { background: #f59e0b; box-shadow: 0 0 0 3px rgba(245,158,11,.2); }
+  .muted { color: #9aa3b2; }
+  .phase { font-size: 11px; text-transform: uppercase; letter-spacing: .12em; color: #93c5fd; margin-bottom: 8px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header style="display:flex;justify-content:space-between;align-items:end;flex-wrap:wrap;gap:10px;">
+    <div>
+      <h1>Stackchain AI Lab — Agent Engineering Report</h1>
+      <div class="sub">Audience: agent engineers · 2026-07-08 · Source of truth: Gitea</div>
+    </div>
+    <div class="status"><span class="dot green"></span> Operations active</div>
+  </header>
+
+  <section class="grid grid-3" style="margin-top:24px;">
+    <div class="card">
+      <h2>Current State</h2>
+      <table>
+        <tr><td>Infra</td><td>Gitea 1.22.0, Caddy-free routing</td></tr>
+        <tr><td>Public URL</td><td><a href="https://forge.alexanderwhitestone.com/git/">forge.alexanderwhitestone.com/git/</a></td></tr>
+        <tr><td>Org</td><td><a href="https://forge.alexanderwhitestone.com/git/org/stackchain">stackchain</a></td></tr>
+        <tr><td>Repos</td><td>4 active (`hackathon`, `dashboard`, `agent-todo-tracker`, `project-template`)</td></tr>
+        <tr><td>Active users</td><td>5 (2 admins onboarded via CLI + 2 promoted via DB + bot)</td></tr>
+        <tr><td>Pipeline</td><td>CI + RC workflows pushed to mains</td></tr>
+        <tr><td>Loop</td><td>Issue → PR → review → merge/no-spam, stale/blocked handled</td></tr>
+        <tr><td>Creative agent</td><td>Hou3 profile active on Tencent Hy3</td></tr>
+      </table>
+    </div>
+
+    <div class="card">
+      <h2>Stackchain Dashboard</h2>
+      <table>
+        <tr><td>Repo</td><td><a href="https://forge.alexanderwhitestone.com/git/stackchain/stackchain-dashboard">stackchain/stackchain-dashboard</a></td></tr>
+        <tr><td>Backend</td><td>FastAPI context endpoint + suggestion engine</td></tr>
+        <tr><td>Frontend</td><td>Adaptive SPA shell with 3-column layout</td></tr>
+        <tr><td>Kanban</td><td>Hermes board + label sync script wired</td></tr>
+        <tr><td>Issues</td><td>#9 epic, #10 context, #11 engine, #12 panels, #13 cache</td></tr>
+        <tr><td>Status</td><td><span class="pill wip">WIP</span> Backend scaffold shipped</td></tr>
+      </table>
+    </div>
+
+    <div class="card">
+      <h2>Queue Snapshot</h2>
+      <table>
+        <tr><td>Open issues</td><td>19 items in `stackchain-hackathon`</td></tr>
+        <tr><td>P0/P1</td><td><span class="pill blocked">P0</span> Pages enablement (blocked on human handoff)</td></tr>
+        <tr><td>P1</td><td>#8 Adaptive UI, #10 context, #11 engine, #12 frontend</td></tr>
+        <tr><td>P2</td><td>#13 cache, #5 agent-todo, #6 scaffolder</td></tr>
+        <tr><td>Creative</td><td>#16 README, #17 overlays, #18 release notes</td></tr>
+        <tr><td>Open PRs</td><td>0</td></tr>
+        <tr><td>Hou3</td><td>Actively composing deliverable drafts</td></tr>
+      </table>
+    </div>
+  </section>
+
+  <hr class="rule" />
+
+  <section class="grid grid-2">
+    <div class="card">
+      <h2>Operational Constraints</h2>
+      <table>
+        <tr><td>Caddy</td><td>No changes for Gitea work</td></tr>
+        <tr><td>Human touchpoints</td><td>Prototype review + RC test only</td></tr>
+        <tr><td>Config</td><td>`ROOT_URL=https://forge.alexanderwhitestone.com/git/`</td></tr>
+        <tr><td>Assets</td><td>`/var/lib/gitea/public/assets/` verified present</td></tr>
+        <tr><td>Pages API</td><td>Returns <span class="kbd">404</span>; enablement gated</td></tr>
+        <tr><td>Cleanup done</td><td>Dupe users removed, admins promoted</td></tr>
+      </table>
+    </div>
+
+    <div class="card">
+      <h2>Risk Register</h2>
+      <table>
+        <tr><td>Gitea Pages auth</td><td><span class="pill blocked">Medium</span></td><td>Surface as handoff in #14</td></tr>
+        <tr><td>Memory</td><td><span class="pill wip">Medium</span></td><td>Watchdog + serialize workers</td></tr>
+        <tr><td>Auth drift</td><td><span class="pill live">Low</span></td><td>Single admin path, weekly audit</td></tr>
+        <tr><td>Workflow drift</td><td><span class="pill wip">Medium</span></td><td>One canonical workflow source</td></tr>
+        <tr><td>Hou3 spam</td><td><span class="pill live">Low</span></td><td>Seen-state + max-comment guard</td></tr>
+      </table>
+    </div>
+  </section>
+
+  <hr class="rule" />
+
+  <section class="card">
+    <h2>Market Fit Matrix — What We Can Build</h2>
+    <table>
+      <tr><th>Product</th><th>Market Signal</th><th>Fit</th><th>Build Order</th></tr>
+      <tr><td>Adaptive UI dashboard</td><td>Context-aware developer surfaces are emerging category</td><td><span class="pill live">Strong</span></td><td>P0</td></tr>
+      <tr><td>Agent Task Harness</td><td>Deterministic multi-agent orchestration is foundational</td><td><span class="pill live">Strong</span></td><td>P1</td></tr>
+      <tr><td>Agent Memory Store</td><td>Cross-session memory is table stakes for useful agents</td><td><span class="pill live">Strong</span></td><td>P1</td></tr>
+      <tr><td>PR Review Agent</td><td>Automated review reduces human load</td><td><span class="pill live">Strong</span></td><td>P1</td></tr>
+      <tr><td>Repo Scaffolder Agent</td><td>NL project generation lowers onboarding friction</td><td><span class="pill wip">Medium</span></td><td>P2</td></tr>
+      <tr><td>Hou3 creative pipeline</td><td>Launch docs/content automation</td><td><span class="pill wip">Medium</span></td><td>P2</td></tr>
+      <tr><td>Gitea Pages site</td><td>Public lab landing page</td><td><span class="pill blocked">Medium</span></td><td>Blocked</td></tr>
+      <tr><td>Kanban-to-issue sync</td><td>Single pane of glass</td><td><span class="pill wip">Medium</span></td><td>Wired</td></tr>
+    </table>
+  </section>
+
+  <hr class="rule" />
+
+  <section class="grid grid-3">
+    <div class="card">
+      <div class="phase">Phase A — 0–48h</div>
+      <h2>Close the Loop</h2>
+      <ul>
+        <li>Ship adaptive dashboard panels from #8–#13</li>
+        <li>Wire Hou3 output → issues/PRs as real comments</li>
+        <li>Run first full autonomous cycle: branch, impl, PR, self-review, merge</li>
+      </ul>
+    </div>
+    <div class="card">
+      <div class="phase">Phase B — 48h–2w</div>
+      <h2>Harden</h2>
+      <ul>
+        <li>Fill test suites in dashboard + agent-todo-tracker</li>
+        <li>Automate token rotation via cron/Hermes job</li>
+        <li>Profile memory usage before adding more workers</li>
+      </ul>
+    </div>
+    <div class="card">
+      <div class="phase">Phase C — 2w+</div>
+      <h2>Scale</h2>
+      <ul>
+        <li>Multi-repo issue queue across <span class="kbd">stackchain/*</span></li>
+        <li>Unique staging targets per RC</li>
+        <li>Separate Hou3 creative queue from code queue</li>
+      </ul>
+    </div>
+  </section>
+
+  <hr class="rule" />
+
+  <div class="card">
+    <h2>Human Gates</h2>
+    <table>
+      <tr><th>Human Action</th><th>Trigger</th><th>What to do</th></tr>
+      <tr><td>Prototype review</td><td>PR includes preview link</td><td>Click, test, comment feedback</td></tr>
+      <tr><td>RC approval</td><td>Automated tests pass, draft release created</td><td>Verify locally, merge release PR</td></tr>
+      <tr><td>Pages handoff</td><td>Issue #14 is `blocked`</td><td>Enable Gitea Pages in UI; confirm URL</td></tr>
+      <tr><td>3 consecutive failed reviews</td><td>Auto-pause in loop</td><td>Surface in issue, triage, decide path</td></tr>
+    </table>
+  </div>
+
+  <footer style="margin-top:20px;color:#6b7280;font-size:12px;">
+    Source of truth: Gitea issues/PRs. Hermes kanban is mirror-only. No human devops required unless explicitly gated.
+  </footer>
+</div>
+</body>
+</html>
--- a/docs/agent-engineering-report.md
+++ b/docs/agent-engineering-report.md
@ -0,0 +1,84 @@
+# Stackchain AI Lab — Agent Engineering Report
+
+**Audience:** agent engineers  
+**Date:** 2026-07-08  
+**Status:** Operations active, prototypes shipping, release candidates pending human test only
+
+---
+
+## 1. Current State — What We Have Built
+
+| Layer | Artifact | Status | Evidence |
+|---|---|---|---|
+| **Infra** | Gitea 1.22.0 on VPS, Caddy-free routing | Live | `https://forge.alexanderwhitestone.com/git/` |
+| **Org** | `stackchain` org, 4 repos, 5 users | Live | Repos: `hackathon`, `dashboard`, `agent-todo-tracker`, `project-template` |
+| **Auth** | Least-privilege tokens per agent/user | Live | `timmy` org-admin, `turdbot` bot, admin CLI |
+| **Pipeline** | CI + RC workflows in `.gitea/workflows` | Live | Push to main auto-tags + drafts RC |
+| **Loop** | Autonomous issue→PR→review→merge/no-spam | Locked | Stale 72h, close +24h, velocity `#Velocity` |
+| **Agent** | `agent-todo-tracker` CLI shipped | Done | `init/create/list/update/close`, SQLite storage |
+| **Kanban** | Hermes board + Gitea label sync | Wired | `scripts/gitea_sync.py` |
+| **Creative** | Hou3 dispatcher profile (Tencent Hy3) | Active | Assigned to #16/#17/#18, composing deliverables |
+
+---
+
+## 2. Operational Constraints — Read This First
+
+- **No Caddy changes** for Gitea work. Period.
+- **No human devops.** Humans only: review prototype, test RC, approve ship.
+- **Cached config:** `/etc/gitea/app.ini` `ROOT_URL=https://forge.alexanderwhitestone.com/git/`
+- **Asset path:** `/var/lib/gitea/public/assets/` — verified exists
+- **Pages status:** Repo Pages API returns 404; enablement gated on human config handoff
+- **Dupe cleanup:** `john`/`JohnGalt` removed; `john52galt` retained
+- **Admin roster:** `rockachopa`, `timmy`, `grepples`, `john52galt`
+
+---
+
+## 3. Market Fit Matrix — What We Can Build Next
+
+| Idea | Market Signal | Fit | Build Order |
+|---|---|---|---|
+| **Adaptive UI dashboard** | Developers want intelligent, context-aware interfaces | Strong | P0 — already scoped in #8, needs fleshed panels |
+| **Agent Task Harness** | Multi-agent orchestration is table stakes for agentic startups | Strong | P1 — deterministic routing, retry, circuit break |
+| **Agent Memory Store** | Every agent needs persistent memory across sessions | Strong | P1 — shared KV store, embeddings optional |
+| **PR Review Agent** | Automated code review reduces human review load | Strong | P1 — inline comments, label-based auto-merge |
+| **Repo Scaffolder Agent** | Natural-language project generation lowers onboarding friction | Medium | P2 — templates + agent-driven file gen |
+| **Hou3 creative pipeline** | Marketing/docs automation for launch velocity | Medium | P2 — release notes, overlay variants, README polish |
+| **Gitea Pages site** | Public landing page for the lab | Medium | Blocked on Pages enablement |
+| **Kanban-to-issue sync** | Single pane of glass for ops | Medium | Wired but untested at scale |
+
+---
+
+## 4. Recommended Sequencing — Take It to the Next Level
+
+### Phase A — Close the Loop (0–48h)
+1. **Ship dashboard panels.** Turn the scaffold in `stackchain-dashboard` into a clickable, adaptive UI. Map panels to concrete Gitea views: review queue, issue triage, repo health.
+2. **Wire Hou3 output to PRs/issues.** Move from “drafting” to “posting review comments” on assigned issues. Close #16, #17, #18 with actual deliverables.
+3. **Run the first full autonomous cycle.** Pick one P1 issue, branch it, implement, open PR, self-review, merge. Prove the loop without spam.
+
+### Phase B — Harden (48h–2w)
+4. **Add tests.** The dashboard and `agent-todo-tracker` need real pytest suites. CI already runs them — fill the gap.
+5. **Token rotation cadence.** Automate via cron or a Hermes job. Don’t rely on manual rotation.
+6. **Resource audit.** 8GB RAM VPS. Model: Gitea + Caddy + N agents + dashboard. Profile before adding more workers.
+
+### Phase C — Scale (2w+)
+7. **Multi-repo velocity.** Queue issues across `stackchain/*`, not just `hackathon`.
+8. **External preview URLs.** Each RC gets a unique staging target. Humans click, test, approve.
+9. **Hou3 specialization.** Split creative dispatch into its own queue with different acceptance criteria than code agents.
+
+---
+
+## 5. Risk Register
+
+| Risk | Likelihood | Mitigation |
+|---|---|---|
+| Gitea Pages never enables via API | Medium | Surface as explicit human handoff in #14; do not block other work |
+| 8GB RAM exhaustion | Medium | Add memory watchdog; serialize worker starts |
+| Duplicate accounts / auth drift | Low | Single admin path through Timmy; audit weekly |
+| CI workflow YAML drift | Medium | One canonical workflow source; no mirroring |
+| Hou3 repeats itself / spams comments | Medium | Seen-state tracking in `dispatch.state`; max-comment guard |
+
+---
+
+## 6. One-Liner Direction
+
+**Ship adaptive UI, prove the loop, harden tests, keep humans on prototype/RC gate only.**
--- a/docs/engineering-org-protocol.md
+++ b/docs/engineering-org-protocol.md
@ -0,0 +1,34 @@
+# Engineering Org Protocol
+
+## Intake (Human → Org)
+User says: "We want [requirement]."
+1. Agent breaks requirement into Epic + child issues.
+2. Each issue gets labels (`P0`/`P1`/`P2`, type: `feature`, `bug`, `chore`, `docs`).
+3. Each issue gets an assignee based on agent roster.
+4. Epic links issues via Milestone.
+
+## Execution (Org → Ship)
+- Dispatch loop polls assigned issues.
+- Agent acknowledges, branches `<agent>/<issue>-<tag>`, implements, opens PR.
+- PR references parent issue.
+- CI runs automatically.
+- Self-review before merge: lint, tests, diff size, issue linkage.
+- Auto-merge only if: approval flag set AND low-risk AND human not previously blocked.
+
+## Release Cycle
+- Main branch = production-ready.
+- CI auto-tags RC on merge.
+- Human test RC in staging.
+- Human says “ship” or “rework.”
+- Agents do not push to production; humans approve releases.
+
+## Agent Roster
+- `timmy` — admin, orchestration, dispatch
+- `hou3` — creative, docs, UI copy, release notes
+- `turdbot` — integration, API, CI pipelines
+- `vincent` — frontend/backend implementation
+
+## Human Gates
+- Prototype review (click preview, comment)
+- RC approval (test, merge release)
+- Blocked/paused workflows (3 failed reviews)