# 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
```