Add CI pass requirement guidance

CONTRIBUTING.md

@@ -8,7 +8,7 @@ We welcome open-source contributions! As middleware, this SDK is critical for th
 3. **Branching:** Use `feat/`, `fix/`, or `chore/` prefixes.
 4. **Testing:** You MUST write unit tests in `tests/` for any new methods added. PRs without test coverage will be rejected. For predictable SDK responses without live RPC, use the mock client from `@aegis/sdk/testing` (see `docs/testing.md`). Behavior changes should follow the [Test-First Contribution Guide](docs/test-first-contribution.md), including happy-path, negative-path, and no-test justification rules.
 5. **Formatting:** Ensure `npm run lint` and `npm run format` pass before opening a PR.
-6. **CI Verification:** Run `npm run check` locally to verify that build, unit tests, and runtime compatibility checks pass. PRs with failing GitHub Actions CI checks will not be reviewed or merged until all status checks are green (see [CI Resolution Workflow](docs/ci-resolution-workflow.md)).
+6. **CI Verification:** Run `npm run check` locally to verify that build, unit tests, and runtime compatibility checks pass. PRs with failing GitHub Actions CI checks will not be reviewed or merged until all status checks are green (see [CI Pass Requirements](docs/ci-pass-requirements.md) and [CI Resolution Workflow](docs/ci-resolution-workflow.md)).
 
 Search the codebase for `// TODO:` comments to find areas that need immediate help!
 

README.md

