trackly-cli 0.7.3 → 0.9.0

package/skills/trackly-apply/references/browser-lifecycle.md

@@ -0,0 +1,101 @@
+# Browser lifecycle and recovery
+
+Keep business identity in Trackly and host-specific browser identity local.
+Every live tab belongs to exactly one frozen job and existing application run.
+Never infer identity from window position, a transient tab number, or title text
+alone.
+
+## Local tab ledger
+
+Maintain a local job ID -> run ID -> tab record containing the raw tab
+identifiers, browser surface, normalized requisition URL, binding hash,
+ownership state, and inspection epoch. Raw tab identifiers never go to the
+Trackly backend. If the host persists the ledger, store it in a private
+mode `0600` file and remove it when the batch expires.
+
+Backend observations contain only a value-free binding hash, inspection epoch,
+ownership state, lifecycle/action codes, and timestamps. Never send the URL,
+tab title, employer, role, page text, credentials, or answer values as browser
+metadata.
+
+## Reconciliation
+
+Before resuming, handing off, or closing a tab:
+
+1. Request every complete controller-owned inventory the host can enumerate.
+2. Request every complete user-owned inventory the host can enumerate.
+3. Normalize and reconcile their union against the local ledger.
+4. Treat an inventory as authoritative only when the adapter explicitly says
+   it is complete. Omission from an incomplete or single-surface inventory is
+   not proof that a tab is gone.
+5. Reclaim a matching tab only after employer, role, requisition, HTTPS origin,
+   ATS tenant when applicable, run ID, and browser binding all revalidate.
+
+For every initial tab and every recovery, call `trackly_bind_apply_surface`
+with the existing frozen member and run. Use `initial_binding` for the first
+surface and `recovery_binding` after a missing tab or handoff. The returned URL
+is the only URL recovery may open. Treat its returned member version and
+inspection epoch as authoritative; do not reuse evidence from the prior epoch.
+
+The Sola failure mode is the regression model: a handed-off tab can disappear
+from the controller inventory while remaining visible in the user inventory.
+Never make a closure claim from one inventory surface.
+
+## Close proof
+
+For a submitted application, do not begin tab closure until Trackly has
+durably reconciled both the batch member to `submitted` and the saved job to
+`applied_confirmed`. A success page or explicit user confirmation authorizes
+the outcome write; it does not prove that the write committed. On a conflict,
+keep the tab visible while the agent refreshes and performs the one documented
+idempotent replay. If reconciliation still fails, leave the tab open and
+report a control-plane defect.
+
+`closed_verified` requires all of the following for the current inspection
+epoch:
+
+- the adapter declares both available controller and user inventories complete;
+- the exact bound tab receives an explicit close receipt; and
+- the tab is absent from the complete post-close union.
+
+Record these facts separately with `trackly_record_apply_surface_evidence`:
+`surface_inventory_reconciled`, `surface_close_receipt`, and
+`surface_post_close_absent`. A post-close absence event is invalid unless it
+explicitly covers the complete controller+user union. The backend, not the
+agent's prose, derives `closed_verified` from all three current-epoch facts.
+
+If the close request succeeds but a complete union is unavailable or still
+contains the tab, the agent must not claim `closed_verified`; record
+`closure_unverified`. If no mapped tab is found before a verified close,
+record `missing`. Close evidence from an earlier inspection epoch cannot
+satisfy the current closure gate.
+
+Do not close a review-ready tab merely to reduce clutter. Preserve it for the
+user's manual Submit unless the user closes it or explicitly asks the agent to
+close it.
+
+## Missing-tab recovery
+
+When an incomplete member's tab is missing:
+
+1. Preserve the frozen member and reuse the existing run. Never create a
+   replacement run for browser recovery.
+2. Call `trackly_bind_apply_surface` with `recovery_binding`; reopen only its
+   exact backend-stored requisition URL. Do not use search,
+   company careers navigation, redirects remembered from chat, or an invented
+   URL.
+3. Revalidate HTTPS origin, ATS tenant policy, employer, role, requisition, and
+   job identity before entering private data.
+4. Increment the browser inspection epoch and bind the recovered tab. Evidence
+   from an earlier inspection epoch cannot satisfy the current review gate.
+5. Reinventory the whole form. Do not claim that unsaved ATS draft state
+   survived a crash, user close, or handoff.
+6. Refill only verified canonical answers and rerun every applicable integrity
+   gate. If the page shows a changed success URL or submission state,
+   revalidate the exact requisition before recording any outcome and never
+   activate Submit again.
+
+If the recovered origin or identity differs, semantic controls are
+unobservable, or access is blocked by credentials or a pre-form challenge,
+stop private-data mutation and create the appropriate human action. Continue
+the other frozen batch members.

package/skills/trackly-apply/references/review-handoff.md

@@ -1,6 +1,6 @@
 # Review handoff
 
-Provide this compact block and stop:
+For one application, provide this compact block and stop:
 
 ```text
 Ready for your review — not submitted
@@ -26,4 +26,55 @@ Items requiring your attention:
 Please review the live form and click Submit manually.
 ```
 
-Do not include restricted answers in chat unless needed for the user’s review. Never include an OTP or CAPTCHA response.
+For a frozen batch, first summarize unresolved human actions, then provide one
+review block per run that reached `review_ready`. Continue processing other
+members before presenting the first-pass handoff.
+
+## Grouped actions
+
+Group recoverable actions in this order:
+
+1. company;
+2. role;
+3. run;
+4. action type.
+
+Show the stage and what the user must do, without copying raw form questions or
+private values into Trackly observations. Separate credentials, legal choices,
+artifacts, and unknown reusable answers. Later handoffs contain only newly
+revealed conditional deltas.
+
+## Batch review table
+
+Include one row per frozen member:
+
+```text
+Job ID | Run ID | Browser label | ATS | State | Human actions | Evidence
+```
+
+The browser label may help the user find a visible tab, but raw tab identifiers
+stay local and out of Trackly. For each review-ready run, include its current
+inspection epoch, resume-content approval status, per-run attachment proof,
+truth certification status, required scenario coverage, and integrity result.
+Submission evidence and closure evidence remain separate and are normally
+empty until after the user's manual Submit.
+
+After the user submits, record one typed `user_confirmation` only when the user
+explicitly says they submitted. Prefer a current-epoch `success_page` proof when
+the controlled browser visibly shows success. Record a provider receipt only
+from the application surface itself; never search email or a mailbox. Hash the
+proof locally and never send confirmation text, page text, receipt identifiers,
+or URLs as evidence.
+
+Do not claim the batch is ready until every frozen member is either
+`review_ready`, has an explicit resumable human action, is user-revoked, or has
+a terminal trust/observability blocker.
+
+Do not make ready siblings wait for an unresolved member. Hand off every
+truth-certified `review_ready` subset as soon as it is durable, keep its tabs
+open for manual submission, and list remaining human actions separately.
+Members that become ready later require a new certification for the exact
+then-current `review_ready` subset.
+
+Do not include restricted answers in chat unless needed for the user’s review.
+Never include credentials, an OTP, or a CAPTCHA response.