nigig-org/workflow.md

# Nigig-org implementation workflow

This document records the reproducible workflow used in this session from repository acquisition through validation and Gitdab push. It deliberately excludes credentials, access tokens, and any other secret material.

## 1. Obtain and inspect the repository

```bash
git clone https://gitdab.com/andodeki/nigig-org.git
cd nigig-org
git log -1 --format='%H %cs %s'
git status --short
```

Initial review inputs were read from `REVIEWS/`, especially:

- `REVIEWS/NIGIG_PAY_CONSOLIDATED_REVIEW.md`
- `REVIEWS/PAY_CAD_IMPLEMENTATION_STATUS.md`
- the map, spreadsheet, CAD, and cost-estimator review documents.

The implementation work started from the review priority order: contain unsafe payment behavior first, establish a pure domain and durable storage boundary, then migrate legacy paths incrementally.

## 2. Preserve local work while pulling upstream changes

Do not pull over uncommitted implementation work directly. Fetch first, inspect changes, then use rebase/autostash only after confirming the target branch.

```bash
git fetch origin
git log --oneline HEAD..origin/main
git pull --rebase --autostash origin main
git status --short
```

This session pulled upstream commit `e9616c3` (`added missing crates`) and preserved local changes through Git’s autostash mechanism.

## 3. Repair vendored crate paths after upstream import

Upstream added Robius crates under `crates/`, while dependent manifests still pointed to old sibling-repository paths.

The local crate paths were repaired for:

- `robius-sms`
- `robius-ussd`
- `robius-fingerprinting`
- `robius-contacts`
- `robius-trigger`

The root workspace list was also repaired to add commas, remove a duplicate member, and include each imported crate once.

Validation used Python’s TOML parser and direct path checks:

```bash
python3 - <<'PY'
import tomllib
from pathlib import Path
for manifest in [Path('Cargo.toml'), *Path('crates').rglob('Cargo.toml')]:
    tomllib.loads(manifest.read_text())
print('all Cargo manifests parse')
PY
```

The full workspace is not claimed buildable in a standalone checkout until all external Makepad and remaining Robius sibling dependencies are available or vendored.

## 4. Use isolated, self-cleaning Rust tests

The repository contains:

```text
tools/test-rust-clean.sh
```

It creates a temporary directory containing:

- isolated `RUSTUP_HOME`;
- isolated `CARGO_HOME`;
- isolated build target;
- copied pure crate(s), outside the incomplete workspace dependency graph;
- a minimal Rust toolchain and `rustfmt`.

It removes the entire environment through a shell trap on success, failure, interruption, or termination.

Run pure domain tests:

```bash
TEST_TARGET=domain ./tools/test-rust-clean.sh
```

Run storage tests:

```bash
TEST_TARGET=storage ./tools/test-rust-clean.sh
```

To inspect a failed temporary environment only:

```bash
KEEP_TEST_ENV=1 TEST_TARGET=storage ./tools/test-rust-clean.sh
```

Then delete the retained temporary path manually after diagnosis. Do not retain toolchains/caches inside the repository or user home directory.

## 5. Validate each implementation tranche

Before committing each feature:

```bash
git diff --check
TEST_TARGET=domain ./tools/test-rust-clean.sh
TEST_TARGET=storage ./tools/test-rust-clean.sh
```

Use only relevant isolated tests when a feature changes one pure crate. Be explicit if full application compilation cannot run because external GUI/platform dependencies are absent.

## 6. Commit focused changes

Use one focused commit for one tested implementation tranche:

```bash
git add <specific files>
git commit -m '<type>(pay): concise description'
git log -1 --format='%H %s'
```

Repository-local identity used in this session:

```bash
git config user.name 'andodeki'
git config user.email 'andodeki@noreply.gitdab.com'
```

Do not set a global identity unless the developer explicitly wants that behavior.

## 7. Push to Gitdab

Push only after validation and a successful focused commit:

```bash
git push origin main
```

If HTTPS credentials are unavailable in a non-interactive environment, configure authentication through a secure credential helper, SSH deploy key, or an access token supplied through a secure mechanism. Never commit, log, store, or copy a token into repository files, workflow documents, shell history, or Git remote configuration.

After pushing:

```bash
git status --short
git log -1 --format='%H %s'
```

The expected result is a clean working tree and the pushed commit at `origin/main`.

## 8. Current payment migration order

The current safe migration sequence is:

1. Keep default builds tracker-only.
2. Block legacy PIN UI, PIN request creation, USSD dispatch, automatic retry, and bulk dispatch outside explicit demo mode.
3. Use exact-domain `PaymentIntent`, `Money`, validation and fee calculation.
4. Persist payment intent transitions through SQLite and a single storage worker.
5. Import legacy JSON pending records conservatively as reconciliation-required where outcome is ambiguous.
6. Wire startup migration once, then move authoritative UI reads from legacy JSON to SQLite.
7. Only then replace the legacy thread-local PayFlowHandler with the coordinator/application-service path.
8. Add SQLCipher/Keystore integration and provider-authorized gateway before enabling production payment dispatch.

## 9. Non-negotiable rules

- No production default path may collect or retain an M-Pesa PIN.
- No ambiguous session/SMS outcome may be called a known payment failure or success.
- No automatic replay of a financial dispatch after an ambiguous outcome.
- No silent unknown fee fallback to zero.
- No `git push` before test/check results are known.
- No access token or credential in committed files or workflow documentation.