@@ -1,105 +1,105 @@
-#  Aegis SDK
-
-The official TypeScript SDK for the **Aegis RWA Protocol**. This library provides a clean, class-based interface to interact with Aegis Soroban smart contracts on the Stellar network.
-
-##  Installation
-
-```bash
-npm install @aegis/sdk
-```
-
-## Quickstart
-Initialize the client with a typed environment preset and query the compliance module.
-```TypeScript
-import { AegisClient } from '@aegis/sdk';
-import { Keypair } from '@stellar/stellar-sdk';
-
-const adminKeypair = Keypair.fromSecret('S...');
-
-const aegis = new AegisClient({
-  environment: 'testnet', // or 'local'; see docs/environments.md
-  contractId: 'C_YOUR_CONTRACT_ID',
-  keypair: adminKeypair // Optional for read-only calls
-});
-
-async function main() {
-  // Check if a user is KYC compliant
-  const isApproved = await aegis.compliance.checkWhitelist('G_USER_PUBLIC_KEY');
-  console.log('Is User Whitelisted?', isApproved);
-}
-
-main();
-```
-## Role Discovery & Capability Checks
-Check what an address is classified as, and what it can currently attempt through the SDK.
-This is a client-side convenience for UI gating, not on-chain authorization — see the
-[full documentation](./docs/role-discovery.md) for important caveats.
-```TypeScript
-const roleResult = await aegis.role.discoverRole('G_USER_PUBLIC_KEY');
-console.log('Role:', roleResult.role); // 'investor' | 'unauthorized' | 'unknown'
-
-const capability = await aegis.role.checkCapability('G_USER_PUBLIC_KEY', 'receive_transfer');
-console.log('Can receive transfer?', capability.isPermitted);
-```
-
-## Contract Event Decoder
-Decode Soroban contract events into typed audit-trail models for dashboards and indexers.
-
-```typescript
-import { decodeContractEvent } from '@aegis/sdk';
-
-const event = decodeContractEvent({
-  topic: rpcEvent.topic,
-  value: rpcEvent.value,
-  txHash: rpcEvent.txHash,
-});
-
-if (event.kind === 'transfer') {
-  console.log(event.from, event.to, event.amount);
-}
-```
-
-See [Contract Event Decoder](./docs/contract-events.md) for supported topics, unknown fallback behaviour, and dashboard integration guidance.
-
-## Testing
-To run the SDK unit tests locally:
-
-```
-npm run test
-```
-
-Run the full release gate, including TypeScript compilation and browser/Node
-runtime compatibility checks:
-
-```bash
-npm run check
-```
-
-### Pre-submit verification
-
-Run all checks (lint, format, build, test, compat) in a single command before
-submitting a PR:
-
-```bash
-npm run verify
-```
-
+#  Aegis SDK
+
+The official TypeScript SDK for the **Aegis RWA Protocol**. This library provides a clean, class-based interface to interact with Aegis Soroban smart contracts on the Stellar network.
+
+##  Installation
+
+```bash
+npm install @aegis/sdk
+```
+
+## Quickstart
+Initialize the client with a typed environment preset and query the compliance module.
+```TypeScript
+import { AegisClient } from '@aegis/sdk';
+import { Keypair } from '@stellar/stellar-sdk';
+
+const adminKeypair = Keypair.fromSecret('S...');
+
+const aegis = new AegisClient({
+  environment: 'testnet', // or 'local'; see docs/environments.md
+  contractId: 'C_YOUR_CONTRACT_ID',
+  keypair: adminKeypair // Optional for read-only calls
+});
+
+async function main() {
+  // Check if a user is KYC compliant
+  const isApproved = await aegis.compliance.checkWhitelist('G_USER_PUBLIC_KEY');
+  console.log('Is User Whitelisted?', isApproved);
+}
+
+main();
+```
+## Role Discovery & Capability Checks
+Check what an address is classified as, and what it can currently attempt through the SDK.
+This is a client-side convenience for UI gating, not on-chain authorization — see the
+[full documentation](./docs/role-discovery.md) for important caveats.
+```TypeScript
+const roleResult = await aegis.role.discoverRole('G_USER_PUBLIC_KEY');
+console.log('Role:', roleResult.role); // 'investor' | 'unauthorized' | 'unknown'
+
+const capability = await aegis.role.checkCapability('G_USER_PUBLIC_KEY', 'receive_transfer');
+console.log('Can receive transfer?', capability.isPermitted);
+```
+
+## Contract Event Decoder
+Decode Soroban contract events into typed audit-trail models for dashboards and indexers.
+
+```typescript
+import { decodeContractEvent } from '@aegis/sdk';
+
+const event = decodeContractEvent({
+  topic: rpcEvent.topic,
+  value: rpcEvent.value,
+  txHash: rpcEvent.txHash,
+});
+
+if (event.kind === 'transfer') {
+  console.log(event.from, event.to, event.amount);
+}
+```
+
+See [Contract Event Decoder](./docs/contract-events.md) for supported topics, unknown fallback behaviour, and dashboard integration guidance.
+
+## Testing
+To run the SDK unit tests locally:
+
+```
+npm run test
+```
+
+Run the full release gate, including TypeScript compilation and browser/Node
+runtime compatibility checks:
+
+```bash
+npm run check
+```
+
+### Pre-submit verification
+
+Run all checks (lint, format, build, test, compat) in a single command before
+submitting a PR:
+
+```bash
+npm run verify
+```
+
 See [Test-First Contribution Guide](docs/test-first-contribution.md) for when behavior changes need happy-path, negative-path, and no-test justification coverage.
 
-See [Verification Command](docs/verification.md) for detailed usage and
-troubleshooting guidance.
-
-See [Runtime Compatibility](docs/runtime-compatibility.md) for the supported
-environments, what the automated probes cover, and integration guidance.
-
-For step-by-step instructions on reproducing and fixing CI check failures, see the [CI Resolution Workflow](docs/ci-resolution-workflow.md).
-
-## Contributing
-We welcome contributions! Please check our [CONTRIBUTING.md](CONTRIBUTING.md) for our branching strategy and code style guidelines.
-
-### Review Process
-PRs submitted to this repository are reviewed against our [Pull Request Reviewer Checklist](docs/reviewer-checklist.md), which covers code implementation, unit test coverage, CI build compatibility, API reference documentation, security/compliance, and acceptance criteria.
-
-### Acceptance Criteria Traceability
-Every PR **must** include an [acceptance criteria traceability table](docs/acceptance-criteria-traceability.md) that maps SDK modules, tests, docs, and behaviour verification to each acceptance criterion from the linked issue. This makes evaluation straightforward for maintainers and GrantFox reviewers.
-
+See [Verification Command](docs/verification.md) for detailed usage and
+troubleshooting guidance.
+
+See [Runtime Compatibility](docs/runtime-compatibility.md) for the supported
+environments, what the automated probes cover, and integration guidance.
+
+For step-by-step instructions on reproducing and fixing CI check failures, see the [CI Resolution Workflow](docs/ci-resolution-workflow.md).
+
+## Contributing
+We welcome contributions! Please check our [CONTRIBUTING.md](CONTRIBUTING.md) for our branching strategy and code style guidelines.
+
+### Review Process
+PRs submitted to this repository are reviewed against our [Pull Request Reviewer Checklist](docs/reviewer-checklist.md), which covers code implementation, unit test coverage, CI build compatibility, API reference documentation, security/compliance, and acceptance criteria.
+
+### Acceptance Criteria Traceability
+Every PR **must** include an [acceptance criteria traceability table](docs/acceptance-criteria-traceability.md) that maps SDK modules, tests, docs, and behaviour verification to each acceptance criterion from the linked issue. This makes evaluation straightforward for maintainers and GrantFox reviewers.
+

