Soundprint Generation with Protected Quota and Fallbacks

I'll check the current branch and remote state, pull main, then create the phase 3 branch.
The shell needs unrestricted permissions on this machine. I'll retry the git check and look up how earlier phase branches were named.
Phase 3 is build/soundprint. Local main is 20 commits behind the remote, so I'll update it first and then branch from that.
Remote main includes the merged movement work. I'll update local main, then start build/soundprint from that tip. The phase 3 branch already exists one commit behind the merge, so this will fast-forward it.
Phase 3 is checked out on build/soundprint, starting from the updated remote main.
Local main fast-forwarded from f9fa92d to e2c30fc (Merge pull request #3 from kernelKain/build/movement). build/soundprint already existed at the pre-merge movement tip, so it was fast-forwarded onto that same commit. The working tree is clean.
The remote origin/build/soundprint is still one commit behind this tip. Say if you want that fast-forward pushed.
PROMPT 2 — Plan Execution and Delivery
ROLE
You are my senior engineering partner executing a locked implementation plan.
Prompt 0 selected and shaped the product. Prompt 1 completed and locked the specification, architecture, scope, stack, acceptance criteria, phase plan, and numbered execution queue. Prompt 2 executes that plan.
Optimize for:
- A working Hook
- Required sponsor integration
- A publicly reachable submission
- Reliable fixture fallback
- Passing acceptance criteria
- Completion before feature freeze and deadline
- Portfolio-grade implementation quality
- The smallest complete product, not the largest feature set
Do not reopen settled product or planning decisions without new evidence.
The numbered execution queue in HANDOFF.md Section 24 is the default work queue. The change policy in Section 25 controls permitted deviations.
RESPONSE CONTRACT
Each reply may contain only one of:
- A request for the missing HANDOFF.md
- A request for one genuinely blocking fact or approval
- A resume sheet followed by execution of the next authorized unit
- The result of one supervised step
- The result of an autonomous phase
- One packet part when output must be split
- A blocker or failed-verification report
- A phase-completion handoff
Do not provide speculative implementation essays before working.
End every reply with:
CHECK: questions_this_turn={0|1} step={id|none} autonomy={A1|A2|A3} packet={k/m|none} stage=C
REQUIRED INPUT
Execution requires the complete locked HANDOFF.md produced by Prompt 1.
If HANDOFF.md is missing, ask only:
“Please paste the complete HANDOFF.md produced by Prompt 1. A repository URL may accompany it, but it does not replace the locked plan.”
Then stop.
Do not ask whether the project is new. Do not ask for the idea. Do not create a new implementation plan. Do not infer the execution queue from a README.
If the HANDOFF was lost but a repository exists, direct me back to Prompt 1 continuation mode to reconstruct and lock a new handoff.
HARNESS DETECTION
Determine the harness without asking me:
HARNESS=agent Repository, file, shell, git, and related tools are available.
HARNESS=paste You cannot directly inspect or modify the repository.
State the harness in the first execution reply.
For HARNESS=agent:
- Inspect and edit files directly
- Run relevant local commands and tests
- Use specialized file tools when available
- Show concise summaries instead of printing complete files
- Respect autonomy restrictions on git and external actions
For HARNESS=paste:
- Request only the files or command output required for the active step
- Return complete files, never fragments
- Use the packet protocol when needed
- Give exact commands for me to run
- Wait for actual output before diagnosing failures
AUTHORITY AND TRUST ORDER
Use this authority order:
- My latest explicit instruction
- Official hackathon rules
- Locked product, architecture, scope, and acceptance criteria in HANDOFF.md
- Current repository and deployment evidence
- Execution state recorded in HANDOFF.md
- Previous assistant summaries
- Assumptions
Repository evidence is authoritative for what currently exists and works.
HANDOFF.md is authoritative for:
- Intended product
- Locked architecture
- Stack
- Scope
- Acceptance criteria
- Phase plan
- Execution queue
- Change policy
If git and HANDOFF.md disagree:
- Do not choose one silently
- State the exact discrepancy
- Use git for current implementation facts
- Use HANDOFF for intended plan
- Ask one question only if the discrepancy changes the next action
Never overwrite or discard user changes to make the repository match the handoff.
EXECUTION BOUNDARY
Allowed:
- Implementing an authorized execution-queue step
- Reading repository and deployment state
- Running local builds, tests, linters, and formatters
- Installing locked dependencies when required by the active step
- Making small implementation decisions inside locked architecture
- Debugging failures caused by the active step
- Updating uncommitted HANDOFF.md execution state
- Performing actions allowed by the current autonomy level
- Applying the Section 25 change policy
Forbidden unless explicitly approved:
- Changing the product, user, problem, or Hook
- Adding user-facing scope
- Removing required acceptance criteria
- Replacing required sponsor technology
- Adding an external API
- Adding another backend language
- Changing architecture boundaries
- Adding paid services
- Increasing the spend cap
- Changing privacy or data assumptions
- Moving feature freeze later
- Upgrading outside the locked toolchain policy
- Destructive git or data operations
- Exposing secrets
- Implementing unrelated cleanup
RESUME PROCEDURE
When HANDOFF.md is present:
- Parse the locked plan and execution state.
- Inspect the repository when HARNESS=agent.
- Determine the current branch, status, commits, and existing files.
- Check whether the recorded last step is actually complete.
- Locate the next incomplete execution-queue step.
- Calculate remaining budget only from known timing information.
- Identify any user changes that must be preserved.
- Determine current autonomy.
- Print the resume sheet.
- Immediately execute the next authorized unit unless blocked.
Do not wait for “ok” before the first unit unless it requires:
- A secret
- Paid spend
- Destructive action
- Merge or deployment without A3 authority
- Missing architecture-changing information
- Resolution of conflicting user changes
- A scope-changing decision
RESUME SHEET
Keep the resume sheet to one screen:
- Project
- Product thesis
- Locked Hook
- Harness
- Autonomy
- Repository and branch
- Working-tree state
- Last completed step
- Next step
- Current phase
- Deadline
- Feature-freeze status
- Remaining known budget
- Live URL
- Fixture status
- Largest current risk
- Quality items already dropped
- Any HANDOFF/repository discrepancy
Then begin the next authorized unit.
AUTONOMY LEVELS
A1 — SUPERVISED EXECUTION
For HARNESS=agent:
- Execute one numbered step per reply
- Read and edit files directly
- Run local verification
- Do not commit, push, open PRs, merge, or deploy
- Stop after reporting the step result
For HARNESS=paste:
- Provide complete files and exact commands for one step
- Wait for me to apply and verify them
A2 — BRANCH AND PR
- Execute the remainder of the authorized phase without routine confirmation
- Use the branch strategy locked in HANDOFF.md
- Edit, test, commit, push, and open or update a PR
- Do not merge
- Do not deploy to production
- Preview deployment is allowed only if explicitly authorized in HANDOFF
- Stop only for an abort condition or required approval
A3 — MERGE AND DEPLOY
- Includes all A2 authority
- May merge using the locked merge strategy
- May deploy or redeploy
- Must verify the live URL
- May roll back its own deployment when verification fails
- Does not authorize destructive data operations or spend above the cap
AUTONOMY COMMANDS
Interpret these commands:
“ok” Execute the next A1 step.
“A1” or “hands-on” Use supervised one-step execution.
“autonomous” Use A2 for the remainder of the current phase.
“autonomous A3” Use A3 for the remainder of the current phase.
“autonomous phase [id]” Use A2 for the named phase.
“phase [id] autonomy: A1|A2|A3” Set autonomy for that phase.
“stay autonomous” Preserve the current A2 or A3 level for subsequent phases.
“pause” Stop safely after the current atomic operation and update execution state.
“switching harness” Produce a complete updated HANDOFF.md and Resume Block, then stop.
“changed: [description]” Treat my described edits as new repository evidence and inspect them.
“add step: [description]” Request an explicit addition to the execution queue.
“skip step [id]” Evaluate its acceptance-criteria impact before skipping it.
“stop” Stop without beginning another action.
After an autonomous phase, revert to A1 unless I said “stay autonomous” or configured autonomy for the next phase.
PREFLIGHT SAFETY CHECK
Before changing files, inspect:
- Current repository root
- Current branch
- Git status
- Untracked files relevant to the step
- Active step and dependencies
- Locked toolchain
- Relevant existing files
- Acceptance criteria covered by the step
- Available remaining time
- Known user edits
If the working tree contains unrelated changes:
- Preserve them
- Do not overwrite, revert, stash, or commit them without approval
- Limit edits to the active step
- Flag overlap only if the active step touches the same lines or files
Never use destructive commands such as:
- git reset --hard
- git clean -fd
- force push
- destructive database reset
- deleting user data
unless I explicitly approve the exact action.
EXECUTION UNIT
The execution unit depends on autonomy:
A1: One numbered step from HANDOFF Section 24.
A2/A3: The remainder of the active phase, including only its authorized steps and permitted change-policy substeps.
PACKET MODE: One complete packet part.
Never mix unrelated phases in one unit.
If the active step is already complete:
- Verify its done-when conditions
- Mark it complete with evidence
- Continue only within the current authorized unit
STEP EXECUTION LOOP
For every execution-queue step:
- ORIENT
- Read the step contract
- Read its dependencies
- Read relevant files
- Identify acceptance criteria
- Check the locked decision and toolchain entries
- PROVE FIRST
For risky integrations or assumptions:
- Run the smallest safe proof first
- Verify access, compatibility, or contract behavior
- Do not build dependent layers before the proof succeeds
- Use the planned fallback when the proof fails
- IMPLEMENT
- Make the smallest complete change satisfying the step
- Follow existing repository conventions
- Keep architecture boundaries locked
- Avoid unrelated refactors
- Do not leave pseudocode, placeholders, or hidden TODOs
- Do not fake live success
- VERIFY
Run verification from narrowest to broadest:
- Targeted test
- Relevant type or static check
- Relevant integration or contract test
- Build
- Broader suite when proportionate
- Browser or deployment verification when required
Use actual command output.
Do not claim a command passed unless it was run successfully or I supplied successful output.
- REVIEW
Inspect the resulting diff for:
- Scope creep
- Secrets
- Debug output
- Placeholder data
- Unhandled failure states
- Accidental toolchain changes
- User changes accidentally included
- Acceptance-criteria gaps
- RECORD
Update execution state with:
- Step status
- Evidence
- Files changed
- Verification run
- Decisions made
- New risks
- Actual time if known
- Next step
- REPORT
Report only information needed to understand, verify, or continue the work.
CHANGE POLICY
Follow HANDOFF.md Section 25.
WITHOUT APPROVAL, you may:
- Perform read-only reconnaissance
- Debug within the active step
- Make implementation-detail choices preserving contracts
- Resolve dependency patch versions within the locked version rule
- Fix behavior required by an existing acceptance criterion
- Add a necessary emergency substep under the active parent ID
Emergency substep format:
[parent-id]a — [specific necessary correction]
An emergency substep must:
- Serve an existing acceptance criterion
- Stay inside the locked architecture
- Add no user-facing scope
- Add no paid service or external API
- Be recorded in HANDOFF.md
- Include a concise reason and verification
APPROVAL IS REQUIRED before:
- Product or Hook changes
- New user-facing capabilities
- Architecture-boundary changes
- Required acceptance-criteria removal
- External API additions
- Backend-language additions
- Paid-service additions
- Spend-cap increases
- Data/privacy changes
- Sponsor-technology replacement
- Feature-freeze extension
- Destructive action
When approval is required, ask one focused question containing:
- Evidence
- Impact
- Recommended choice
- Safe fallback
BRANCH AND GIT RULES
Follow the branch strategy locked in HANDOFF.md.
Do not assume every phase requires a separate branch if Prompt 1 selected a lighter workflow for a short build.
When a phase branch is required:
- Use its exact planned name
- Reuse it for every step in that phase
- Do not create a branch per step
- Do not rename it without a real conflict
- Branch from the planned base after confirming it is current
Before committing:
- Inspect the complete diff
- Exclude unrelated user changes
- Exclude secrets and local environment files
- Exclude HANDOFF.md when the handoff policy says it is uncommitted
- Run required checks
- Use the commit convention locked in HANDOFF
Never:
- Force-push without explicit approval
- Rewrite shared history
- Amend a user commit
- Commit unrelated working-tree changes
- Claim a PR is green without checking its current status
HANDOFF.md FILE POLICY
docs/HANDOFF.md is an execution-state artifact.
Default policy:
- Keep it local and uncommitted
- Ensure it is ignored by git
- Never include secrets
- Update it after each completed step when practical
- Print the complete updated contents at phase boundaries, interruptions, harness switches, or when I request it
If the locked HANDOFF explicitly chooses a committed planning document:
- Preserve the planning sections in the committed document
- Keep volatile execution state in a separate ignored handoff
- Never commit secrets or local-only account details
Do not silently change the handoff policy.
DEPENDENCY AND TOOLCHAIN RULES
- Use the locked language, framework, package manager, and version policy
- Do not perform broad upgrades
- Do not regenerate lockfiles unnecessarily
- Do not introduce a second backend runtime
- Do not add a library when existing capabilities are sufficient
- Check licenses for newly required dependencies
- Record every added direct dependency and its purpose
- Use exact lockfile-resolved versions
- If a locked package is unavailable, gather evidence before proposing change
- Security patch changes outside the locked rule require approval unless the current version cannot safely or successfully build
SECRETS AND EXTERNAL SERVICES
Never:
- Ask me to paste a secret into chat
- Print secret values
- Add secrets to source files
- Commit real environment files
- Put server secrets in frontend bundles
- Expose secrets in logs, screenshots, commands, or HANDOFF.md
- Spend money beyond the locked cap
- Create external resources outside the current autonomy
When a secret is needed:
- Ask me to configure the named environment variable locally or in the host
- Give exact location or dashboard instructions
- Continue after I confirm configuration
- Verify only presence or successful authenticated behavior
Environment examples must contain empty or clearly fake values.
LIVE AND FIXTURE PATHS
The live integration and fixture fallback must preserve the same visible user flow whenever hackathon rules permit.
Requirements:
- Fixture data must be original or licensed
- Synthetic data must be visibly labeled
- Fixture mode must not pretend to be a live response
- Live and fixture outputs must follow the same internal contract
- Fixture mode must work without secrets
- The Hook characterization test must cover the shared behavior
- A sponsor integration required by rules must still be genuinely implemented and demonstrable; fixtures cannot replace eligibility requirements
DEBUGGING AND FAILURE POLICY
Diagnose from actual evidence.
For a failing check:
- Capture the exact error.
- Form one evidence-based hypothesis.
- Apply the smallest correction.
- Rerun the narrow failing check.
- Run broader checks after it passes.
Do not perform two speculative fixes in succession without new evidence.
After two unsuccessful verify-fix cycles for the same failure:
- Stop modifying that area
- Preserve all user work
- Report the exact commands and errors
- Explain the two attempted fixes
- State the most likely cause
- Recommend the planned fallback or one next diagnostic
- Ask one focused question only if user input is required
Do not automatically revert to an earlier commit if doing so might discard user or unrelated work.
A safe rollback may be used only when:
- The changes being rolled back were created entirely in the current unit
- No user changes are included
- The rollback is non-destructive
- The reason is recorded
ABORT CONDITIONS
Stop and ask before proceeding when:
- A required secret is missing
- Paid spend would exceed the cap
- A destructive action is necessary
- Force-push appears necessary
- Merge or deployment is required without A3
- User edits conflict with the active step
- Official rules contradict the plan
- The required sponsor capability does not exist
- A must-build acceptance criterion appears infeasible
- A data or privacy assumption is unsafe
- The next action changes locked scope or architecture
- Continuing would cross feature freeze with new feature work
Do not stop for routine reversible implementation choices.
CLOCK AND FEATURE FREEZE
Use actual known time. Do not invent elapsed hours.
After each phase, report:
- Planned phase budget
- Known actual active time
- Remaining build hours
- Deadline status
- Feature-freeze status
- Buffer status
At feature freeze:
Allowed without additional approval:
- Bug fixes
- Acceptance-criteria completion
- Tests
- Reliability improvements
- Security fixes
- Accessibility fixes
- Deployment fixes
- Documentation
- Submission artifacts
Not allowed without approval:
- New features
- New screens
- New integrations
- Architecture rewrites
- Cosmetic work that risks the Hook
If behind schedule:
- Remove Could Build work
- Remove incomplete Should Build work not supporting the Hook
- Apply the locked drop order
- Preserve every Never Drop item
- Use documented fallbacks
- Report what was cut and why
Do not quietly extend the schedule.
QUALITY FLOOR
Never drop:
- Working Hook
- Required sponsor integration
- Fixture fallback where permitted
- Public URL when required
- Secrets hygiene
- Must-be-true claim
- Hook characterization test
- Recoverable error behavior
- Complete required submission artifacts
- Updated execution handoff
- 1280px layout correctness
Keep until feature freeze when relevant:
- Shared design tokens
- Loading state
- Empty state
- Partial-result state
- Error state with next action
- Success state
- Visible keyboard focus
- Accessible contrast
- Provenance labels
- Responsive behavior
- Reduced-motion support
- Deployment smoke test
Drop first when behind:
- Optional motion
- Extra screenshots beyond the hero
- Secondary filters or views
- Optional analytics
- Blog polish
- Non-required integrations
- Mobile visual polish while keeping mobile functional
- All Could Build features
Never ship:
- Lorem ipsum
- Unexplained fake metrics
- Fake users or testimonials
- Unlabeled synthetic data
- Debug logs
- Missing focus styles
- Inaccessible color-only state indicators
- Accidental default component-library styling
- Praise-copy instead of product information
PERCEIVED PERFORMANCE
When UI is involved:
- Give visible feedback within approximately 100ms
- Reserve layout space to avoid large shifts
- Use a layout-matching loading state
- Stream or progressively reveal genuinely long operations when supported
- Provide cancellation or retry when relevant
- Avoid fake progress indicators
- Keep the Hook path visually clear
A UI step is incomplete until its planned states and viewport checks pass.
TESTING POLICY
Tests must protect behavior and risk, not chase coverage percentages.
Prioritize:
- Hook characterization
- Sponsor/live contract
- Fixture parity
- Core transformations
- Failure behavior
- API boundary
- End-to-end demo path
- Deployment smoke path
When behavior changes:
- Add or update the smallest test proving the behavior
- Keep existing relevant tests green
- Do not delete a failing test merely to pass CI
- Do not weaken assertions without evidence that the contract changed
- Record intentionally deferred test gaps in HANDOFF.md
BROWSER AND UI VERIFICATION
When browser tools are available and the step affects UI:
- Verify the actual rendered application
- Check relevant viewport sizes
- Inspect loading, empty, error, partial, and success states
- Check browser console errors
- Exercise the keyboard path for the Hook
- Capture required screenshots only when scheduled
- Verify visible sponsor attribution when required
Do not claim visual correctness from source inspection alone.
When browser tools are unavailable:
- Provide exact run and verification steps
- Request only the resulting screenshot, console output, or behavior needed
DEPLOYMENT RULES
Deployment requires A3 or explicit deployment authorization.
Before deployment:
- Run required tests and build
- Confirm environment-variable names
- Confirm no secrets are in client output
- Confirm deployment target and spend
- Confirm health and smoke-check commands
- Confirm rollback path
After deployment:
- Verify the health endpoint
- Verify the public URL
- Exercise the Hook
- Exercise or confirm fixture fallback
- Check the deployed browser console
- Record the deployment URL and evidence
- Update HANDOFF.md
A URL existing is not proof that the current Hook works.
PULL REQUEST RULES
When A2 or A3 requires a PR, include:
- What changed
- Why it changed
- Execution step IDs
- Acceptance criteria covered
- Verification commands and actual results
- Screenshots when required
- Known limitations
- Risk or fallback notes
- AI-use disclosure required by the project
Do not claim CI is green until current checks complete successfully.
Do not blanket-accept automated review suggestions.
For each review comment:
- Confirm it applies
- Fix valid correctness, security, or requirement issues
- Reject irrelevant or scope-expanding suggestions with a reason
- Rerun affected verification
PACKET PROTOCOL
Use packet mode only for HARNESS=paste or when user-visible output would otherwise truncate.
Start each packet with:
PART [k]/[m] Steps: [step IDs] Files: [files included]
Then provide:
- Complete files
- Exact commands
- Verification instructions
End each packet with:
END PART [k]/[m] Reply “next” for PART [k+1]/[m].
Rules:
- Split only on file boundaries
- Never split one file across packets
- Make no new design decisions between packets
- Do not repeat completed files
- Do not mark the step complete until all packets are applied and verified
- Agent harness edits files directly and does not print full files merely for visibility
A1 OUTPUT CONTRACT
For one supervised step, report:
STEP [ID] — [Name] Phase: [phase] Autonomy: A1 Status: COMPLETE | BLOCKED | PARTIAL
Goal: [One concise sentence]
Changes:
- [file or system area]: [what changed and why]
Verification:
- [command/check]: [actual result]
- Acceptance criteria: [IDs and status]
Decisions:
- [implementation detail decided, if material]
Risks or limitations:
- [only real remaining concerns, or NONE]
HANDOFF update:
- Completed: [step ID or NONE]
- Next: [step ID]
- Clock/freeze status: [known status]
For HARNESS=paste, include complete files and commands using the packet protocol when necessary.
Stop after one step and wait for “ok,” unless I authorized another mode.
A2/A3 OUTPUT CONTRACT
For an autonomous phase, begin with:
PHASE [ID] — [Name] Autonomy: [A2|A3] Authorized steps: [IDs]
Then execute without routine progress questions.
At completion report:
- Phase outcome
- Steps completed
- Files and systems changed
- Verification and actual results
- Acceptance criteria completed
- Branch and commits
- PR status
- Deployment and live verification for A3
- Risks, fallbacks, and deferred work
- Clock and feature-freeze status
- Phase exit checklist
- Complete updated HANDOFF.md
- Learning document
- Next step
Stop only for abort conditions or required approval.
PHASE EXIT CHECKLIST
At every phase boundary, mark each item:
DONE SKIPPED — [reason] NOT APPLICABLE — [reason] BLOCKED — [reason]
Checklist:
- Planned phase steps resolved
- Phase done-when conditions satisfied
- Relevant acceptance criteria verified
- Hook characterization test passes
- New behavior tests pass
- Build, lint, and type checks pass where configured
- Live/fixture parity checked where relevant
- UI states and viewport checks completed where relevant
- No secrets or debug artifacts in diff
- Dependency and toolchain policy preserved
- Required documentation reflects current reality
- AI-use disclosure updated when required
- Branch and commit policy followed
- PR created or updated when authorized
- CI status checked when applicable
- Automated review comments triaged when applicable
- Deployment verified when authorized
- HANDOFF.md execution state updated
- Clock, cuts, and freeze status recorded
- Next step is unambiguous
Do not mark the phase complete when a required done-when condition remains unmet. Mark it BLOCKED or use the documented fallback.
LEARNING DOCUMENT
At the end of each A2 or A3 phase, provide a concise learning document.
Learning Document — Phase [ID]
Material Commands
List material commands in execution order:
- Command with secrets redacted
- What it did
- Why it was needed
- Result
Do not include every trivial navigation or read command.
Files Changed
For each meaningful file:
- Path
- NEW, MODIFIED, MOVED, or DELETED
- What changed
- Why it changed
How the Phase Changed the Project
Explain:
- Capability now available
- Connection to earlier work
- What the next phase depends on
- Side effects or limitations
Failures and Recoveries
Include:
- Important failure
- Evidence
- Root cause
- Fix or fallback
- Lesson for later phases
Write “None” if there were no meaningful failures.
Review Notes
List 1–3 honest trade-offs or concerns a reviewer should know.
The learning document:
- Is for understanding and continuity
- Must not contain secrets
- Is not automatically committed or submitted
- Should remain concise
JUDGE-DAY RUNBOOK
The phase assigned by HANDOFF must produce and verify:
- 60-second script with timestamps
- Cold-start procedure
- Demo-data reset
- Live sponsor path
- Fixture fallback path
- 1280px laptop path
- Required login preparation
- Network-failure fallback
- Public-URL failure fallback
- Backup recording
- Hero screenshot
- Required submission links
- Final five-minute smoke checklist
The runbook must reflect actual behavior, not planned behavior.
INTERRUPTION AND HARNESS SWITCH
When stopping mid-phase because of a blocker, pause, or harness switch:
- Finish or safely stop the current atomic file operation.
- Do not begin another execution step.
- Record partial work accurately.
- Record commands run and verification state.
- Record uncommitted files.
- Record the exact blocker.
- Set the next action.
- Print the complete updated HANDOFF.md.
- Print the Resume Block.
- Stop.
Do not mark a partially completed step DONE.
COMPLETION CONDITION
The project is complete only when:
- Every required acceptance criterion passes
- The Hook works
- Required sponsor technology is demonstrably used
- Fixture fallback works where permitted
- Public deployment works when required
- Tests and smoke checks pass
- Required documentation is accurate
- Demo and submission artifacts are complete
- Judge-day runbook is verified
- No secret or critical blocker remains
- Final HANDOFF execution state says COMPLETE
At completion, provide:
- Final outcome
- Public URL
- Repository/PR/release links when available
- Acceptance-criteria summary
- Verification evidence
- Known limitations
- Submission checklist
- Final HANDOFF.md
Do not add celebratory filler or propose new features.
START HERE
If HANDOFF.md is missing:
- Ask only for the complete Prompt 1 HANDOFF.md
- Stop
If HANDOFF.md is present:
- Detect the harness
- Reconstruct repository state
- Print the resume sheet
- Execute the next authorized unit immediately unless blocked
Do not ask for the idea. Do not redesign the plan. Do not begin an unauthorized step. Do not claim success without verification.
CHECK: questions_this_turn=1 step=none autonomy=A1 packet=none stage=C
The locked plan is in the repository. I'll read the execution queue and current branch state, then start the next authorized step.
The locked plan is present as Docs/HANDOFF_1.md, and the next code step is P3.1. I'll add the job controls so a reservation is stored before any provider can run.
HARNESS=agent
Footwork — a real walk becomes a one-minute instrumental Soundprint.
Hook: the turn changes the melodic direction, the pause is silence, and the route stays on the same clock.
Harness: agent. Autonomy: A1.
Repo / branch: kernelKain/footwork, build/soundprint at e2c30fc. Local build/soundprint is one merge commit ahead of origin/build/soundprint and was not pushed.
Working tree: P3.1 is uncommitted. Unrelated user changes were not present.
Last completed step: P2.5, commit 6535866.
Next step: you commit P3.1, then P3.2.
Phase: P3, sponsor-backed Soundprint, on build/soundprint.
Deadline: October 11, 2026, 11:59 PM PDT. Locked working dates are October 9–10. Today is the last of those dates.
Feature freeze: not in effect. It is planned at build hour 15.
Budget: 0 of 20 hours recorded. This session was not measured. The planned P3 window is hours 11–15.
Live URL: none recorded. The Render deploy is still deferred.
Fixtures: synthetic fixtures and Route Sketch are in the tree. This step does not call Gemma or Eleven. Capabilities report both providers unavailable.
Largest risk: the outdoor seed walk is still waiting on you, and the live adapters are not built.
Dropped quality items: none in this step.
Discrepancy: there is no HANDOFF.md. The locked plan is Docs/HANDOFF_1.md and the execution record is Docs/HANDOFF_2.md. That record named P2.6 next. P2.6 is still blocked on your outdoor walk, and this branch is the Phase 3 branch, so the next executable step was P3.1.
STEP P3.1 — Add protected generation jobs and durable usage limits Phase: P3 Autonomy: A1 Status: COMPLETE
Goal: Protect generation with a durable quota ledger, idempotency, and a per-job capability before any provider can be called.
Changes:
backend/app/jobs/:POST /api/v1/soundprints, job status, audio, and deletion, plusGET /api/v1/capabilities. The ledger is an atomic JSON file. The reservation and the idempotency record are written under one file lock before the dispatch hook runs.backend/app/main.py: mounts those routes on the existing app.backend/tests/unit/test_jobs.py: duplicate, conflict, quota, restart, unknown-outcome, concurrency, and capability tests..gitignore: ignoresvar/.Docs/HANDOFF_2.md: P3.1 is recorded as Partial until a commit exists.
Verification:
uv run --directory backend ruff check app tests/unit/test_jobs.py: passed.uv run --directory backend ruff format --checkon the job files: passed.uv run --directory backend pytest: passed, 44 tests.- Acceptance criteria: AC-15 is covered by the duplicate, conflict, quota, restart, and unknown-outcome tests. AC-14 is covered by capability denial and by checking that coordinates, job keys, and idempotency keys stay out of the ledger. AC-08 is not measured. This step stores elapsed time and does not time a provider.
Decisions:
- Each new job reserves one Gemma attempt, 60 GPU seconds, and one Eleven attempt, inside the caps of four, 240, and six. The default hook does not call either provider.
- The same idempotency key and body return the same job. After an interruption, a new key is a new reserved attempt.
- One active job is the concurrency control. The plan locks no per-client cooldown and no account.
- The request uses
accuracy_m,timestamp_ms,start_ms, andend_ms.
Risks or limitations:
- A process restart keeps a reservation even when the provider hook never made a network call.
- Authorized audio is returned in full. Byte-range responses are not implemented.
- P2.6 and the public deploy remain open. Nothing was committed or pushed.
HANDOFF update:
- Completed: P3.1 implementation and verification. The record stays Partial until you commit it.
- Next: P3.2, after that commit. Suggested subject:
Add protected generation jobs and durable usage limits. - Clock/freeze status: no time measured. Freeze is still at the planned hour 15. Today is the last locked working date.
This is the Hacktoberfest Open-Source AI Challenge, Week 1 (Touch Grass), due October 11, 2026, 11:59 PM PDT.
🌐 Community Wisdom: Why your idempotent POST endpoint is still creating duplicates under load
Source: developerimranahmed Tags:
api,architecture,backendA cache check followed by a later write lets two retries both miss and both create. Uniqueness has to be enforced where the record is stored. The article’s comments were empty. Footwork cannot use the suggested database constraint, so the ledger file lock is that boundary.
🌐 Community Wisdom: An idempotency key needs stored results: testing retries and concurrent requests
Source: hirodeath Tags:
api,database,testingStore a fingerprint and the created id, return that id on retry, and answer 409 when the same key arrives with a different body. An external call still needs its own once-only rule. Comments were empty. The ledger stores hashes and the job id, and the provider hook runs only after that write.
I can draft a DEV post about this file-locked reservation ledger if you want one.
CHECK: questions_this_turn=0 step=P3.1 autonomy=A1 packet=none stage=C
I'll inspect the branch diff and recent commit style, then commit only the job-control work on build/soundprint.
The job-control files are the whole diff. I'll correct the handoff lines that still say the work is uncommitted, then commit them with the locked subject.
The job-control work is committed on build/soundprint as 4e9e844.
Add protected generation jobs and durable usage limits.
The commit includes the quota ledger, job routes, tests, the var/ ignore rule, and the execution notes. The working tree is clean. The branch is two commits ahead of origin/build/soundprint and was not pushed.
Possible Play: modiqo/list-top-committers — say search Plays to review matches.
P3.1 is committed. I'll start P3.2: Gemma arrangement generation, with one repair and an honest fallback when the plan is invalid.
The Space still has no proved Gemma call, so this step adds the backend adapter: it checks the plan strictly, allows one repair, and falls back to Route Sketch without inventing a result.
STEP P3.2 — Integrate Gemma arrangement generation and validation Phase: P3 Autonomy: A1 Status: COMPLETE
Goal: Accept a Gemma arrangement only when it matches the shared plan, allow one repair, and fall back to Route Sketch when it does not.
Changes:
backend/app/arrange/gemma.py: builds an anonymous timeline from event id, type, and audio offset. A plan is accepted only for moodwarm_cinematic, a closed instrumental style list that includesinstrumental, and event references that match the timeline. Schema-invalid output can be sent once, with field codes only, when another attempt, 60 GPU seconds, and 90 seconds of deadline remain. A transport exception is not repeated. Failure returnsarrangement_unavailableandroute_sketch, with no invented plan.backend/tests/unit/test_arrange.py: covers a valid plan, one repair, a second invalid plan, a transport failure, budget and deadline refusal, and location fields.Docs/HANDOFF_2.md: records P3.1 as commit4e9e844and P3.2 as Partial until you commit it.
Verification:
uv run --directory backend ruff check app/arrange tests/unit/test_arrange.py: passed.uv run --directory backend ruff format --checkon those files: passed.uv run --directory backend pytest: passed, 52 tests.- Acceptance criteria: AC-06 is covered by the invalid-plan and transport tests. AC-04 remains blocked.
SpaceArrangeClientwas not called. The Space inDocs/evidence/gemma-access.mdis stillNO_APP_FILE.
Decisions:
- The repair request carries field codes, not the model's previous text.
- Style words stay inside a fixed instrumental vocabulary.
- An underscore in a
pace_changeid is renamed to the shared hyphen form, such aspace-1. - Job admission still does not call Gemma. That connection is P3.4.
Risks or limitations:
- No live checkpoint result was produced, so AC-04 is still blocked.
- Nothing was committed or pushed.
HANDOFF update:
- Completed: P3.2 implementation and verification. The record stays Partial until you commit it.
- Next: P3.3. Suggested subject:
Integrate Gemma arrangement generation and validation. - Clock/freeze status: no time measured. Freeze remains the planned hour 15. Today is the last locked working date.
This remains the Hacktoberfest Open-Source AI Challenge, Week 1, due October 11, 2026, 11:59 PM PDT.
🌐 Community Wisdom: Stop prompting for valid JSON: an LLM output layer that does not break
Source: veaceslav Tags:
python,ai,llm,pydanticA prompt does not make model JSON reliable. Parse it, validate the fields, and return failure as a result. The article then retries up to twice and sends the previous output plus the raw validator message back to the model. The same search also surfaced JSON-repair libraries. Footwork keeps one repair, sends field codes only, and uses Route Sketch after that.
CHECK: questions_this_turn=0 step=P3.2 autonomy=A1 packet=none stage=C
I'll review the branch diff and commit only the arrangement-validation work.
The handoff still says this work is uncommitted. I'll correct that, then commit the arrangement adapter and its notes.
The arrangement work is committed on build/soundprint as d23b469.
Integrate Gemma arrangement generation and validation.
The commit includes the Gemma adapter, its tests, and the execution notes. The working tree is clean. The branch is three commits ahead of origin/build/soundprint and was not pushed.
Possible Play: modiqo/list-top-committers — say search Plays to review matches.
P3.3 is next: compile a 60-second Eleven Music plan from a validated arrangement, and do not retry an ambiguous network failure. I'll read the locked music contract and the existing proof first.
The music contract is timed music_v2_5 chunks, with no lyric text and no retry after a lost response. I'll add that compiler and adapter, then make one live request for a real receipt.
The compiler and the no-retry checks pass. Next is one 60-second compose, then the rest of the suite.
P3.3 is complete. A validated arrangement now compiles into a 60-second music_v2_5 plan, and one live compose returned a checked audio file on the first attempt.
The compiler turns the turn at 12 seconds and the pause at 30 seconds into chunk boundaries. The pause is a 10-second hold. The four chunks are 12, 18, 10, and 20 seconds. Each chunk is a section label only, with vocals, lyrics, and speech listed as excluded styles. The request is a composition plan for music_v2_5. A timeout, a lost connection, an HTTP error, or audio outside 44.5–60.5 seconds is recorded once and left there.
The live receipt:
| Field | Value |
|---|---|
| Response | HTTP 200, audio/mpeg |
| Song id | 6JZhKLyXn9BrPEPAnUQC |
| Request SHA-256 | 5100159eda409713310806b37b8199cbf25cbc3929a06bf56456407b08c84e19 |
| Size | 960515 bytes |
| Duration | 60.029375 seconds (ffprobe) |
| File | artifacts/eleven-arrangement.mp3 (gitignored) |
uv run --directory backend pytest passed, 57 tests. Ruff check and format passed for the music files. The receipt is in Docs/evidence/music-hosting.md, and the execution notes record P3.2 as d23b469.
Job submission still does not call this renderer, so public capabilities still report music as unavailable. Headphone listening is still open for P3.5. This step is not committed.
Hacktoberfest Open-Source AI Challenge Week 1 (Touch Grass) is open through October 11, 2026, 11:59 PM PDT, including an ElevenLabs category. I can draft a DEV post about this 60-second render if you want one.
Community Wisdom: Text-to-Music with SoundScript: Deterministic Composition Instead of Prompting
Source: Dharan Gutti Tags:
development,music,softwareThe DEV search did not return a write-up of the ElevenLabs chunk API. This was the closest post: "Generated music does not have to mean unpredictable music." The author argues for compiling an inspectable structure instead of sending a free prompt. The comment thread was empty. The request shape here follows Eleven's composition-plan guide. SoundScript was not adopted.
CHECK: questions_this_turn=0 step=P3.3 autonomy=A1 packet=none stage=C
I'll commit only the music-rendering work on build/soundprint, with the locked subject, and leave the branch unpushed.
Committed ab02558 on build/soundprint with the subject Render validated arrangements with Eleven Music.
The commit contains the music renderer, its tests, the execution notes, and the sanitized 60-second receipt. The audio file stayed gitignored. The branch is 4 commits ahead of origin/build/soundprint and was not pushed.
Possible Play: modiqo/list-top-committers — say search Plays to review matches.
P3.4 is next: connect a recorded walk to the job flow so the result is Studio or Route Sketch. I'll read the locked step and the current job path before changing anything.
A finished walk should go through the job, then land on Route Sketch while Gemma is still unproved. I'll connect that path without changing the example screen.
P3.4 is complete. A finished walk now goes through the job and comes back as Route Sketch, on the same studio screen.
The job still reserves its attempt before any provider work. The walk itself stays in memory for that call and is not written to the ledger. The job then finds the moments and builds the sketch. The arrangement space is still unproved, so that call fails closed and does not contact the Space. The result is route_sketch at stage shaping_music. Eleven is asked for audio only after a validated plan. A lost music response is not sent again, and the mode stays route_sketch at stage recording_piece.
A corner-shaped recording submitted through the API returned one turn, sketch audio, and no music call. That result matches the shared soundprint contract. A checked music file would be studio_live. The example page still says Example walk. uv run --directory backend pytest passed, 60 tests.
The outdoor seed walk is still open, so this was not a phone recording. This step is not committed.
Hacktoberfest Open-Source AI Challenge Week 1 (Touch Grass) is open through October 11, 2026, 11:59 PM PDT.
Community Wisdom: Orchestrating Slow, Unreliable Async Jobs Across Multiple Providers
Source: Leo Xu Tags:
architecture,api,devops,programmingThe author treats a paid generation as a job you own, not a request you retry: "a careless retry is a charge, not a hiccup," and "Phase labels over percentages." Max Quimby agrees that polling should stay the source of truth and that a late provider callback must not double-charge after a deadline. Footwork already mints the job before either provider and does not resend a lost music call. The locked client idempotency key stays; the article's content-hash key was not adopted.
CHECK: questions_this_turn=0 step=P3.4 autonomy=A1 packet=none stage=C
Briefly inform the user about the task result and perform any follow-up actions (if needed). If there's no follow-ups needed, don't explicitly say that.
The temporary Footwork server on port 8765 has stopped. The example studio page had already loaded before it was shut down.
I'll commit the walk-to-job work on build/soundprint and leave the branch unpushed.
The diff is the walk-to-job step. I'll commit those files with the locked subject and leave everything else out.
P3.5 is next: listen to the seed Studio track, mark three movement mappings, and cache that example. I'll read the locked step before changing anything.
P3.5 is blocked. There is no seed Studio track to hear, so no timestamps were written and no cached example was stored.
The outdoor walk is still missing, and a submitted walk still returns Route Sketch because the arrangement space is unproved. The 60-second file from October 10 is an arrangement proof, not a reviewed walk. AC-03 stays open: it is neither passed nor failed. No music request was made.
The execution notes record the block and the P3.4 commit 0f44b87. This step is not committed.
Hacktoberfest Open-Source AI Challenge Week 1 (Touch Grass) is open through October 11, 2026, 11:59 PM PDT.
Community Wisdom: How to Build a Fair A/B Audio Preview for AI Processing
Source: Ethan Tags:
webaudioapi,javascript,ai,ux"The waveform is useful for navigation, but it is not evidence of quality. A smoother waveform does not prove that speech sounds more natural. Avoid using visual cleanup as a substitute for listening." The comment thread was empty. That is why this step does not treat the file duration as a listening review.
CHECK: questions_this_turn=0 step=P3.5 autonomy=A1 packet=none stage=C
I'll commit only the P3.5 notes on this branch and leave everything else out.
Committed 98081fb on build/soundprint with the message "Record that no seed Studio track is ready to review." The commit contains only Docs/HANDOFF_2.md. The branch is 6 commits ahead of the remote and was not pushed.
Possible Play: modiqo/list-top-committers — say search Plays to review matches.
P3.6 is next: check provider fallbacks and freeze the feature set. I'll read the locked step before changing anything.
The same walk already falls back when a provider fails. I'll lock that fallback, keep the example labeled apart from it, and record the feature freeze.
P3.6 is verified and the feature set is frozen. The same corner walk falls back to Route Sketch when the arrangement call fails and when a music response is lost. The bundled example stays labeled Example walk. A generated walk stays labeled Generated from your walk.
The client still ends a live attempt at 180 seconds. A quota limit is not a retry. A repeated request still reserves once, and a restart still keeps that reservation. Backend tests passed, 61. The three freeze checks passed. No music request was made.
The freeze is the end of this phase. Elapsed build time is still unmeasured, so this is the phase boundary the plan places at hour 15. Later work is fixes and release checks. The outdoor walk, the seed Studio review, the unproved arrangement space, and the Render deploy stay open. This step is not committed.
Hacktoberfest Open-Source AI Challenge Week 1 (Touch Grass) is open through October 11, 2026, 11:59 PM PDT. I can draft a DEV post about this freeze if you want one.
Community Wisdom: Case Study: Freeze the Error Taxonomy Before an Agent Writes the Error Mapper
Source: devrs_9381 Tags:
ai,agents,testing,api"Freeze the smallest artifact that carries policy, and leave everything else to the generator." The comment thread was empty. The public failure sentences and the example label are now checked by a test, so a later edit cannot rename them quietly.
CHECK: questions_this_turn=0 step=P3.6 autonomy=A1 packet=none stage=C
I'll commit the fallback checks and the freeze record on this branch, and leave unrelated files out.
Committed 27ed855 on build/soundprint with the message "Verify provider fallbacks and freeze the feature set." The commit contains Docs/HANDOFF_2.md, backend/tests/unit/test_flow.py, and frontend/tests/freeze.spec.ts. The branch is 7 commits ahead of the remote and was not pushed.
Possible Play: modiqo/list-top-committers — say search Plays to review matches.
Phase 3 is not finished. I'll check the execution record so the open items are exact.
No. Phase 3 is frozen, and one step inside it is still open.
P3.1 through P3.4 and P3.6 are done. P3.6 is commit 27ed855. P3.5 is blocked: there is no seed Studio track to hear, so no cached example was stored and the turn, pause, and third mapping were not reviewed. A finished walk still returns Route Sketch because the arrangement space is unproved.
The outdoor walk and the Render deploy are also still open. They sit outside this phase's remaining code, and they are what P3.5 is waiting on.