Updated Nick's Notes

[nickbeau]

This pull request significantly revises and expands both the operating contract for contributors (AGENTS.md) and the product requirements (docs/requirements.md). The changes clarify project boundaries, strengthen security and architecture guardrails, and provide much more detailed, actionable standards for persistence, security, and operational practices. These updates ensure that all contributors have a clear, enforceable framework for safe, auditable, and maintainable development.

Key changes include:

1. Project Governance and Contribution Standards

• AGENTS.md is rewritten to clearly separate the main product (test mining platform) from retained tooling (Symphony), requiring every PR to declare its target and to split cross-boundary changes. It introduces explicit sections for mission, sources of truth, non-negotiable guardrails, architecture rules, coding standards, security hygiene, testing, configuration, observability, delivery workflow, and escalation procedures.

2. Persistence and Database Requirements

• The product requirements now specify PostgreSQL as the only required database provider for v1, with SQL Server support deferred but not blocked. Provider-specific features are allowed in v1 if future portability is considered. Integration tests must use real PostgreSQL, not in-memory providers.
• All persistent entities must include common fields for audit, concurrency, and soft-deletion, with detailed rules for each.
• A new UserAccount entity is defined, and all audit references must resolve to this entity.

3. Security and Data Protection

• Strict guardrails are introduced: never log, persist, or emit secrets; enforce allow-lists for target URLs; require encryption at rest for sensitive material; and prohibit hand-editing of generated code. [1] [2]
• Detailed requirements for encryption and masking of sensitive data are added, including retroactive masking if a field's classification changes.

4. Artefact Retention and Cleanup

• Artefact storage is now governed by explicit retention windows and size caps (e.g., screenshots retained for 30 days, capped at 10 MB), with administrative override possible. A background process will enforce cleanup and audit deletions.

5. Human Approval and AI Guardrails

• Healing proposals that alter persisted scenarios must always require human approval in v1; auto-apply policies are deferred and heavily restricted for future versions.

6. Operational Metrics and Performance Targets

• Performance targets are now precise (e.g., p50/p95 latencies for key operations), and observability requirements ensure these can be measured and verified in production.

These changes collectively raise the bar for safety, auditability, and clarity in both code and process, and should be carefully reviewed by all contributors.

[Copilot]

Pull request overview

This PR updates the repository’s contributor operating contract (AGENTS.md) and the product requirements spec (docs/requirements.md) to more explicitly define repository boundaries (platform vs. retained Symphony tooling), and to tighten security, persistence, and operational guardrails for the test mining platform.

Changes:

• Rewrites AGENTS.md to establish governance, guardrails, architecture boundaries, and workflow expectations for contributors.
• Expands docs/requirements.md with a v1 persistence/provider strategy (PostgreSQL-first), common entity requirements, security/encryption/URL allow-list requirements, retention policies, and more explicit exit/acceptance criteria.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
docs/requirements.md	Extends/clarifies product requirements across persistence strategy, security controls, retention policies, and acceptance/exit criteria.
AGENTS.md	Replaces the prior Symphony-focused guidance with a platform-focused operating contract and cross-boundary contribution rules.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.