| # ProjectIntakeTower |
|
|
| ProjectIntakeTower is a local, read-only intake harness for Samuel's machine. It scans approved project and agent-state roots, creates a prioritized inventory, drafts bounded handoff jobs, drafts GitHub issues locally, and verifies the resulting artifacts. |
|
|
| ## Purpose |
|
|
| Reduce open mental tabs into one working map: |
|
|
| - local project inventory |
| - project cards with evidence snippets |
| - triage lists |
| - bounded review-only job contracts |
| - local GitHub issue drafts |
| - owner digest |
|
|
| ## Safety model |
|
|
| - Source projects are scanned read-only. |
| - Writes are restricted to this `ProjectIntakeTower/` repository. |
| - Secret-like filenames and secret-like content are skipped/redacted. |
| - Dependency/build/cache directories are ignored. |
| - Large/binary files are not read; media is treated as filename metadata only. |
| - GitHub issues are not created by default. Drafts are Markdown files under `github/issue_drafts/`. |
| - Worker jobs are `review_only` unless Samuel explicitly changes the mode. |
|
|
| ## Run intake |
|
|
| From this repository: |
|
|
| ```bash |
| bash scripts/run_all.sh |
| ``` |
|
|
| The pipeline runs: |
|
|
| 1. `scripts/scan_projects.py` |
| 2. `scripts/create_project_cards.py` |
| 3. `scripts/triage_projects.py` |
| 4. `scripts/generate_jobs.py` |
| 5. `scripts/generate_github_issue_drafts.py` |
| 6. verifier checks |
|
|
| ## Outputs |
|
|
| - `OWNER_DIGEST.md` — one-screen owner summary |
| - `inventory/raw_scan.jsonl` — scan events and skipped roots/files |
| - `inventory/projects.jsonl` — structured project inventory |
| - `inventory/project_cards/*.md` — one card per detected project/artifact cluster |
| - `inventory/evidence/*.json` — capped safe evidence snippets |
| - `triage/BACKLOG.md` |
| - `triage/TOP_10_NEXT_ACTIONS.md` |
| - `triage/MERGE_CANDIDATES.md` |
| - `triage/ARCHIVE_CANDIDATES.md` |
| - `triage/NEEDS_HUMAN.md` |
| - `jobs/pending/*.json` — bounded handoff contracts |
| - `github/issue_drafts/*.md` — local issue drafts |
|
|
| ## GitHub issue creation |
|
|
| Default behavior creates local drafts only: |
|
|
| ```bash |
| python3 scripts/generate_github_issue_drafts.py |
| ``` |
|
|
| To create real issues, review drafts first, then run explicitly: |
|
|
| ```bash |
| python3 scripts/generate_github_issue_drafts.py --create --repo OWNER/REPO --yes |
| ``` |
|
|
| No issue creation happens without `--create --repo OWNER/REPO --yes`. |
|
|
| ## Agent job protocol |
|
|
| Agents working from `jobs/pending/*.json` must: |
|
|
| 1. Read exactly one job contract. |
| 2. Treat `project_path` as read-only. |
| 3. Never read or print secrets. |
| 4. Never commit, push, merge, delete, or refactor source projects. |
| 5. Write artifacts only under `ProjectIntakeTower/jobs/done/<job_id>/`. |
| 6. Stop with `needs_human` if credentials, destructive actions, unclear owner intent, or writes outside scope are required. |
| 7. Treat success as verifier-owned: artifacts plus verifier pass, not agent opinion. |
|
|
| ## Operator role |
|
|
| The Operator keeps Samuel in control. The Operator dispatches bounded workers, verifies artifacts, summarizes results, and human-gates risky decisions. Worker claims are not accepted without artifact paths and verifier results. |
|
|
| ## Verifiers |
|
|
| ```bash |
| python3 verifier/verify_inventory.py |
| python3 verifier/verify_job_contracts.py |
| python3 verifier/verify_artifacts.py |
| ``` |
|
|
| For a completed job: |
|
|
| ```bash |
| python3 verifier/verify_artifacts.py --job jobs/pending/<job_id>.json --require-done |
| ``` |
|
|
