Unclassified

IntegrateWise — Working Contract

This repository is the IntegrateWise platform. The canonical architecture is frozen.

Read AGENTS.md and docs/architecture/ARCHITECTURE_LOCK.md before changing product or platform code. If any local document conflicts with the architecture lock, the lock wins.

Product rules

The product is IntegrateWise: Onboarding, one User Workbench, and a Silent Twin.
The Workbench is one surface. Never expose L1, L2, L4, or L7 in user-facing UI.
Twin is a contextual capability, not a persistent panel or sidebar destination. It is silent by default and never acts without explicit approval.
The four user controls are: Store in Spine, Ask your Twin, Assign your Twin, and Approve Twin's Action.
The Workbench is built from three user primitives: Tables, Views, and Docs.
The frontend knows only: Entity, Projection, Capability, Signal, Context, Doc, and Twin.

Product vocabulary maps to kernel vocabulary

Users say Tables, Views and Docs. The system says Entity, Projection and Doc.
Two of these are the same thing named for the person using it; one is new.

User primitive	Kernel term	Status
Table	`Entity`	Renamed at the surface. A Table is the structured face of Spine entities of one type. Not a database view, not a new store.
View	`Projection`	Renamed at the surface. A View is a Projection — "the role-specific projection of work and context presented to a human". Do not introduce a `View` type alongside `Projection` in code.
Doc	`Doc`	New primitive. No existing kernel term covers an authored narrative artifact bound to entities. Flow B ingests documents as evidence; a Doc is authored in the product and writes back.

Doc is a new kernel concept and therefore a major version under the
versioning rules below. It adds a write path that did not previously exist:

Doc → Twin proposal → governed structure → Spine

That path is Flow C and inherits every Flow C constraint: it never writes
operational truth directly, the proposed structure is reviewed by a human, and
promotion runs through the governed writer. A decision captured in a Doc becomes
a decision record only after approval — never on save.

Platform rules

Spine is the single source of operational truth. Memory may inform truth but does not replace it.
Preserve the frozen runtime sequence:
Configuration → Integration → Pipeline → Adaptive Spine → Workbench Composition → Continuity Bridge → User Workbench → Twin → Capability → Governance → Hermes → Sync → Promotion.
Governance is a hard gate. No approval token means no external mutation.
Add capability implementations to the Capability Fabric; do not duplicate tools in the Workbench.
Use TypeScript and Node.js in the product path. Do not introduce retired infrastructure or new platform concepts.

Current implementation boundaries

apps/web is a Next.js App Router application with a static export for Cloudflare Pages. Add active page entry points under apps/web/src/app/; keep all data access behind the Gateway.
apps/web/src/legacy-pages/ contains retained legacy React Router screens during the migration. Do not add new product routes there; migrate or compose them through the App Router instead.
Authentication entry points are provider-specific behind the shared auth provider. Keep provider selection and public environment values in the documented web configuration; never hard-code credentials or direct browser-to-database access.
Workbench projections and activities are tenant- and actor-scoped. The browser accesses canonical workbench data through the Gateway, which forwards trusted identity headers to the Spine service.
External integrations are Gateway-managed connections. OAuth initiation, connection state, MCP-server registration, and provider actions must remain permission-checked and auditable; they are not direct client-side provider calls.
The canonical Neon Workbench routes live in services/spine/src/neon-workbench.ts. Preserve their tenant and actor requirements, bounded request handling, and Spine provenance when extending the projection.

Deployment rules

This repository deploys the platform to Cloudflare Workers. Do not treat it as a Vercel microfrontend repository.
Deployment surfaces are fixed: local dev, demo test, and live prod. Use --env prod; production is an alias only.
Test and prod must never share KV namespaces, Queues, or D1 databases.
Test and prod must also use distinct R2, Vectorize, Durable Object, secret-store, and service-binding targets. Do not make a warning disappear by copying a production binding into env.test.
The MCP Connector must remain isolated as mcp-connector-test and mcp-connector-prod.
Run pnpm release:check -- --environment test before a release.
The only CI Worker publication path is Release Core Workers (.github/workflows/deploy-workers.yml). It is manually dispatched, test-first, runs the canonical core order, and deploys Gateway last. Do not add a push-triggered, parallel, or direct-wrangler Worker workflow.
Run pnpm release:deploy -- --environment test --service core --dry-run after binding changes. A non-dry release is blocked until every core Worker preflight has zero Wrangler warnings and the isolated-binding inventory is reviewed.
Use pnpm release:deploy -- --environment test --service core for remote test deployment.
Production requires --confirm-production, CLOUDFLARE_API_TOKEN, and CI (or ALLOW_LOCAL_PROD_DEPLOY=true after explicit approval). Do not bypass Wrangler warnings without explicit operational approval.
Package immutable committed source with pnpm release:package -- --ref <commit-or-tag>.

The detailed release procedure is in docs/operations/PACKAGE_AND_DEPLOYMENT.md.

Public package rules

The current publishable packages are @integratewise/sdk and @integratewise/spine-schema; services and implementation packages remain private deployment units.
The public, read-only catalogue lives at /api/v1/platform, /packages, /services, /endpoints, and /openapi.json. It may describe Gateway contracts but must never reveal Worker bindings, direct service addresses, provider credentials, or tenant connection details.
Frontends use the SDK only through the Gateway's server-owned capability manifest: resolve → prepare immutable plan → explicitly approve. Never expose direct provider execution.
Run pnpm release:packages:check before publishing. pnpm release:packages:publish requires a clean committed worktree, npm authentication, and a new semver version; it will not overwrite an existing package version.

Change discipline

Start with git status --short; preserve unrelated user changes.
Keep user-visible wording in platform vocabulary. Do not propagate stale terms such as legacy UI layers or retired product names.
Keep authentication, platform, deployment, and marketing changes in focused commits when possible.
Validate the smallest relevant surface before handing work off. For deployment changes, run shell syntax checks, JSON parsing, release-surface validation, and non-publishing Wrangler dry-runs.
Keep release evidence current in docs/operations/GO_LIVE_AND_GTM_PLAN.md; it is a go/no-go record, not launch marketing copy.

GStack Engineering Operating System (SDLC)

All work follows the Garry Tan / YC GStack 7-Stage Lifecycle:

Think (/office-hours) ➔ Plan (/plan-ceo-review, /plan-eng-review) ➔ Build (/build) ➔ Review (/review, /security-audit) ➔ Test (/qa) ➔ Ship (/ship) ➔ Reflect (/reflect)

Think (/office-hours): Interrogate product problem, wedge, and user persona before touching code.
Plan (/plan-ceo-review, /plan-eng-review): Lock architecture, contracts, and schema boundaries to prevent hallucinations.
Build (/build): Strict TypeScript, zero any, zero-trust boundaries, and modular components.
Review (/review, /security-audit): Rigorous code quality, tenant isolation (tenant_id), and SAIF compliance audit.
Test (/qa): Browser-first verification and 100% automated test suite passing (pnpm test).
Ship (/ship): Full monorepo build verification (pnpm build) and clean deployment gating.
Reflect (/reflect): Post-ship synthesis and memory promotion to Fortress Spine.