From 1f1fff569ea218436343ce7b6004e451cf2b99bb Mon Sep 17 00:00:00 2001 From: DJConnect Date: Thu, 17 Sep 2026 15:08:02 +0200 Subject: [PATCH 1/2] docs: complete project onboarding for Genesis Managed and promotion (NO_BUMP) --- BOOTSTRAP.md | 12 ++ docs/PROJECT_BOOTSTRAP_V1.md | 90 +++++++++++++ docs/PROJECT_BOOTSTRAP_V1_DAG.json | 19 +++ docs/PROJECT_BOOTSTRAP_V1_ROADMAP.md | 22 ++++ docs/REPOSITORY_ONBOARDING.md | 181 ++++++--------------------- 5 files changed, 182 insertions(+), 142 deletions(-) create mode 100644 docs/PROJECT_BOOTSTRAP_V1.md create mode 100644 docs/PROJECT_BOOTSTRAP_V1_DAG.json create mode 100644 docs/PROJECT_BOOTSTRAP_V1_ROADMAP.md diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index e064206..79ec898 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -1,5 +1,17 @@ # Workspace Bootstrap +## New-project bootstrap and promotion design + +Read [Project bootstrap V1](docs/PROJECT_BOOTSTRAP_V1.md), the reconciled +[repository onboarding contract](docs/REPOSITORY_ONBOARDING.md), +[scoped roadmap](docs/PROJECT_BOOTSTRAP_V1_ROADMAP.md) and +[documentary DAG](docs/PROJECT_BOOTSTRAP_V1_DAG.json) for both Genesis and +Managed project creation/adoption, plus explicit history-preserving promotion. +The design consumes Forge's exact artifact manifest and EP's qualified +operation/readback contracts through HTTP. All PB-W runtime nodes remain +PLANNED. This does not implement a UI, create a project/Mission, activate +permissions, change package versions or add a Mission-3 prerequisite. + ## Current pickup checkpoint — consolidation and parking, 10 September 2026 Read the [owning parking record](docs/CONSOLIDATION_PARKING_2026_09_10.md) and diff --git a/docs/PROJECT_BOOTSTRAP_V1.md b/docs/PROJECT_BOOTSTRAP_V1.md new file mode 100644 index 0000000..c0c0890 --- /dev/null +++ b/docs/PROJECT_BOOTSTRAP_V1.md @@ -0,0 +1,90 @@ +# Project bootstrap V1 — Workspace experience and contracts + +**Increment:** `PROJECT_BOOTSTRAP_AND_ARTIFACT_MANIFEST_V1`. **Owner:** Workspace. +**Status:** canonical target design after protected merge; implementation/installed UI qualification **PLANNED**. **NO_BUMP.** + +This refines [repository onboarding](REPOSITORY_ONBOARDING.md) and the onboarding/control-plane lane in the [Workspace roadmap](../ROADMAP.md). See [scoped roadmap](PROJECT_BOOTSTRAP_V1_ROADMAP.md) and [documentary DAG](PROJECT_BOOTSTRAP_V1_DAG.json). Forge owns the detailed portable artifact manifest at `pcvantol/forge:docs/architecture/PROJECT_BOOTSTRAP_AND_ARTIFACT_MANIFEST_V1.md`; EP owns execution/provisioning at `pcvantol/engineering-platform:docs/engineering/PROJECT_BOOTSTRAP_EXECUTION_V1.md`. The shared PB-01..PB-40 catalogue resides with Forge. Workspace does not create a competing artifact schema or bootstrap state machine. + +Source basis on 2026-09-17: Workspace `92da171c97dc3f67cc844125b08cf8a2a0e56a1e`, Forge `eee7f8dadd5b2df9e836627b43de4928a46eeb35`, EP `d7fe0af363fb36f1f819fedc7a63919e01b88e66`. Existing Forge storage-init is not a project scaffolder. Existing EP Genesis and B8R attachment are reusable foundations, not proof that this complete UI/API journey exists. No runtime, grant, installation or Mission is changed by this design. + +## 1. Five distinct journeys, not a single ambiguous Init button + +| User choice | What the user selects | Owning outcome and important restriction | +| --- | --- | --- | +| New local Genesis project | Product purpose and an eligible host's missing/empty local target, or unborn local Git | Common project/engineering foundation with local Git evidence; no remote contact/publication | +| Adopt local Genesis work | Existing local target and explicit content/identity adoption | Preserve existing work/history; unknown ownership or dirty content must be resolved before mutation | +| New Managed project | Repository provider, owner/namespace, name and explicit visibility | Qualified remote birth and governance, not merely a successful create API response | +| Adopt Managed repository | Existing remote identity, project mapping and intended checkout attachment | Drift preview and protected adoption; never treat a README-only repository as empty | +| Promote Genesis to Managed | Existing local project plus explicit destination/publication decision | Same IDs/history with remote governance and attachment proof; no silent mode flag change | + +A qualification-only purpose is separately identified with explicit retention/deletion authority. It is not the default project type and is not automatically disposable. Mode, Governance Profile, technology template and autonomy/release settings are separate fields. No automatic fallback between Genesis and Managed when a remote/tool/credential is unavailable. + +## 2. Application boundary and supported capabilities + +Workspace Client talks to Workspace Server over authenticated HTTP. Workspace Server talks to Forge for product planning/governance and directly to EP for EP-owned provisioning/attachment/effects as applicable to the accepted workflow. It never shells to either peer, reads their databases, writes a checkout or implements its own GitHub executor. Browser clients receive no reusable peer or repository-host credentials. + +At session start query the versioned capability inventory and exact peer instance/project scope. A button is offered only when its owning operation is supported and authorized; unavailable capability is shown explicitly, not a private endpoint guess. Thin CLI and HTTP target equivalent owning services, but local-only administration is not automatically remotely exposed. Browser init of a new project is distinct from server storage/installation initialization. + +Workspace persists only its own draft/conversation/preferences and references to owning plans, decisions and operation results. Source truth for portable identity remains EP's committed `.engineering-platform/repository.json`; display names do not allocate that identity. Forge's artifact mapping references it. Reservations before the first commit are visibly provisional, not registered canonical topology. Draft creation or viewing a sample doesn't allocate a Mission. + +## 3. Guided flow and exact review model + +### Step A — Describe the product + +Collect purpose, intended users, desired outcome, non-goals, constraints, existing assets and important unknowns. Offer optional Solution Templates as advisory starting points, not already-approved Missions or implementation. Separate user statements from inferred suggestions and approved decisions. Do not require the user to fabricate an entire finished architecture just to save a draft. + +Choose the authority repository relationship and any child repository mappings. Reuse matching existing identity only after owning verification. Creating a fork/new product is an explicit separate choice, not automatic adoption of copied declarations. Show that a child repo receives its own contract/declaration while referencing authority-owned Vision/roadmap. + +### Step B — Choose Genesis or Managed and target + +For Genesis, explain local-only effects and identify the actual eligible EP host/placement. A browser's current directory or arbitrary client upload path is not the host target. Use an owning scoped inventory/file-selection capability; restrict returned path detail to the authorized operator and keep it out of portable repo artifacts. Distinguish absent, empty, unborn, existing, dirty, nested or occupied targets. Any existing remote is disclosed but not contacted or modified by a Genesis operation. + +For Managed, require explicit provider account/namespace/name/visibility; no implicit public repository. Validate actual resource identity and distinguish missing/unborn from existing history. Show denied scopes or unsupported mandatory provider features before submitting effects. Do not expose a generic admin credential or ask users to paste bearer values into project forms. + +### Step C — Profiles and contract + +Show installed baseline version/hash/provenance, supported stack options, artifact mapping, effective validation/assurance and repo-governance profile. Describe inherited versus project-specific policy and exceptions. Optional license choice is explicit; no default legal/publication decision. Genesis still has local engineering safeguards; remote controls read NOT_APPLICABLE_GENESIS, not green PASS. Unsupported required local checks remain blockers. + +The default project behaviour is governed Mission selection. The three project-autonomy modes from the existing live-roadmap design remain explicit: per-Mission release; execute a bounded approved workset; delegated full autonomy within a separately authorized boundary. Recommended priority is not committed priority. Selecting a template, importing a repo or choosing auto-when-eligible doesn't grant new approvals. Bootstrap never enables autonomous reviewer-driven follow-up work. + +### Step D — Review a frozen plan + +Render a before/after artifact tree and per-file diff, plus a separate remote-settings diff. Use Forge's canonical manifest as the sole file selection source. Show required/common versus conditional assets, existing equivalent mapped paths, before hashes/ABSENT, output digests, affected permissions/refs, prospective ID mapping and unresolved decisions. Typical common documents are README/BOOTSTRAP/AGENTS, product Vision, architecture, roadmap/DAG and portable engineering/baseline contracts; the detail view derives the actual paths from the versioned plan rather than hardcoding a second template list. + +Surface whether an artifact is project-owned, immutable pinned baseline or source-bound projection. Existing differing documents aren't marked safe to overwrite merely because generated versions exist. Preserve unrelated dirty/staged/untracked work; let the owner resolve a blocked preparation instead of auto-stash/commit/delete. No raw secrets or unbounded file contents in previews. + +Approvals bind the exact plan digest/revision and classified effect set. Route product direction to Business/Architecture and resource creation/publication to the actual provisioning authority. One user can hold multiple authorized roles, but the distinct decisions remain recorded. Do not turn local draft acceptance or chat affirmation into an owner receipt. Changing target, visibility, history refs, baseline, plan bytes or material policy invalidates incompatible approval and requires refreshed review. + +### Step E — Submit and track + +Submit the existing frozen operation with stable idempotency/correlation identity and expected revision. Disable duplicate UI submission as a convenience, not as the sole duplicate-effect protection. After reconnect/lost response, read the same owning operation; never start a second request with a new key to resolve uncertainty. + +The activity view shows selected mode, reserved versus committed identity, plan version, actual stage/effects, receipts, authorizations, blockers and safe next actions. Physical mutation, repository-governance qualification, attachment availability and Forge project readiness are separate. ACCEPTED/HTTP 200 is not READY; technical completion is not Mission acceptance. Polling/events carry scoped cursor/snapshot and freshness; stale projections cannot enable mutation controls. + +### Step F — Enter the project + +After owning readback, show the exact canonical local/remote repository, materialized contract/baseline and verified readiness vector. Genesis shows local commit/reconciliation, not PR/remote-CI badges. Managed shows actual remote/governance/check evidence. Remaining product questions and advisory Candidates are visible. The next action is refine/select/approve a Mission via the existing separate lifecycle, not automatic feature execution. + +## 4. Genesis-to-Managed promotion is an explicit wizard + +Promotion begins from the existing Genesis project, not a new-product form. Display stable IDs, current local HEAD/refs, destination and expected remote state. Explain that publication can disclose all selected historical commits, not just the current file tree. Require scope-appropriate confirmation of visibility, licensing and sensitive-history findings before any push. Ignore rules do not prove old commits safe. + +Show the proposed retained ancestry, new Managed CI/security/settings artifacts and resulting policy change separately. A diverged/unrelated existing remote is a conflict; no UI 'continue' may authorize implicit force push or squash of history. Required history rewrite or data disposal is a separately reviewed migration. Display actual owning quiescence/fence and current operation, not a local UI lock as proof that no writers exist. + +Track remote transfer, real governance readback, attachment and Forge mode activation. Do not switch the project badge to Managed on request acceptance or first push. During uncertainty, disclose effects already observed and keep applicable editing/execution controls fenced. Cancel after a push is a cancellation request, not a claim the remote data has been undisclosed. Existing Genesis history remains available with original mode/qualification; no manufactured historic PRs or reset approvals. + +Recovery offers read/reconcile or a separately authorized corrective plan from the owner service. It does not run local SQL, delete the remote or restart a second project. A safely reconciled incomplete promotion may leave the same project in Genesis with the partial remote effect recorded. + +## 5. Error, security and accessibility contract + +Provide meaningful empty/loading/unsupported/offline/denied/stale/conflict/partial/failed/cancel-pending states for every step. Preserve the user's draft and references when an owner is unavailable, but don't replace its state with optimistic local success. Explain who owns the blocker and which actions are currently authorized. Do not translate machine IDs/enums in exported machine data; translate human labels/explanations in en/nl/de/fr/es. + +Use accessible labelled controls, keyboard review/approval, focus restoration after async updates, screen-reader announcements for meaningful stage changes and responsive desktop/mobile artifact diffs. Avoid colour-only status and default selections that conceal destructive/public effects. Long trees/diffs are bounded/paginated with visible completeness, stable snapshot and safe download. Tests include stale tab, double-click, filter/target change during response, expired session and cross-project access denial. + +Document/export views use the owning operation's exact snapshot, mode and provenance. No endpoint, host placement, credential or confidential history is included merely because it is available to the server. Bootstrap telemetry is operation-scoped and separate from subsequent Mission usage. New findings become proposals; a security block cannot silently authorize a new remediation Mission. + +## 6. Qualification and delivery boundary + +Workspace PB-WQ tests the actual installed Client/Server and real HTTP boundaries to qualified owner slices, plus controlled denied/partial/replay fixtures. It does not claim installed Forge/EP capability from mocks alone. Qualify all five journeys, blueprint changes invalidating approvals, no secondary template/identity authority, history-safe promotion and all user-visible states on desktop/mobile/five locales. PB-33..PB-35 are UX-focused families; PB-22..PB-32 and PB-36..PB-40 provide cross-product guardrails. + +The current update supplies design, scoped roadmap and documentary DAG only. No buttons, endpoints, database, permissions, policies, provider work, repository creation, runtime service, version or Mission 3 change is implemented. Workspace remains optional for headless Forge/EP bootstrap, and this programme is not added before the current inner-Mission canary. diff --git a/docs/PROJECT_BOOTSTRAP_V1_DAG.json b/docs/PROJECT_BOOTSTRAP_V1_DAG.json new file mode 100644 index 0000000..87d77e1 --- /dev/null +++ b/docs/PROJECT_BOOTSTRAP_V1_DAG.json @@ -0,0 +1,19 @@ +{ + "schema_version":"1.0", + "increment":"PROJECT_BOOTSTRAP_AND_ARTIFACT_MANIFEST_V1", + "owner":"workspace", + "authority":"DOCUMENTARY_DERIVED", + "executable":false, + "version_decision":"NO_BUMP", + "parent_lanes":["ONBOARDING_CONTROL_PLANE_V1","FWV1-G003","FWV1-G013"], + "architecture":"docs/PROJECT_BOOTSTRAP_V1.md", + "current_mission_3_dependency":false, + "nodes":[ + {"id":"PB-W0","status":"PLANNED","depends_on":[],"deliverable":"Five-journey UX, role and owning capability contract"}, + {"id":"PB-W1","status":"PLANNED","depends_on":["PB-W0"],"external_evidence":["forge:PB-F0","engineering-platform:PB-E0"],"deliverable":"Typed Workspace HTTP adapters and safe draft references"}, + {"id":"PB-W2","status":"PLANNED","depends_on":["PB-W1"],"external_evidence":["forge:PB-F2","forge:PB-F7","engineering-platform:PB-E1"],"deliverable":"Genesis/Managed create/adopt and exact-plan decision UX"}, + {"id":"PB-W3","status":"PLANNED","depends_on":["PB-W1"],"external_evidence":["forge:PB-F4","forge:PB-F5","forge:PB-F7","engineering-platform:PB-E5"],"deliverable":"Mode-correct progress, recovery, readiness and exports"}, + {"id":"PB-W4","status":"PLANNED","depends_on":["PB-W2","PB-W3"],"external_evidence":["forge:PB-F6","engineering-platform:PB-E4"],"deliverable":"Explicit history-preserving Managed promotion UX"}, + {"id":"PB-WQ","status":"PLANNED","depends_on":["PB-W2","PB-W3","PB-W4"],"external_evidence":["forge:PB-FQ","engineering-platform:PB-EQ"],"deliverable":"Installed five-journey, accessibility and five-locale qualification"} + ] +} diff --git a/docs/PROJECT_BOOTSTRAP_V1_ROADMAP.md b/docs/PROJECT_BOOTSTRAP_V1_ROADMAP.md new file mode 100644 index 0000000..97abf44 --- /dev/null +++ b/docs/PROJECT_BOOTSTRAP_V1_ROADMAP.md @@ -0,0 +1,22 @@ +# Project bootstrap V1 — Workspace owning roadmap + +**Owner:** Workspace. **Status:** all runtime/qualification nodes PLANNED. **NO_BUMP.** +This is the scoped implementation decomposition of onboarding/control plane in [ROADMAP.md](../ROADMAP.md), refining [repository onboarding](REPOSITORY_ONBOARDING.md), not a second planner or EP console. Read [the complete design](PROJECT_BOOTSTRAP_V1.md) and [non-executable DAG](PROJECT_BOOTSTRAP_V1_DAG.json). + +| Node | Depends on | Deliverable / closure | +| --- | --- | --- | +| PB-W0 | none | Five-journey UX/intent contract, identity/reservation and owner/capability mapping | +| PB-W1 | PB-W0; Forge PB-F0 and EP PB-E0 contracts | Workspace Server's typed authorized HTTP projections/intents and safe draft storage; no peer CLI/SQL | +| PB-W2 | PB-W1; Forge PB-F2/PB-F7 and EP PB-E1 | Genesis/Managed create/adopt wizard with exact artifact/settings diff and role-bound plan decisions | +| PB-W3 | PB-W1; Forge PB-F4/PB-F5/PB-F7 and EP PB-E5 | Mode-correct progress/readiness, partial effects, recovery/readback and source-bound exports | +| PB-W4 | PB-W2, PB-W3; Forge PB-F6 and EP PB-E4 | History/publication-aware Genesis-to-Managed promotion, fenced activation and recovery UX | +| PB-WQ | PB-W2, PB-W3, PB-W4; qualified Forge PB-FQ and EP PB-EQ | Installed HTTP integration for all five journeys, desktop/mobile, five locales, accessibility and negative authority cases | + +PB-W0/W1 can advance contract-first without runtime services being complete; delivered user actions remain gated by actual compatible owner capabilities. Workspace qualification consumes peer evidence but is not a prerequisite of Forge PB-FQ or EP PB-EQ. The documentary DAG allocates Workspace work only; owner roadmaps decide peer implementation status and order. + +Companions: +- Forge `docs/roadmap/PROJECT_BOOTSTRAP_V1.md` and `docs/roadmap/project-bootstrap-v1.json`. +- EP `docs/development/PROJECT_BOOTSTRAP_V1_ROADMAP.md` and `docs/development/PROJECT_BOOTSTRAP_V1_DAG.json`. +- Shared scenario catalogue: Forge `docs/architecture/PROJECT_BOOTSTRAP_QUALIFICATION_V1.md`, PB-01..PB-40. + +All implementation is post-/parallel-autonomy productization as appropriate; no new edge blocks Mission 3. Design completion does not close FWV1-G003/G013 implementation or imply an installed onboarding UI. Existing policy/workset/priority authority remains unchanged. diff --git a/docs/REPOSITORY_ONBOARDING.md b/docs/REPOSITORY_ONBOARDING.md index c93273c..1e4e82f 100644 --- a/docs/REPOSITORY_ONBOARDING.md +++ b/docs/REPOSITORY_ONBOARDING.md @@ -1,144 +1,41 @@ # Workspace repository onboarding and qualification -## Status and purpose - -**Status: proposed.** This document is the canonical Workspace product design -for presenting and initiating project/repository onboarding. It records intent -and boundaries only. It does not establish an implemented Workspace UI, a -GitHub integration, an Engineering Platform (EP) protocol, an EP repository -schema, or permission to provision external resources. - -Workspace is the user- and project-control plane above Forge planning and EP -execution: it gives people one place to understand project topology and to -start permitted lifecycle actions. “Above” describes the user experience and -control-plane composition, never an authority to bypass Forge, CENTRAL, EP, or -the Project Agent. The product boundaries remain defined in -[Architecture](ARCHITECTURE.md), and sequencing remains in the -[roadmap](../ROADMAP.md). - -## Intended onboarding choices - -The planned Workspace onboarding surface offers these mutually distinct entry -points: - -| Choice | Planned outcome | Intended use | -| --- | --- | --- | -| **Use existing repository** | Register an already-existing GitHub repository in a logical project and request eligible Agent attachment. | Adopt an existing codebase without recreating its Git history. | -| **Create new repository** | Request governed GitHub provisioning, then register the created repository in the logical project. | Start a normal new repository under an approved owner/namespace. | -| **Genesis project** | Create a logical project and its initial canonical project/repository topology, then request an initial repository bootstrap. | Start a new product with no prior repository. | -| **Qualification-only repository** | Create or attach an explicitly disposable repository used solely for a bounded installed-product qualification. | Prove a route without attaching a canonical product repository. | - -The choices are plans, not current Workspace capabilities. A future product -decision must define their request/API model, the EP-owned repository contract, -supported GitHub settings, user roles, approval thresholds, retention, and -failure/recovery behavior. - -## Logical and physical authority - -The future flow separates a logical declaration from the physical host work. -This prevents a browser, a planner, or a local Agent from silently becoming the -authority for every concern. - -| Concern | Planned authority | Not the authority | -| --- | --- | --- | -| User-facing project/repository control and topology presentation | Workspace Server and Client | A local checkout or Project Agent | -| Cross-project planning, dependencies, and proposed lane intent | Forge | Workspace UI or a GitHub repository | -| Accepted project/repository intent, execution admission, durable lifecycle state, and EP evidence | EP CENTRAL / EP Server | Forge, Workspace, or a Project Agent | -| GitHub resource provisioning from accepted intent | A future governed CENTRAL-backed GitHub integration, with Workspace/Forge as permitted requesters | A Project Agent acting on its own initiative | -| Clone, checkout, worktree, local toolchain, provider-host readiness, and local credential use | EP Project Agent on the selected host | Workspace, Forge, or CENTRAL directly accessing the host filesystem | - -Workspace may initiate a permitted request and show its state. Forge may -produce the related plan. Neither may issue a direct Agent filesystem command, -admit an execution, allocate a repository lease, or turn a proposed repository -into a provisioned resource without the applicable CENTRAL decision and -operator controls. - -## Portable repository declaration - -The intended logical declaration is a portable, -repository-relative `.engineering-platform/repository.json`. It describes the -logical project/repository relationship that EP can consume when the repository -is attached. It must be safe to carry in Git and must not encode facts that -only make sense on one machine or in one installation. - -The eventual EP-owned schema may include stable logical identifiers, a -repository role, and non-secret source/provider references. It must not include -any of the following: - -- `server_url` or other CENTRAL endpoint/address; -- `agent_id` or host identity; -- `local_path`, clone path, worktree path, or IDE path; or -- credentials, access tokens, private keys, cookies, or other secrets. - -EP owns the schema and validation rules; this document does not define them. -Host attachment and credentials remain local Agent/secure-store concerns. -This boundary also allows a repository to move between eligible hosts without -rewriting a server- or machine-bound declaration. - -## Disposable qualification lifecycle - -A qualification-only repository is intentionally not a shortcut around -canonical project governance. Its planned lifecycle is: - -```text -explicit qualification purpose and scope - → approved create or attach request - → GitHub repository provisioned or verified - → portable logical declaration and project registration - → Project Agent clone/checkout/attachment and host preflight - → installed product qualification through the canonical route - → durable, redacted evidence and disposition recorded - → archive or delete under the approved retention policy -``` - -The qualification record must identify that the repository is disposable and -must retain the relevant logical identity, exact artifact/revision context, -outcome, and redacted evidence. It must not retain credentials or treat a -successful qualification as authorization to use the same repository as a -canonical product repository. Archive versus deletion, retention duration, and -any evidence export are future operator-policy decisions. - -## GitHub integration and operator governance - -GitHub is a future external resource provider, not a new project authority. -Before implementation, the owning product contracts must define: - -- who may request use, creation, archive, and deletion; -- which organization/account, namespace, visibility, naming, default-branch, - protection, and template choices are permitted; -- when a request needs explicit operator approval, including all destructive - disposal actions; -- how CENTRAL records idempotency, the accepted intent, provider result, and - redacted audit/evidence; and -- how failed, partially provisioned, or manually changed resources are shown - and recovered without guessing their authority. - -Workspace should show the request, approval, provisioning, attachment, and -qualification states clearly. It must not expose provider credentials to a -client, implement approval policy locally, or claim that a GitHub-side change -has succeeded until the governing service records it. - -## Relationship to project topology and lanes - -One logical project can have one canonical project authority repository and -zero or more child repositories. Workspace presents this multi-project/multi- -repository topology; Forge plans dependencies across it; EP CENTRAL admits and -records executable work; and Project Agents supply local physical capability. - -Multi-repository parallel mutation is deliberately later. It may begin only -after standalone EP verification and requires EP-managed repository leases, -capacity-aware admission, dependency ordering, and qualification evidence. The -initial safety rule remains one mutating lane per repository. Same-repository -worktree or declared-disjoint-scope parallelism is a separate later proposal. - -For the cross-product sequencing and constraints, see the Forge Platform -[MVP roadmap](https://github.com/pcvantol/forge-platform/blob/main/docs/roadmap/MVP_1_0.md#post-verification-multi-repository-parallel-lane-execution) -and its [project/repository/Agent ADR](https://github.com/pcvantol/forge-platform/blob/main/docs/architecture/adr/ADR-0002-project-repository-host-agent-model.md). - -## Decision checkpoints - -No implementation should start from this design alone. The next bounded -decisions are to establish the owner and contract for repository registration, -the EP-owned declaration schema, the GitHub integration/approval model, and -the first limited Workspace onboarding experience. Each must be reviewed as a -separate proposed-to-implemented change with its own validation and evidence. +## Status and scope + +**Status:** canonical target design; implementation and installed qualification remain PLANNED. This record and the [detailed project-bootstrap design](PROJECT_BOOTSTRAP_V1.md) define Workspace's product experience, not an executed onboarding operation or permission to provision resources. The [scoped roadmap](PROJECT_BOOTSTRAP_V1_ROADMAP.md) and [documentary DAG](PROJECT_BOOTSTRAP_V1_DAG.json) decompose the onboarding/control-plane lane of [ROADMAP.md](../ROADMAP.md). + +The detailed contract resolves the formerly unspecified artifact-preview, Genesis/Managed adoption and promotion design. It does not claim runtime closure of those capabilities. EP B8R already owns committed project/repository identity and authenticated attachment; this replaces only this document's older wording that the declaration schema/registration were entirely future. A complete create/adopt/promotion product journey still requires new qualified composition. + +## Entry points + +| Choice | Target outcome | +| --- | --- | +| New Genesis project | Common local product/engineering foundation in an approved missing/empty target or unborn Git; no remote effects | +| Adopt local Genesis work | Explicitly reviewed local content/identity mapping, preserved history and local qualification | +| New Managed repository | Approved remote birth, project foundation and verified host governance | +| Adopt Managed repository | Actual remote inventory/drift review, protected changes and B8R attachment; no history recreation | +| Promote Genesis to Managed | Same project/authority IDs and ancestry, explicit publication and remote-governance proof | + +Qualification-only is an independent purpose with explicit disposable-resource retention/deletion policy, not a mode or generic cleanup authorization. The exact target/effects are approved before execution. A remote failure cannot silently change mode. A local directory is selected through the eligible EP host, not inferred from the browser machine. + +## Owning boundaries + +Workspace owns human-facing drafts, conversations, views and permitted intents; Forge owns product meaning, artifact/contract selection, desired policy and readiness interpretation; EP owns accepted effect authorization, repository-host/local mutation, leases, validation, attachment and evidence. Project Agents provide scoped physical capabilities, not logical topology authority. Forge and Workspace do not command Agent filesystems directly or use peer CLI/import/SQL as a substitute for HTTP. + +Logical identity stays in the EP-owned `.engineering-platform/repository.json`, using its supported packaged schema. Project and repository IDs and the single authority-repository relationship are portable; paths, server/Agent identities and credentials are not. Workspace display naming is not identity. Before a first commit, a reserved name/ID is shown as provisional; canonical registration follows validated committed declaration evidence. The detailed companion specifies how this avoids an identity/permission circular dependency. + +## End-to-end experience + +Describe product -> choose Genesis/Managed and target -> inspect/adoption mapping -> select installed baseline and profiles -> preview exact artifact and settings changes -> obtain applicable scoped decisions -> submit the same stable operation -> observe owning effects/readback -> show mode-specific readiness -> separately refine/approve a first Mission. + +The authoritative artifact manifest and file contents are Forge-owned, not a second Workspace hardcoded template. Users see common product/engineering documents, conditional host assets, before/after hashes, source provenance and unresolved questions. Edits invalidate incompatible decisions. Existing project-owned files and dirty/staged/untracked work are preserved, never auto-overwritten or committed. + +Genesis uses local validation and commit/reconciliation evidence, no fake remote CI/PR success. Managed birth has a reviewed absent-resource boundary before ordinary protected work; it cannot bypass existing branch rules. Managed adoption reads back real governance rather than treating requested settings as compliance. Promotion discloses selected history/privacy/license/visibility, preserves ancestry and switches effective mode only after full qualified result. + +## Recovery, qualification and portability + +Persist owning operation/plan/decision references, not a parallel execution queue. Duplicate request, lost acknowledgement, reconnect and cancellation read back the same operation. Partial effects, privacy-sensitive publication and unresolved ownership stay visible; no silent fresh repo, automatic remote deletion, force-push or database repair. Accepted, delivered, governance-qualified, project-ready and Mission-accepted are separate outcomes. + +Qualification-only resources keep explicit purpose/identity, exact candidate/artifact/proof and eventual disposition. Deletion/archive needs its own applicable approval and cannot be inferred from a green test. User production projects are not disposable fixtures. + +Multi-repository projects have one authority repo and independent children/results. No cross-repo atomicity or new parallel-mutation permission is implied. The first headless bootstrap and existing Mission-3 canary do not wait for Workspace UI. See [the PB-01..PB-40 test coverage mapping](PROJECT_BOOTSTRAP_V1_ROADMAP.md) for installed HTTP/UX, accessibility, five-language and failure-path qualification. Source checkout independence and safe portable manifests are mandatory; development repositories are not runtime template authorities. From 22932f559e9c4e1b1098eed22e6a31888a5aebb6 Mon Sep 17 00:00:00 2001 From: DJConnect Date: Thu, 17 Sep 2026 15:11:01 +0200 Subject: [PATCH 2/2] docs: retain explicit proposed implementation status for onboarding --- docs/REPOSITORY_ONBOARDING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/REPOSITORY_ONBOARDING.md b/docs/REPOSITORY_ONBOARDING.md index 1e4e82f..6e5f354 100644 --- a/docs/REPOSITORY_ONBOARDING.md +++ b/docs/REPOSITORY_ONBOARDING.md @@ -2,7 +2,7 @@ ## Status and scope -**Status:** canonical target design; implementation and installed qualification remain PLANNED. This record and the [detailed project-bootstrap design](PROJECT_BOOTSTRAP_V1.md) define Workspace's product experience, not an executed onboarding operation or permission to provision resources. The [scoped roadmap](PROJECT_BOOTSTRAP_V1_ROADMAP.md) and [documentary DAG](PROJECT_BOOTSTRAP_V1_DAG.json) decompose the onboarding/control-plane lane of [ROADMAP.md](../ROADMAP.md). +**Status: proposed.** This is the canonical target design; implementation and installed qualification remain PLANNED. This record and the [detailed project-bootstrap design](PROJECT_BOOTSTRAP_V1.md) define Workspace's product experience, not an executed onboarding operation or permission to provision resources. The [scoped roadmap](PROJECT_BOOTSTRAP_V1_ROADMAP.md) and [documentary DAG](PROJECT_BOOTSTRAP_V1_DAG.json) decompose the onboarding/control-plane lane of [ROADMAP.md](../ROADMAP.md). The detailed contract resolves the formerly unspecified artifact-preview, Genesis/Managed adoption and promotion design. It does not claim runtime closure of those capabilities. EP B8R already owns committed project/repository identity and authenticated attachment; this replaces only this document's older wording that the declaration schema/registration were entirely future. A complete create/adopt/promotion product journey still requires new qualified composition.