docs/ci-pass-requirements.md

@@ -0,0 +1,56 @@
+# CI Pass Requirements
+
+Aegis SDK pull requests are evaluated only after the required CI checks are green or an unrelated infrastructure failure is clearly documented. Failing CI can delay review, affect campaign or maintainer evaluation, and prevent approval until the author resolves the failure.
+
+## Required Passing Checks
+
+Before requesting review, contributors are expected to make these checks pass locally and in GitHub Actions:
+
+| Check | Local command | Required evidence |
+| --- | --- | --- |
+| Lint | `npm run lint` | No ESLint errors in SDK source files. |
+| Format | `npm run format` | Formatting applied or no formatting diff remains. |
+| Build | `npm run build` | TypeScript emits without type errors. |
+| Unit tests | `npm test -- --runInBand` | All focused and existing Jest tests pass. |
+| Runtime compatibility | `npm run test:compat` | Package exports work in supported runtimes. |
+| Full verification | `npm run verify` | The complete pre-submit gate finishes successfully. |
+
+If the CI workflow uses a narrower command than `npm run verify`, the PR should still include the broader local verification output or explain why a docs-only/no-code change does not need it.
+
+## Common Failure Types
+
+- **TypeScript build failures:** usually missing exports, changed method signatures, or mock data no longer matching SDK types.
+- **Unit test failures:** usually unhandled negative paths, changed receipt shapes, or mocks that do not represent the new behavior.
+- **Runtime compatibility failures:** usually Node/browser API assumptions, package export drift, or missing generated `dist` artifacts.
+- **Lint or format failures:** usually unused imports, inconsistent formatting, or generated edits that were not reviewed.
+- **Dependency failures:** usually lockfile drift, unsupported Node versions, or install scripts that do not match CI.
+- **Documentation-link failures:** usually renamed docs without updating README, CONTRIBUTING, or related cross-links.
+
+## Contributor Fix Expectations
+
+When a check fails, the contributor should:
+
+1. Open the failing GitHub Actions log and identify the exact failed command.
+2. Reproduce the failure locally with the matching command.
+3. Push a focused fix instead of broad unrelated cleanup.
+4. Re-run the focused command and then the full verification gate.
+5. Update the PR description or a comment with the new passing command output.
+
+A failure should not be ignored because the changed files look unrelated. If the failure is truly external to the PR, document the evidence: failed job URL, failing step, why the branch did not cause it, and whether a rerun was requested.
+
+## Reviewer Responsibilities
+
+Reviewers should verify that:
+
+- CI is green before approval, or any external failure is explained with a concrete log link.
+- The commands reported in the PR match the changed files and acceptance criteria.
+- Tests cover both the expected success behavior and one meaningful failure mode when runtime behavior changes.
+- Docs-only or metadata-only PRs include a valid no-test justification.
+- A PR with failing required checks is returned for correction before merge.
+
+## Related Guides
+
+- [CI Failure Resolution Workflow](ci-resolution-workflow.md)
+- [Failing CI Response Guide](ci-response-guide.md)
+- [Verification Command](verification.md)
+- [Pull Request Evidence Checklist](pr-evidence-checklist.md)