{"slug":"business/CLAUDE","title":"IntegrateWise — Working Contract","section":"business","sectionLabel":"Business","status":"unclassified","type":"document","path":"business/CLAUDE.mdx","bytes":9133,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\nThis repository is the IntegrateWise platform. The canonical architecture is frozen.\n\nRead [`AGENTS.md`](AGENTS.md) and [`docs/architecture/ARCHITECTURE_LOCK.md`](docs/architecture/ARCHITECTURE_LOCK.md) before changing product or platform code. If any local document conflicts with the architecture lock, the lock wins.\n\n## Product rules\n\n- The product is **IntegrateWise**: Onboarding, one User Workbench, and a Silent Twin.\n- The Workbench is one surface. Never expose `L1`, `L2`, `L4`, or `L7` in user-facing UI.\n- Twin is a contextual capability, not a persistent panel or sidebar destination. It is silent by default and never acts without explicit approval.\n- The four user controls are: **Store in Spine**, **Ask your Twin**, **Assign your Twin**, and **Approve Twin's Action**.\n- The Workbench is built from three user primitives: **Tables**, **Views**, and **Docs**.\n- The frontend knows only: `Entity`, `Projection`, `Capability`, `Signal`, `Context`, `Doc`, and `Twin`.\n\n### Product vocabulary maps to kernel vocabulary\n\nUsers say Tables, Views and Docs. The system says Entity, Projection and Doc.\nTwo of these are the same thing named for the person using it; one is new.\n\n| User primitive | Kernel term  | Status                                                                                                                                                                                      |\n| -------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **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.                                                                 |\n| **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.  |\n| **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. |\n\n`Doc` is a new kernel concept and therefore a **major version** under the\nversioning rules below. It adds a write path that did not previously exist:\n\n```text\nDoc → Twin proposal → governed structure → Spine\n```\n\nThat path is Flow C and inherits every Flow C constraint: it never writes\noperational truth directly, the proposed structure is reviewed by a human, and\npromotion runs through the governed writer. A decision captured in a Doc becomes\na decision record only after approval — never on save.\n\n## Platform rules\n\n- Spine is the single source of operational truth. Memory may inform truth but does not replace it.\n- Preserve the frozen runtime sequence:\n  `Configuration → Integration → Pipeline → Adaptive Spine → Workbench Composition → Continuity Bridge → User Workbench → Twin → Capability → Governance → Hermes → Sync → Promotion`.\n- Governance is a hard gate. No approval token means no external mutation.\n- Add capability implementations to the Capability Fabric; do not duplicate tools in the Workbench.\n- Use TypeScript and Node.js in the product path. Do not introduce retired infrastructure or new platform concepts.\n\n## Current implementation boundaries\n\n- `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.\n- `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.\n- 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.\n- 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.\n- 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.\n- 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.\n\n## Deployment rules\n\n- This repository deploys the platform to Cloudflare Workers. Do not treat it as a Vercel microfrontend repository.\n- Deployment surfaces are fixed: local `dev`, demo `test`, and live `prod`. Use `--env prod`; `production` is an alias only.\n- Test and prod must never share KV namespaces, Queues, or D1 databases.\n- 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`.\n- The MCP Connector must remain isolated as `mcp-connector-test` and `mcp-connector-prod`.\n- Run `pnpm release:check -- --environment test` before a release.\n- 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.\n- 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.\n- Use `pnpm release:deploy -- --environment test --service core` for remote test deployment.\n- 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.\n- Package immutable committed source with `pnpm release:package -- --ref <commit-or-tag>`.\n\nThe detailed release procedure is in [`docs/operations/PACKAGE_AND_DEPLOYMENT.md`](docs/operations/PACKAGE_AND_DEPLOYMENT.md).\n\n## Public package rules\n\n- The current publishable packages are `@integratewise/sdk` and `@integratewise/spine-schema`; services and implementation packages remain private deployment units.\n- 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.\n- Frontends use the SDK only through the Gateway's server-owned capability manifest: resolve → prepare immutable plan → explicitly approve. Never expose direct provider execution.\n- 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.\n\n## Change discipline\n\n- Start with `git status --short`; preserve unrelated user changes.\n- Keep user-visible wording in platform vocabulary. Do not propagate stale terms such as legacy UI layers or retired product names.\n- Keep authentication, platform, deployment, and marketing changes in focused commits when possible.\n- 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.\n- Keep release evidence current in `docs/operations/GO_LIVE_AND_GTM_PLAN.md`; it is a go/no-go record, not launch marketing copy.\n\n## GStack Engineering Operating System (SDLC)\n\nAll work follows the Garry Tan / YC **GStack 7-Stage Lifecycle**:\n\n```text\nThink (/office-hours) ➔ Plan (/plan-ceo-review, /plan-eng-review) ➔ Build (/build) ➔ Review (/review, /security-audit) ➔ Test (/qa) ➔ Ship (/ship) ➔ Reflect (/reflect)\n```\n\n1. **Think (`/office-hours`)**: Interrogate product problem, wedge, and user persona before touching code.\n2. **Plan (`/plan-ceo-review`, `/plan-eng-review`)**: Lock architecture, contracts, and schema boundaries to prevent hallucinations.\n3. **Build (`/build`)**: Strict TypeScript, zero `any`, zero-trust boundaries, and modular components.\n4. **Review (`/review`, `/security-audit`)**: Rigorous code quality, tenant isolation (`tenant_id`), and SAIF compliance audit.\n5. **Test (`/qa`)**: Browser-first verification and 100% automated test suite passing (`pnpm test`).\n6. **Ship (`/ship`)**: Full monorepo build verification (`pnpm build`) and clean deployment gating.\n7. **Reflect (`/reflect`)**: Post-ship synthesis and memory promotion to Fortress Spine.\n"}