> For the complete documentation index, see [llms.txt](https://nytshift.gitbook.io/nytshift-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/proposal-lifecycle.md).

# Advisory proposal lifecycle

## Normal operation

1. Unlock the local operator session and open Terminal **Safety settings**.
2. Paste one complete strict `TradeProposal` JSON document into **Advisory proposal ledger** and select **Validate + register**.
3. Confirm the returned state and fixed reason. Registration is advisory and has no execution capability.
4. For a Hyperliquid draft, select the exact symbol and side first. Use **Attach to draft** only when the ledger presents an exact valid match.
5. Request the normal live risk review. Confirm that AEGIS independently approved the current order and that the review names the reserved proposal UUID.
6. If submission is authorized, confirm once. A consumed proposal is never reusable. If outcome is unknown, reconcile the displayed CLOID and do not register or attach the same idea under a new UUID as a retry.

Manual orders remain available without a proposal and receive the same AEGIS and execution controls.

## State meanings

| State         | Meaning                                                                 | Operator action                                                                                     |
| ------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `valid`       | Within the configured validity window and unbound                       | Attach only to the exact matching Hyperliquid symbol/side, or invalidate                            |
| `reserved`    | Bound to one server-owned review intent until ticket expiry             | Confirm that review or wait for expiry; never create a duplicate proposal                           |
| `consumed`    | Explicit confirmation crossed the single-use boundary before signer I/O | Never reuse; reconcile the CLOID if venue outcome is unknown                                        |
| `invalid`     | Schema-valid record failed time/validity policy or expired              | Correct the analysis upstream and use a genuinely new proposal UUID only for genuinely new analysis |
| `invalidated` | Operator deliberately revoked unconsumed analysis                       | Do not reuse or edit the checkpoint                                                                 |

## Degraded state

`/api/health` reports `proposalLifecycleState`, retained counts and a fixed reason without returning proposal identity. A `degraded` state or `PROPOSAL_CONFIGURATION_INVALID:*` means proposal import/attachment must stop. Manual execution remains governed by its existing gates; do not delete the store to clear an error.

1. Run `pnpm preflight` and correct only the bounded values documented in `.env.example`.
2. Stop the supervisor before filesystem investigation: `pnpm local:stop`.
3. Preserve the current `%USERPROFILE%\.nightshift\data\proposal-lifecycle-v1.json` bytes for incident analysis. Do not open them in an untrusted tool or hand-edit state.
4. Run `pnpm backup:list` and `pnpm backup:verify -- <backup-id>`.
5. Restore only a verified checkpoint while the supervisor is stopped: `pnpm backup:restore -- <backup-id>`.
6. Restart and verify `pnpm local:health`, then unlock and confirm the ledger counts/state.

The default settings are 30 retention days, 1,000 records, 5,000 events and a 15-minute maximum proposal validity. Accepted ranges are enforced by preflight and the local-production configuration parser. `NIGHTSHIFT_PROPOSAL_STORE_PATH`, when used outside supervised defaults, must be absolute and is intentionally excluded from `config.json`.

## Emergency invalidation

Use **Invalidate** for a valid or reserved proposal when its analysis is no longer trusted. A subsequent submission attempt with an already issued ticket fails closed. A consumed proposal cannot be invalidated because it is retained as conservative single-use evidence.

Never edit a proposal record, change a hash, shorten a reservation manually, manufacture a consumed event, or treat the ledger as order-finality evidence. The signer audit and venue reconciliation remain authoritative for capital-moving outcomes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://nytshift.gitbook.io/nytshift-docs/agents-identity-and-data/proposal-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.