docs(readme): clarify verification and resume contracts

[cursor]

🧠 Noēsis Pull Request

Overview

Clarifies the README sections for workspace verification, terminal vs paused artifact contracts, and pause/checkpoint/resume lifecycle behavior. Also fixes a broken code fence in the minimal example so the landing page renders correctly.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

Recent runtime work tightened verification, artifact sealing, and same-run resume semantics. The top-level README had a malformed verification/lifecycle block and implied every run immediately writes sealed terminal artifacts, which is inaccurate for paused runs.

Technical Details

Docs added/updated:

• Updated README.md intro and "What Noēsis does" artifact wording.
• Added a concrete verify=... example with file_exists, file_contains, only_modified, and no_modifications constraints.
• Replaced the malformed artifact/lifecycle block with terminal-vs-paused artifact guidance and interrupt/checkpoint/resume rules.
• Closed the minimal example code fence before the "How it works" section.

Codepaths covered:

• Public verification helpers from noesis/verification.py and noesis/__init__.py.
• Lifecycle APIs from noesis/core.py and noesis/usecases/run_lifecycle.py.
• Checkpoint contract fields and resume errors from noesis/domain/run_lifecycle.py.

Key knowledge gaps addressed:

• Which verification constraints developers can use and what they mean.
• Which artifacts are sealed only for terminal runs versus absent while paused.
• Difference between resume() evidence-only behavior and resume_run() continuation.
• Common resume failure causes: sealed runs, stale/missing checkpoints, and adapter mismatch.

Validation

Required

• Equivalent targeted docs checks: git diff --check and README fenced-code/section validation script
• Schema validation and export diff clean (not applicable; documentation-only README change with no schema changes)

Situational

• Docs build successfully (pnpm run build in docs/) (not run; README-only change outside Mintlify docs app)

ADR-003 Schema Governance Checklist

• $schema_version bumped for every artifact whose stable fields changed (not applicable)
• docs/schema/** regenerated (not applicable)
• KPI updates include version bumps plus math/clamp/rationale updates in internal_docs/schema/kpi*.yaml (not applicable)
• Relevant entry added to MIGRATIONS.schema.md or MIGRATIONS.kpi.md (not applicable)
• python scripts/schema_guard.py --strict --json passes locally (not applicable)
• Docs under docs/app/reference/* updated when new fields/KPIs surface to users (not applicable)

Observability & Safety

No runtime behavior changed. The docs now call out artifact sealing and resume constraints more precisely.

Screenshots / Logs

README checks passed

Related Issues / References

Automated weekly technical documentation refresh.