From d9f0c0a441de91818b901649d8c05e4393a1270d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20J=2E=20Arg=C3=BCello?= <12516370+cjarguello@users.noreply.github.com> Date: Thu, 2 Apr 2026 02:39:39 -0600 Subject: [PATCH 1/3] Rename personal-only zone and drop local_migration_history zone --- audit_ctl.sh | 5 ++++- config/cleanup_zones_policy.tsv | 3 +-- tests/test_audit_tools.sh | 6 +++--- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/audit_ctl.sh b/audit_ctl.sh index a72950e..7a1e21a 100755 --- a/audit_ctl.sh +++ b/audit_ctl.sh @@ -442,7 +442,10 @@ collect_queue_health() { working_files="$(count_files "$ROOT/local-workspace/local-working-files")" trash_files="$(count_files "$ROOT/local-workspace/local-trash-delete")" handoff_files="$(count_files "$ROOT/local-workspace/local-handoffs")" - pm_only_files="$(count_files "$ROOT/local-workspace/local-cj-pm-only")" + pm_only_files="$(count_files "$ROOT/local-workspace/local-personal-only")" + if [[ "$pm_only_files" -eq 0 ]]; then + pm_only_files="$(count_files "$ROOT/local-workspace/local-cj-pm-only")" + fi codex_state_files="$(count_files "$ROOT/local-workspace/local-codex")" shared_dropoff_files="$(count_files "$ROOT/local-workspace/local-shared-dropoff")" } diff --git a/config/cleanup_zones_policy.tsv b/config/cleanup_zones_policy.tsv index 1f900f5..2438634 100644 --- a/config/cleanup_zones_policy.tsv +++ b/config/cleanup_zones_policy.tsv @@ -3,10 +3,9 @@ # - REPORT_ONLY: cleanup audit only reports metrics (counts/dup names/large files), no action pressure. # - STRICT_CANONICAL: canonical zone, expected to stay organized and auditable. -cj_pm_dropbox|REPORT_ONLY|local-workspace/local-cj-pm-only|explicit user-managed keep zone when enabled by the selected local-workspace profile; no cleanup pressure +local_personal_folder|REPORT_ONLY|local-workspace/local-personal-only|personal-only lane when enabled by profile; compatibility alias: local-workspace/local-cj-pm-only local_trash_delete|REPORT_ONLY|local-workspace/local-trash-delete|inactive disposal holding lane; do not replicate; review only for purge local_working_files|REPORT_ONLY|local-workspace/local-working-files|default explicit keep path for local files that are still active or under review -local_migration_history|REPORT_ONLY|local-workspace/local-working-files/local-migration-history|temporary migration-era packet if still present; not part of canonical skeleton; keep tiny and review regularly legacy_agent_bootstrap|REPORT_ONLY|bitpod-docs/archive/legacy-context/sector-feeds-agent-bootstrap|archived non-feed bootstrap material moved out of sector-feeds; preserve and monitor only templates_registry|STRICT_CANONICAL|bitpod-tools/linear/docs/templates_registry|canonical template index and references learnings_ledger|STRICT_CANONICAL|bitpod-docs/archive/learnings|canonical retros/protocol learnings diff --git a/tests/test_audit_tools.sh b/tests/test_audit_tools.sh index 483a2d1..1463142 100755 --- a/tests/test_audit_tools.sh +++ b/tests/test_audit_tools.sh @@ -139,7 +139,7 @@ setup_workspace() { mkdir -p "$WORKSPACE_ROOT/local-workspace/local-working-files/local-reference" mkdir -p "$WORKSPACE_ROOT/local-workspace/local-trash-delete" mkdir -p "$WORKSPACE_ROOT/local-workspace/local-trash-delete/local-purge" - mkdir -p "$WORKSPACE_ROOT/local-workspace/local-cj-pm-only" + mkdir -p "$WORKSPACE_ROOT/local-workspace/local-personal-only" ln -s "$AUDIT_CTL" "$WORKSPACE_ROOT/bitpod-tools/audit_ctl.sh" ln -s "$PROJECT_ROOT/scripts/parity_pulse_emit.sh" "$WORKSPACE_ROOT/bitpod-tools/scripts/parity_pulse_emit.sh" @@ -154,7 +154,7 @@ required_paths = [ "local-working-files", "local-trash-delete", "local-trash-delete/local-purge", - "local-cj-pm-only", + "local-personal-only", ] optional_paths = [] disabled_paths = [ @@ -167,7 +167,7 @@ EOF cat > "$ZONE_POLICY_FILE" <<'EOF' # zone|mode|rel_path|notes working|STRICT_CANONICAL|local-workspace/local-working-files|active working files -pm_only|REPORT_ONLY|local-workspace/local-cj-pm-only|personal-only lane when enabled by profile +pm_only|REPORT_ONLY|local-workspace/local-personal-only|personal-only lane when enabled by profile EOF create_tracked_repo "alpha" From a8f460e22547c64db19f78522e5567c27acc6f90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20J=2E=20Arg=C3=BCello?= <12516370+cjarguello@users.noreply.github.com> Date: Mon, 6 Apr 2026 00:55:42 -0600 Subject: [PATCH 2/3] bootstrap org workspace and align policy packet paths --- .agents/policy/taylored-policy-rules.md | 25 ++- .agents/policy/taylored-policy.md | 77 ++++---- .../durable_artifact_memory_flow_proof_v1.md | 28 +-- .../global_artifact_naming_policy_v1.md | 2 +- ...ode_retirement_and_hardening_mapping_v1.md | 18 +- .../docs/process/vera_qa_lane_contract_v1.md | 10 +- .../vera_qa_lane_operational_proof_v1.md | 16 +- .../vera_linear_pr_review_prompt_v1.md | 14 +- .../scripts/execution_hq_remote_bootstrap.sh | 14 +- scripts/bootstrap_org_workspace.sh | 168 ++++++++++++++++++ 10 files changed, 294 insertions(+), 78 deletions(-) create mode 100755 scripts/bootstrap_org_workspace.sh diff --git a/.agents/policy/taylored-policy-rules.md b/.agents/policy/taylored-policy-rules.md index c48e861..da972eb 100644 --- a/.agents/policy/taylored-policy-rules.md +++ b/.agents/policy/taylored-policy-rules.md @@ -1,21 +1,20 @@ - + # Taylored Policy Rules -CANONICAL SOURCE: `bitpod-docs/process/taylored-policy-rules.md` -LOCAL ROOT MIRROR: `$WORKSPACE/taylored-policy-rules.md` bootstrap mirror only -EDIT SURFACE: edit this file first; generated mirrors must not become parallel canon +CANONICAL SOURCE: `bitpod-docs/policies/taylored-policy-rules.md` +EDIT SURFACE: edit this file first NAME: Taylored Policy Rules STATUS: Active -DATE: 2026-03-24 -VERSION: 1.1 +DATE: 2026-04-05 +VERSION: 1.2 OWNER: Workspace / Product Development DESCRIPTION: Enumerates prohibition IDs, enforcement states, alertability, and exception eligibility. SCOPE: Root prohibitions for the entire workspace. -ENTRYPOINT: Referenced by repo `AGENTS.md` files and governance docs. -DEPENDENCIES: `taylored-policy.md`, `../AGENTS.md`. +ENTRYPOINT: Referenced by repo `AGENTS.md` files, root `AGENTS.md`, and governance docs. +DEPENDENCIES: `taylored-policy.md`, `policy-registry.toml`, `../AGENTS.md`. OVERRIDE_POLICY: Only rules marked `exception_allowed = YES` may be declared as explicit repo exceptions. Status: Active shared policy rules file @@ -75,7 +74,7 @@ Every exception must include: | `TPR-011` | GitHub-Native Minimalism | Do not rely on GitHub-native config as the main Taylor01 portability layer. | root governance | `DOCUMENTED_ONLY` | `NO_ALERT_YET` | `NO` | `taylored-policy.md` | | `TPR-012` | Tokenized Public Root | Do not publish person-specific local paths in root public policy surfaces. | root public docs | `ENFORCED` | `ALERT_ON_SUCCESS` | `YES` | `taylored-policy.md` | | `TPR-013` | Secretless Repo Trees | Do not store secrets in tracked repo files or shared handoff folders by default. | repo files and handoffs | `ENFORCED` | `ALERT_ON_SUCCESS` | `YES` | `taylored-policy.md` | -| `TPR-014` | Root Policy Canon | Do not create, restore, or treat legacy policy shim files as the primary policy authoring surface once `taylored-policy.md` exists. | root policy files | `ENFORCED` | `ALERT_ON_SUCCESS` | `NO` | `taylored-policy.md` | +| `TPR-014` | Root Policy Canon | Do not create, restore, or treat competing root policy files as the primary policy authoring surface once `taylored-policy.md` exists. | root policy files | `ENFORCED` | `ALERT_ON_SUCCESS` | `NO` | `taylored-policy.md` | | `TPR-015` | Temporal Is Local Until Unified | Do not treat repo-local temporal metadata as the universal artifact lifecycle contract until a shared lifecycle taxonomy is adopted. | repo temporal metadata | `ENFORCED` | `ALERT_ON_SUCCESS` | `YES` | `temporal-and-local-working-artifact-policy.md` | | `TPR-016` | No Local Workspace README Docs | Do not create `README.md`, `readme.md`, or equivalent local folder documentation files anywhere under `#LOCAL_WORKSPACE`, including nested local folders. | `#LOCAL_WORKSPACE` | `ENFORCED` | `ALERT_ON_SUCCESS` | `YES` | `file-creation-and-artifact-placement-policy.md` | @@ -83,3 +82,11 @@ Interpretation for `TPR-016`: - local-workspace lanes are operational holding surfaces, not documentation surfaces - canonical guidance belongs in root policy, shared process docs, owning repos, or approved external canonical systems + +## Registry companion + +The status of policy-like surfaces is governed by: + +- `bitpod-docs/policies/policy-registry.toml` + +Use the registry to distinguish active, compat, inactive, and legacy surfaces. diff --git a/.agents/policy/taylored-policy.md b/.agents/policy/taylored-policy.md index 5a95259..6691d79 100644 --- a/.agents/policy/taylored-policy.md +++ b/.agents/policy/taylored-policy.md @@ -1,22 +1,21 @@ - + # Taylored Work Policy -CANONICAL SOURCE: `bitpod-docs/process/taylored-policy.md` -LOCAL ROOT MIRROR: `$WORKSPACE/taylored-policy.md` bootstrap mirror only -EDIT SURFACE: edit this file first; generated mirrors must not become parallel canon +CANONICAL SOURCE: `bitpod-docs/policies/taylored-policy.md` +EDIT SURFACE: edit this file first NAME: Taylored Work Policy STATUS: Active -DATE: 2026-03-24 -VERSION: 2.0 +DATE: 2026-04-05 +VERSION: 2.1 OWNER: Workspace / Product Development -DESCRIPTION: Canonical repo-backed global work-policy contract for local umbrella bootstrap and cloud-visible repo distribution. -SCOPE: Workspace-wide authority, portability, and artifact governance. -ENTRYPOINT: repo-root `AGENTS.md` files and generated bootstrap mirrors. -DEPENDENCIES: `AGENTS.md`, `taylored-policy-rules.md`, shared process docs. -OVERRIDE_POLICY: Repo `AGENTS.md` may declare explicit rule exceptions listed in the registry. +DESCRIPTION: Canonical repo-backed global work-policy contract for the BitPod-App workspace. +SCOPE: Workspace-wide authority, portability, minimal root contract, and artifact governance. +ENTRYPOINT: repo-root `AGENTS.md` files and root umbrella `AGENTS.md`. +DEPENDENCIES: `AGENTS.md`, `taylored-policy-rules.md`, `policy-registry.toml`, shared process docs. +OVERRIDE_POLICY: Repo `AGENTS.md` may declare explicit rule exceptions listed in the root policy rules. STATUS: @@ -38,19 +37,23 @@ TOKENS: CANONICAL POLICY SURFACES: - `bitpod-docs/AGENTS.md` = canonical repo-backed policy entrypoint -- `bitpod-docs/process/taylored-policy.md` = canonical global work-policy contract -- `bitpod-docs/process/taylored-policy-rules.md` = canonical prohibition list +- `bitpod-docs/policies/taylored-policy.md` = canonical global work-policy contract +- `bitpod-docs/policies/taylored-policy-rules.md` = canonical prohibition list +- `bitpod-docs/policies/policy-registry.toml` = canonical authority-status registry -COMPATIBILITY SURFACES: +ACTIVE ROOT SURFACES: -- `$WORKSPACE/AGENTS.md` = local umbrella bootstrap mirror only -- `$WORKSPACE/taylored-policy.md` = local umbrella bootstrap mirror only -- `$WORKSPACE/taylored-policy-rules.md` = local umbrella bootstrap mirror only +- `$WORKSPACE/AGENTS.md` = local umbrella router only +- `$WORKSPACE/.codex/org-workspace.toml` = workspace metadata only +- `$WORKSPACE/.codex/environments/environment.toml` = minimal environment metadata only +- `$WORKSPACE/.codex/config.toml` = compatibility-only if Codex still requires an explicit instruction pointer -FALLBACK FILE NAMES: +RETIRED ROOT SURFACES: -- lowercase `agents.md` may exist as a compatibility fallback only -- lowercase files are never canonical when uppercase files exist +- `$WORKSPACE/taylored-policy.md` +- `$WORKSPACE/taylored-policy-rules.md` +- `$WORKSPACE/policy.md` +- `$WORKSPACE/.codex/policy.md` DEFAULT MODEL: @@ -61,22 +64,31 @@ DEFAULT MODEL: DISCOVERY MODEL: -- local umbrella bootstrap may start from `$WORKSPACE/AGENTS.md` +- local umbrella sessions may start from `$WORKSPACE/AGENTS.md` - cloud and repo-local Codex runs must discover policy from files that exist inside the actual repo -- do not rely on umbrella-root-only files for cloud-visible behavior +- do not rely on retired umbrella-root mirror files for cloud-visible behavior READ ORDER: 1. repo-root `AGENTS.md` in the active repo -2. local packet or canonical policy files referenced by that repo-root `AGENTS.md` +2. local repo packet or canonical policy files referenced by that repo-root `AGENTS.md` 3. repo-specific nested `AGENTS.md` or `AGENTS.override.md`, if present 4. task-specific canonical docs explicitly pointed to by the active instruction chain +For local umbrella-root sessions: + +1. root `AGENTS.md` +2. `bitpod-docs/policies/taylored-policy.md` +3. `bitpod-docs/policies/taylored-policy-rules.md` +4. `bitpod-docs/policies/truthfulness-and-verification-policy.md` +5. `bitpod-docs/policies/file-creation-and-artifact-placement-policy.md` + AUTHORITY MAP: - repo-root `AGENTS.md` = active runtime entry routing inside each repo -- `bitpod-docs/process/taylored-policy.md` = global guardrails and authority model -- `bitpod-docs/process/taylored-policy-rules.md` = prohibition IDs, enforcement state, alertability, and exception eligibility +- `bitpod-docs/policies/taylored-policy.md` = global guardrails and authority model +- `bitpod-docs/policies/taylored-policy-rules.md` = prohibition IDs, enforcement state, alertability, and exception eligibility +- `bitpod-docs/policies/policy-registry.toml` = active versus compat versus legacy authority status - repo `AGENTS.md` = repo-specific execution instructions, workflow guidance, model defaults, and canonical doc pointers - repo `README.md` = orientation and navigation only - shared process docs = detailed semantics, naming, lifecycle, audit behavior, and packet contracts @@ -112,7 +124,7 @@ KEEP IN GLOBAL POLICY CANON: - portability boundaries - root/local lifecycle guardrails - the structure that governs how the root policy rules are applied -- packet and mirror discipline for cloud-visible repo distribution +- registry and packet discipline for cloud-visible repo distribution KEEP IN REPO `AGENTS.md`: @@ -168,22 +180,23 @@ SECRETS: PORTABILITY: -- Taylor01 portability should rely primarily on repo-root `AGENTS.md`, `bitpod-docs/process/taylored-policy.md`, `bitpod-docs/process/taylored-policy-rules.md`, and shared canonical docs +- Taylor01 portability should rely primarily on repo-root `AGENTS.md`, `bitpod-docs/policies/taylored-policy.md`, `bitpod-docs/policies/taylored-policy-rules.md`, and shared canonical docs - GitHub-native files are used only for GitHub-native behavior - `.github` repo may hold governance docs or automation, but it is not the sole runtime instruction source -PACKET AND MIRROR RULE: +PACKET RULE: - canonical policy is edited in `bitpod-docs` -- distributed repo packets and local root bootstrap files are generated from canon -- mirrored files must declare canonical source and `DO NOT EDIT HERE` +- distributed repo packets are generated from canon +- root runtime depends only on root `AGENTS.md`, not on root mirrored policy files - generated runtime packets must not become silent parallel canon ROOT REFERENCES: -- `$WORKSPACE/bitpod-docs/process/taylored-policy-rules.md` +- `$WORKSPACE/bitpod-docs/policies/taylored-policy-rules.md` +- `$WORKSPACE/bitpod-docs/policies/policy-registry.toml` - `$WORKSPACE/bitpod-docs/process/read-first-protocol.md` -- `$WORKSPACE/bitpod-docs/process/truthfulness-and-verification-policy.md` +- `$WORKSPACE/bitpod-docs/policies/truthfulness-and-verification-policy.md` - `$WORKSPACE/bitpod-docs/process/codex-global-policy-packet-contract.md` TRUTHFULNESS DISCLOSURE RULE: diff --git a/linear/docs/process/durable_artifact_memory_flow_proof_v1.md b/linear/docs/process/durable_artifact_memory_flow_proof_v1.md index c218617..7510654 100644 --- a/linear/docs/process/durable_artifact_memory_flow_proof_v1.md +++ b/linear/docs/process/durable_artifact_memory_flow_proof_v1.md @@ -1,6 +1,6 @@ # Durable Artifact and Memory Flow Proof v1 -Status: Working proof +Status: Retained proof (inactive by default) Linked issue: [BIT-87 — Prove durable decision, memory, and artifact flow in live AI-team operations](https://linear.app/bitpod-app/issue/BIT-87/prove-durable-decision-memory-and-artifact-flow-in-live-ai-team) ## Objective @@ -24,9 +24,9 @@ Interpretation: Decision/planning artifacts: -- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/bootstrap_phase_normalization_plan_v1.md` -- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/stage4_5_agent_stack_execution_plan_v1.md` -- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/startup_operating_model_v1.md` +- `$WORKSPACE/bitpod-tools/linear/docs/process/bootstrap_phase_normalization_plan_v1.md` +- `$WORKSPACE/bitpod-tools/linear/docs/process/stage4_5_agent_stack_execution_plan_v1.md` +- `$WORKSPACE/bitpod-tools/linear/docs/process/startup_operating_model_v1.md` Controlling issue/PR: @@ -47,10 +47,10 @@ Execution lane: Representative implementation outputs: -- `/Users/cjarguello/bitpod-app/sector-feeds/artifacts/runs/legacy_tuesday_track/jack_mallers_show/20260311T065208Z__status.json` -- `/Users/cjarguello/bitpod-app/sector-feeds/artifacts/runs/legacy_tuesday_track/jack_mallers_show/20260311T065208Z__summary.md` -- `/Users/cjarguello/bitpod-app/sector-feeds/artifacts/runs/experimental_track/jack_mallers_show/20260311T065224Z__status.json` -- `/Users/cjarguello/bitpod-app/sector-feeds/artifacts/runs/experimental_track/jack_mallers_show/20260311T065224Z__summary.md` +- `$WORKSPACE/sector-feeds/artifacts/runs/legacy_tuesday_track/jack_mallers_show/20260311T065208Z__status.json` +- `$WORKSPACE/sector-feeds/artifacts/runs/legacy_tuesday_track/jack_mallers_show/20260311T065208Z__summary.md` +- `$WORKSPACE/sector-feeds/artifacts/runs/experimental_track/jack_mallers_show/20260311T065224Z__status.json` +- `$WORKSPACE/sector-feeds/artifacts/runs/experimental_track/jack_mallers_show/20260311T065224Z__summary.md` What this proves: @@ -82,9 +82,9 @@ What this proves: Checkpoint protocol artifacts: -- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/long_thread_checkpoint_protocol_v1.md` -- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/checkpoints/thread_checkpoint_template_v1.md` -- `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/checkpoints/active_checkpoint_sector_feeds_bit77_2026-03-11.md` +- `$WORKSPACE/bitpod-tools/linear/docs/process/long_thread_checkpoint_protocol_v1.md` +- `$WORKSPACE/bitpod-tools/linear/docs/process/checkpoints/thread_checkpoint_template_v1.md` +- `$WORKSPACE/bitpod-tools/linear/docs/process/checkpoints/active_checkpoint_sector_feeds_bit77_2026-03-11.md` Controlling issue/PR: @@ -108,6 +108,12 @@ The current live chain is: That is a real decision -> execution -> QA/artifact -> memory/checkpoint chain. +## Authority note + +This file is retained proof, not active execution policy. Use the policy +registry to determine which current guide, contract, and runbook surfaces are +still authoritative. + ## What Is Still Missing This proof should not be overstated. diff --git a/linear/docs/process/global_artifact_naming_policy_v1.md b/linear/docs/process/global_artifact_naming_policy_v1.md index 465fba2..01b0f92 100644 --- a/linear/docs/process/global_artifact_naming_policy_v1.md +++ b/linear/docs/process/global_artifact_naming_policy_v1.md @@ -4,6 +4,6 @@ Compatibility pointer. Primary shared policy now lives at: -- `/Users/cjarguello/BitPod-App/bitpod-docs/process/global-artifact-naming-policy-v1.md` +- `/Users/cjarguello/BitPod-App/bitpod-docs/policies/global-artifact-naming-policy-v1.md` Use that file for current naming rules. diff --git a/linear/docs/process/isolation_mode_retirement_and_hardening_mapping_v1.md b/linear/docs/process/isolation_mode_retirement_and_hardening_mapping_v1.md index d45c20d..c982d2e 100644 --- a/linear/docs/process/isolation_mode_retirement_and_hardening_mapping_v1.md +++ b/linear/docs/process/isolation_mode_retirement_and_hardening_mapping_v1.md @@ -1,6 +1,6 @@ # Isolation Mode Retirement and Hardening Mapping v1 -Status: Working baseline +Status: Retained baseline (inactive by default) Primary issue: [BIT-74 — Execute post-bootstrap local scope hardening window after migration closeout](https://linear.app/bitpod-app/issue/BIT-74/execute-post-bootstrap-local-scope-hardening-window-after-migration) ## Objective @@ -14,8 +14,8 @@ Make the current truth explicit: Policy artifacts still exist: -- `/Users/cjarguello/bitpod-app/local-workspace/local-codex/policy/isolation/enforcement_state.json` -- `/Users/cjarguello/bitpod-app/local-workspace/local-codex/policy/isolation/violation_queue.json` +- `$WORKSPACE/local-workspace/local-codex/policy/isolation/enforcement_state.json` +- `$WORKSPACE/local-workspace/local-codex/policy/isolation/violation_queue.json` Current state is dormant: @@ -25,9 +25,9 @@ Current state is dormant: Last known implementation exists only in quarantined legacy paths: -- `/Users/cjarguello/bitpod-app/local-workspace/local-trash-delete/bitpod/scripts/isolation_ctl.py` -- `/Users/cjarguello/bitpod-app/local-workspace/local-trash-delete/bitpod/tools/isolation/cli.py` -- `/Users/cjarguello/bitpod-app/local-workspace/local-trash-delete/bitpod/tools/isolation/runtime.py` +- `$WORKSPACE/local-workspace/local-trash-delete/bitpod/scripts/isolation_ctl.py` +- `$WORKSPACE/local-workspace/local-trash-delete/bitpod/tools/isolation/cli.py` +- `$WORKSPACE/local-workspace/local-trash-delete/bitpod/tools/isolation/runtime.py` ## Retirement decision @@ -87,6 +87,12 @@ If OpenClaw or another operator surface later needs stronger isolation: - implement it in an approved active path - verify it in the current runtime/host model +## Authority note + +This file is retained as an explanatory mapping, not as an active operating +policy. Current authority lives in the active policy registry and the approved +hardening/runtime boundary docs. + ## Allowed remaining legacy state The dormant policy files and skill may remain temporarily as historical inspection aids. diff --git a/linear/docs/process/vera_qa_lane_contract_v1.md b/linear/docs/process/vera_qa_lane_contract_v1.md index 69ff3e7..b5a3ae5 100644 --- a/linear/docs/process/vera_qa_lane_contract_v1.md +++ b/linear/docs/process/vera_qa_lane_contract_v1.md @@ -80,14 +80,16 @@ If the handoff packet is incomplete, QA should reject the handoff and ask Taylor Every dedicated QA execution must produce a `verification_report.md`-style artifact with: -1. verdict: `PASSED` or `FAILED` +1. verdict: `PASSED`, `FAILED`, or `SKIPPED` 2. environment matrix 3. critical acceptance criteria with evidence per criterion 4. `this failed QA because ...` section when verdict is `FAILED` -5. optional low-risk fix hints only when obvious -6. final line: +5. `this QA was skipped because ...` section when verdict is `SKIPPED` +6. optional low-risk fix hints only when obvious +7. final line: - `QA_VERDICT: PASSED`, or - - `QA_VERDICT: FAILED` + - `QA_VERDICT: FAILED`, or + - `QA_VERDICT: SKIPPED` Allowed storage targets: diff --git a/linear/docs/process/vera_qa_lane_operational_proof_v1.md b/linear/docs/process/vera_qa_lane_operational_proof_v1.md index 427d590..b14e598 100644 --- a/linear/docs/process/vera_qa_lane_operational_proof_v1.md +++ b/linear/docs/process/vera_qa_lane_operational_proof_v1.md @@ -1,6 +1,6 @@ # Vera QA Lane Operational Proof v1 -Status: Working proof +Status: Retained proof (inactive by default) Linked issue: [BIT-90 — Stand up dedicated QA lane beyond interim AI technical QA policy](https://linear.app/bitpod-app/issue/BIT-90/stand-up-dedicated-qa-lane-beyond-interim-ai-technical-qa-policy) ## Objective @@ -33,7 +33,7 @@ That gap was documented in: The stronger QA behavior now lives in Vera's dedicated QA contract and is currently implemented through the local skill surface: - canonical local surface: - - `/Users/cjarguello/bitpod-app/local-workspace/local-codex/skills/qa-specialist/SKILL.md` + - `$WORKSPACE/local-workspace/local-codex/skills/qa-specialist/SKILL.md` Taylor's current skill now explicitly delegates final QA verification execution to `qa-specialist`, which is why BIT-90 should anchor to Vera's artifact contract rather than Taylor-style review behavior. @@ -54,14 +54,20 @@ That does not mean Vera should remain only a skill long-term. The skill is an ac ### Durable artifacts produced in this execution - contract: - - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/vera_qa_lane_contract_v1.md` + - `$WORKSPACE/bitpod-tools/linear/docs/process/vera_qa_lane_contract_v1.md` - verification artifact: - - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/examples/verification_report_bit90_minimum_team_2026-03-12.md` + - `$WORKSPACE/bitpod-tools/linear/examples/verification_report_bit90_minimum_team_2026-03-12.md` - lane checkpoint: - - `/Users/cjarguello/bitpod-app/bitpod-tools/linear/docs/process/checkpoints/active_checkpoint_phase4_minimum_team_2026-03-12.md` + - `$WORKSPACE/bitpod-tools/linear/docs/process/checkpoints/active_checkpoint_phase4_minimum_team_2026-03-12.md` - validation command: - `bash linear/scripts/local_smoke.sh` -> `local smoke PASS` +## Authority note + +This file is retained proof, not active execution policy. Treat the current +policy registry and explicitly promoted guide/contract surfaces as the active +authority layer. + ## Why This Counts As A Dedicated QA Lane The lane is no longer only an informal review style because it now has: diff --git a/linear/examples/vera_linear_pr_review_prompt_v1.md b/linear/examples/vera_linear_pr_review_prompt_v1.md index 3f4a05a..1dec8e6 100644 --- a/linear/examples/vera_linear_pr_review_prompt_v1.md +++ b/linear/examples/vera_linear_pr_review_prompt_v1.md @@ -38,20 +38,21 @@ Required output: - Final line: - `QA_VERDICT: PASSED` - or `QA_VERDICT: FAILED` + - or `QA_VERDICT: SKIPPED` 3. Then return a concise receipt comment with: - target issue (and PR if present) - - `QA_RESULT=PASSED` or `QA_RESULT=FAILED` - - if a PR exists, include `PR_URL=` - - QA label (`qa-passed` or `qa-failed`) - - short reason if label is `qa-failed` + - `PR_URL=` when a PR exists + - `QA_RESULT=PASSED`, `QA_RESULT=FAILED`, or `QA_RESULT=SKIPPED` + - QA label (`qa-passed`, `qa-failed`, or `qa-skipped`) + - short reason if label is `qa-failed` or `qa-skipped` - link or pasted body for `verification_report.md` Rules: - If critical context is missing, fail closed as `QA_RESULT=FAILED` with `qa-failed` +- If QA cannot safely reach pass/fail (legacy `NO_VERDICT`), emit `QA_RESULT=SKIPPED` with `qa-skipped`, end the report with `QA_VERDICT: SKIPPED`, and explain what is missing - Do not give a casual “looks good” - Every critical acceptance criterion needs either pass evidence or one reproducible failure - Optional fix hints are allowed only if obvious and low-risk, max 3 bullets -- `SKIPPED` is not allowed in the interim bridge Important: - keep this as a cheap interim Linear-first QA pass @@ -64,7 +65,8 @@ Important: ## Notes - Preferred durable artifact name remains `verification_report.md` -- The only QA labels are `qa-passed` and `qa-failed` +- Canonical QA labels are `qa-passed`, `qa-failed`, and `qa-skipped` +- For interim bridge compatibility, treat legacy `NO_VERDICT` as `QA_RESULT=SKIPPED` + `qa-skipped` - This is intentionally cheaper than the Zulip-era Taylor QA runtime - Canonical QA lane contract still lives in: - `linear/docs/process/vera_qa_lane_contract_v1.md` diff --git a/linear/scripts/execution_hq_remote_bootstrap.sh b/linear/scripts/execution_hq_remote_bootstrap.sh index 3bde4ec..18d6a1b 100755 --- a/linear/scripts/execution_hq_remote_bootstrap.sh +++ b/linear/scripts/execution_hq_remote_bootstrap.sh @@ -6,6 +6,7 @@ AI_HQ_EXEC_USER="${AI_HQ_EXEC_USER:-taylorhq}" AI_HQ_ADMIN_USER="${AI_HQ_ADMIN_USER:-cjarguello}" AI_HQ_WORKSPACE="${AI_HQ_WORKSPACE:-\$HOME/bitpod-app}" AI_HQ_GIT_SCHEME="${AI_HQ_GIT_SCHEME:-https}" +AI_HQ_PROFILE="${AI_HQ_PROFILE:-taylor01_hq_lean}" AI_HQ_REPOS="${AI_HQ_REPOS:-bitpod-assets bitpod-docs bitpod-taylor-runtime bitpod-tools bitregime-core sector-feeds}" SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=5) @@ -24,8 +25,9 @@ Environment: Notes: - probe is non-destructive and checks ssh reachability for both accounts -- reset-workspace deletes and recreates the execution-account workspace -- verify-workspace confirms the expected repo set under the execution account +- reset-workspace deletes and recreates the execution-account workspace, then + writes minimal root metadata and the selected local-workspace profile +- verify-workspace confirms root metadata, repo set, and the selected profile - smoke runs AI_HQ_SMOKE_CMD inside the execution-account shell EOF } @@ -88,8 +90,8 @@ rm -rf \"\$WORKSPACE\" mkdir -p \"\$WORKSPACE\" cd \"\$WORKSPACE\" ${repo_lines} -printf 'workspace reset complete at %s\n' \"\$WORKSPACE\" -ls" +bash \"\$WORKSPACE/bitpod-tools/scripts/bootstrap_org_workspace.sh\" --root \"\$WORKSPACE\" --profile \"${AI_HQ_PROFILE}\" --clone-scheme \"${AI_HQ_GIT_SCHEME}\" --skip-clone +printf 'workspace reset complete at %s\n' \"\$WORKSPACE\"" } command_verify_workspace() { @@ -101,6 +103,10 @@ command_verify_workspace() { run_remote_exec "set -euo pipefail export WORKSPACE=\"${AI_HQ_WORKSPACE}\" [[ -d \"\$WORKSPACE\" ]] || { echo \"missing workspace: \$WORKSPACE\" >&2; exit 1; } +[[ -f \"\$WORKSPACE/AGENTS.md\" ]] || { echo \"missing root AGENTS.md\" >&2; exit 1; } +[[ -f \"\$WORKSPACE/.codex/org-workspace.toml\" ]] || { echo \"missing org-workspace.toml\" >&2; exit 1; } +[[ -f \"\$WORKSPACE/.codex/environments/environment.toml\" ]] || { echo \"missing environment.toml\" >&2; exit 1; } +[[ -d \"\$WORKSPACE/local-workspace\" ]] || { echo \"missing local-workspace\" >&2; exit 1; } ${verify_lines} printf 'workspace verified at %s\n' \"\$WORKSPACE\"" } diff --git a/scripts/bootstrap_org_workspace.sh b/scripts/bootstrap_org_workspace.sh new file mode 100755 index 0000000..fcc8a28 --- /dev/null +++ b/scripts/bootstrap_org_workspace.sh @@ -0,0 +1,168 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +WORKSPACE_DEFAULT="$(cd -- "$SCRIPT_DIR/../.." && pwd)" + +ROOT="${WORKSPACE_DEFAULT}" +PROFILE="personal_full" +CLONE_SCHEME="https" +SKIP_CLONE=0 + +usage() { + cat <<'EOF' +usage: bootstrap_org_workspace.sh [--root PATH] [--profile personal_full|taylor01_hq_lean] [--clone-scheme https|ssh] [--skip-clone] + +Creates or validates a BitPod org workspace root, clones missing repos, writes +minimal root metadata, syncs repo policy packets, and creates the selected +local-workspace profile skeleton. +EOF +} + +while [[ $# -gt 0 ]]; do + case "$1" in + --root) + ROOT="$2" + shift 2 + ;; + --profile) + PROFILE="$2" + shift 2 + ;; + --clone-scheme) + CLONE_SCHEME="$2" + shift 2 + ;; + --skip-clone) + SKIP_CLONE=1 + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + echo "unknown argument: $1" >&2 + usage >&2 + exit 2 + ;; + esac +done + +mkdir -p "$ROOT" + +clone_url() { + local repo="$1" + if [[ "$CLONE_SCHEME" == "ssh" ]]; then + printf 'git@github.com:BitPod-App/%s.git' "$repo" + else + printf 'https://github.com/BitPod-App/%s.git' "$repo" + fi +} + +manifest_json() { + python3 - "$ROOT/bitpod-docs/process/global-agent-policy-distribution-manifest.json" <<'PY' +import json, sys +from pathlib import Path + +manifest_path = Path(sys.argv[1]) +data = json.loads(manifest_path.read_text()) +for repo in data["activeRepos"]: + print(repo) +PY +} + +write_root_metadata() { + mkdir -p "$ROOT/.codex/environments" + cat > "$ROOT/.codex/org-workspace.toml" < "$ROOT/.codex/environments/environment.toml" <<'EOF' +# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY +version = 1 +name = "BitPod-App" + +[setup] +script = "" +EOF + + cat > "$ROOT/.codex/config.toml" <<'EOF' +project_root_markers = [] +model_instructions_file = "AGENTS.md" +EOF +} + +clone_missing_repos() { + local repo + while IFS= read -r repo; do + [[ -z "$repo" ]] && continue + if [[ -d "$ROOT/$repo/.git" ]]; then + echo "ok existing repo: $repo" + continue + fi + echo "cloning repo: $repo" + git clone "$(clone_url "$repo")" "$ROOT/$repo" + done < <(manifest_json) +} + +create_local_workspace_profile() { + python3 - "$ROOT/bitpod-docs/process/local-workspace-skeleton-contract.toml" "$PROFILE" "$ROOT/local-workspace" <<'PY' +import sys +from pathlib import Path + +contract_path = Path(sys.argv[1]) +profile = sys.argv[2] +workspace_root = Path(sys.argv[3]) + +try: + import tomllib # type: ignore[attr-defined] +except ModuleNotFoundError: + import tomli as tomllib # type: ignore[no-redef] + +with contract_path.open("rb") as fh: + data = tomllib.load(fh) + +profiles = data.get("profiles", {}) +if profile not in profiles: + raise SystemExit(f"unknown profile: {profile}") + +required = profiles[profile].get("required_paths", []) +workspace_root.mkdir(parents=True, exist_ok=True) +for rel in required: + (workspace_root / rel).mkdir(parents=True, exist_ok=True) + print(f"created {workspace_root / rel}") +PY +} + +validate_workspace() { + [[ -f "$ROOT/AGENTS.md" ]] || { echo "missing root AGENTS.md" >&2; exit 1; } + [[ -f "$ROOT/.codex/org-workspace.toml" ]] || { echo "missing org-workspace.toml" >&2; exit 1; } + [[ -f "$ROOT/.codex/environments/environment.toml" ]] || { echo "missing environment.toml" >&2; exit 1; } + [[ -f "$ROOT/bitpod-docs/policies/taylored-policy.md" ]] || { echo "missing taylored-policy.md" >&2; exit 1; } + [[ -f "$ROOT/bitpod-docs/policies/taylored-policy-rules.md" ]] || { echo "missing taylored-policy-rules.md" >&2; exit 1; } + [[ -f "$ROOT/bitpod-docs/policies/policy-registry.toml" ]] || { echo "missing policy-registry.toml" >&2; exit 1; } + python3 "$ROOT/bitpod-docs/scripts/sync_global_agent_policy.py" validate +} + +write_root_metadata + +if [[ "$SKIP_CLONE" -eq 0 ]]; then + clone_missing_repos +fi + +python3 "$ROOT/bitpod-docs/scripts/sync_global_agent_policy.py" sync +create_local_workspace_profile +validate_workspace + +echo "workspace bootstrap complete at $ROOT using profile $PROFILE" From f1bbd11facd170513e2ae23dcd3b00c2fc622d0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carlos=20J=2E=20Arg=C3=BCello?= <12516370+cjarguello@users.noreply.github.com> Date: Tue, 7 Apr 2026 20:38:09 -0600 Subject: [PATCH 3/3] refresh policy packet content --- .agents/policy/taylored-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/policy/taylored-policy.md b/.agents/policy/taylored-policy.md index 6691d79..8c8e2f1 100644 --- a/.agents/policy/taylored-policy.md +++ b/.agents/policy/taylored-policy.md @@ -94,7 +94,7 @@ AUTHORITY MAP: - shared process docs = detailed semantics, naming, lifecycle, audit behavior, and packet contracts WORKFLOW POINTER: - +D - for cross-repo Linear issue-update semantics, treat `update Linear` as `make the issue materially more truthful` - that default preserves existing assignee/delegate by default and does not include assigning/delegating issues to Codex or mentioning `@Codex`; those actions are explicit cloud-task delegation only - the canonical detailed rule surface for that behavior is `$WORKSPACE/bitpod-tools/linear/docs/process/linear_operating_guide_v3.md`