@geraldmaron/construct 1.1.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -18
- package/bin/construct +392 -91
- package/bin/construct-postinstall.mjs +30 -2
- package/examples/distribution/README.md +42 -0
- package/examples/distribution/manifest.json +53 -0
- package/examples/distribution/sources/adr.md +84 -0
- package/examples/distribution/sources/deck-one-pager.md +65 -0
- package/examples/distribution/sources/prd-platform.md +161 -0
- package/examples/distribution/sources/research-brief.md +80 -0
- package/examples/distribution/sources/rfc-platform.md +82 -0
- package/examples/distribution/sources/runbook.md +103 -0
- package/examples/distribution/sources/strategy.md +88 -0
- package/lib/adapters-sync.mjs +67 -0
- package/lib/artifact-gate-notice.mjs +38 -0
- package/lib/artifact-manifest.mjs +112 -0
- package/lib/artifact-release-gate.mjs +171 -0
- package/lib/artifact-reviewers.mjs +68 -0
- package/lib/artifact-type-from-path.mjs +79 -0
- package/lib/audit-skills.mjs +4 -0
- package/lib/audit-specialists.mjs +285 -0
- package/lib/audit-trail.mjs +77 -10
- package/lib/auto-docs.mjs +87 -18
- package/lib/beads/drift.mjs +27 -6
- package/lib/beads-client.mjs +49 -121
- package/lib/beads-optimistic.mjs +5 -12
- package/lib/brand-fonts.mjs +93 -0
- package/lib/brand-prose.mjs +214 -0
- package/lib/brand-tokens.mjs +92 -0
- package/lib/bridges/copilot-proxy.mjs +13 -26
- package/lib/capability-ledger.mjs +156 -0
- package/lib/certification/artifact-fixtures.mjs +132 -0
- package/lib/certification/artifact-gates.mjs +63 -0
- package/lib/certification/artifact-provenance.mjs +97 -0
- package/lib/certification/canonical-scenarios.mjs +78 -0
- package/lib/certification/cli.mjs +191 -0
- package/lib/certification/dashboard-api.mjs +71 -0
- package/lib/certification/demo-parity.mjs +116 -0
- package/lib/certification/document-io-fixtures.mjs +246 -0
- package/lib/certification/document-workflow.mjs +97 -0
- package/lib/certification/eval-bridge.mjs +77 -0
- package/lib/certification/model-routing.mjs +149 -0
- package/lib/certification/prompt-budget.mjs +119 -0
- package/lib/certification/rc-gate.mjs +206 -0
- package/lib/certification/real-llm-scenarios.mjs +303 -0
- package/lib/certification/role-cards.mjs +113 -0
- package/lib/certification/role-overlays.mjs +117 -0
- package/lib/certification/run.mjs +122 -0
- package/lib/certification/runner.mjs +323 -0
- package/lib/certification/scenarios.mjs +51 -0
- package/lib/certification/skill-inventory.mjs +289 -0
- package/lib/certification/skill-scenarios.mjs +147 -0
- package/lib/certification/specialist-contracts.mjs +85 -0
- package/lib/certification/specialist-scenarios.mjs +175 -0
- package/lib/certification/stale-impact.mjs +146 -0
- package/lib/certification/status.mjs +252 -0
- package/lib/certification/store.mjs +77 -0
- package/lib/chat/cli.mjs +333 -0
- package/lib/chat/command-suggest.mjs +161 -0
- package/lib/chat/commands.mjs +215 -0
- package/lib/chat/config.mjs +142 -0
- package/lib/chat/context-compactor.mjs +250 -0
- package/lib/chat/context-continuation.mjs +253 -0
- package/lib/chat/continuation-source.mjs +58 -0
- package/lib/chat/demo-guide.mjs +61 -0
- package/lib/chat/design-tokens.mjs +91 -0
- package/lib/chat/desktop-binary.mjs +79 -0
- package/lib/chat/desktop-build.mjs +130 -0
- package/lib/chat/desktop-launcher.mjs +133 -0
- package/lib/chat/evidence.mjs +145 -0
- package/lib/chat/export.mjs +74 -0
- package/lib/chat/harness/driver.mjs +91 -0
- package/lib/chat/list-picker.mjs +112 -0
- package/lib/chat/model-picker.mjs +356 -0
- package/lib/chat/openrouter-fallback.mjs +151 -0
- package/lib/chat/permission-prompt.mjs +33 -0
- package/lib/chat/picker-catalog.mjs +45 -0
- package/lib/chat/policy-telemetry.mjs +34 -0
- package/lib/chat/present.mjs +245 -0
- package/lib/chat/session-context.mjs +39 -0
- package/lib/chat/session-persist.mjs +73 -0
- package/lib/chat/session-restore.mjs +71 -0
- package/lib/chat/session-settings.mjs +53 -0
- package/lib/chat/system-prompt.mjs +52 -0
- package/lib/chat/transparency.mjs +93 -0
- package/lib/chat/tui/color-scheme.mjs +42 -0
- package/lib/chat/tui/markdown.mjs +123 -0
- package/lib/chat/tui/presentation.mjs +100 -0
- package/lib/chat/tui/render.mjs +500 -0
- package/lib/chat/tui/turn-block.mjs +284 -0
- package/lib/chat/tui/turn-present.mjs +18 -0
- package/lib/chat/tui/turn-state.mjs +88 -0
- package/lib/chat/tui/usage.mjs +122 -0
- package/lib/chat/web-commands.mjs +146 -0
- package/lib/chat/web-launcher.mjs +63 -0
- package/lib/chat/web-picker-keys.mjs +46 -0
- package/lib/chat/web-session.mjs +159 -0
- package/lib/cli-commands.mjs +232 -11
- package/lib/comment-lint.mjs +6 -4
- package/lib/config/schema.mjs +36 -5
- package/lib/contract-schemas/decision.json +50 -0
- package/lib/contract-schemas/implementation.json +51 -0
- package/lib/contract-schemas/review-report.json +32 -0
- package/lib/contract-schemas/test-report.json +43 -0
- package/lib/contracts/construct-handoff.mjs +60 -0
- package/lib/contracts/validate.mjs +32 -3
- package/lib/contracts/violation-log.mjs +58 -5
- package/lib/dashboard-demo.mjs +71 -0
- package/lib/dashboard-static.mjs +19 -5
- package/lib/decisions/registry.mjs +5 -3
- package/lib/deck-export-pptx.mjs +1152 -0
- package/lib/demo-recording.mjs +142 -0
- package/lib/demo-script.mjs +114 -0
- package/lib/demo-surface.mjs +249 -0
- package/lib/demo.mjs +703 -0
- package/lib/diagram-export.mjs +192 -0
- package/lib/diagram.mjs +302 -0
- package/lib/docs-verify.mjs +25 -7
- package/lib/doctor/index.mjs +4 -2
- package/lib/doctor/project-adapters.mjs +44 -0
- package/lib/doctor/watchers/cx-budget.mjs +98 -0
- package/lib/doctor/watchers/graph-staleness.mjs +52 -0
- package/lib/doctor/watchers/process-pressure.mjs +4 -3
- package/lib/doctor/watchers/service-health.mjs +1 -1
- package/lib/document-export.mjs +360 -36
- package/lib/document-extract.mjs +88 -0
- package/lib/document-ingest.mjs +32 -18
- package/lib/embed/cli.mjs +2 -2
- package/lib/embed/daemon.mjs +18 -46
- package/lib/embed/semantic.mjs +5 -2
- package/lib/embed/worker.mjs +2 -2
- package/lib/embedded-contract/model-resolve.mjs +10 -9
- package/lib/env-config.mjs +26 -0
- package/lib/evals/dataset.mjs +137 -0
- package/lib/evals/gates.mjs +175 -0
- package/lib/graph/build-co-change.mjs +54 -0
- package/lib/graph/build-from-registry.mjs +136 -0
- package/lib/graph/build-import-graph.mjs +153 -0
- package/lib/graph/cli.mjs +110 -0
- package/lib/graph/impact-cli.mjs +89 -0
- package/lib/graph/impact.mjs +108 -0
- package/lib/graph/staleness.mjs +44 -0
- package/lib/graph/store.mjs +172 -0
- package/lib/handoffs/cleanup.mjs +1 -1
- package/lib/health-check.mjs +90 -76
- package/lib/hooks/artifact-release-gate.mjs +43 -0
- package/lib/hooks/audit-trail.mjs +14 -28
- package/lib/hooks/brand-prose-lint.mjs +38 -0
- package/lib/hooks/graph-impact-advisory.mjs +62 -0
- package/lib/hooks/session-optimize.mjs +84 -207
- package/lib/hooks/session-start.mjs +4 -5
- package/lib/host-disposition.mjs +7 -0
- package/lib/improvement/cli.mjs +189 -0
- package/lib/improvement/controller.mjs +137 -0
- package/lib/improvement/proposal.mjs +120 -0
- package/lib/improvement/specialist-loop.mjs +192 -0
- package/lib/improvement/store.mjs +89 -0
- package/lib/improvement/surface.mjs +219 -0
- package/lib/ingest-tooling.mjs +97 -0
- package/lib/init/doc-lanes.mjs +165 -0
- package/lib/init-docs.mjs +31 -178
- package/lib/init-unified.mjs +27 -97
- package/lib/init-update-guide.mjs +102 -0
- package/lib/init-update.mjs +32 -1
- package/lib/init.mjs +8 -0
- package/lib/install/desktop-binary-download.mjs +85 -0
- package/lib/install/legacy-global-cleanup.mjs +189 -0
- package/lib/intake/daemon.mjs +2 -0
- package/lib/intake/git-queue.mjs +9 -8
- package/lib/intake/queue.mjs +2 -1
- package/lib/intake/session-prelude.mjs +90 -1
- package/lib/libreoffice-export.mjs +97 -0
- package/lib/logging/rotate.mjs +9 -0
- package/lib/maintenance/docker-reclaim.mjs +206 -0
- package/lib/mcp/external-schema-cost.mjs +74 -0
- package/lib/mcp/server.mjs +84 -9
- package/lib/mcp/stdio-mcp-probe.mjs +188 -0
- package/lib/mcp/tool-budget.mjs +55 -4
- package/lib/mcp/tools/document.mjs +18 -4
- package/lib/mcp/tools/skills.mjs +32 -3
- package/lib/mcp/tools/workflow.mjs +13 -1
- package/lib/model-free-selector.mjs +18 -0
- package/lib/model-registry.mjs +13 -229
- package/lib/model-router.mjs +425 -93
- package/lib/models/behavior-matrix.mjs +289 -0
- package/lib/models/catalog.mjs +209 -0
- package/lib/models/execution-capability-profile.mjs +196 -0
- package/lib/models/execution-policy.mjs +307 -0
- package/lib/models/provider-poll.mjs +383 -0
- package/lib/npm-spawn-env.mjs +17 -0
- package/lib/ollama/installed-models.mjs +129 -0
- package/lib/oracle/actions.mjs +187 -0
- package/lib/oracle/artifact-gate.mjs +99 -0
- package/lib/oracle/cli.mjs +204 -0
- package/lib/oracle/daemon-entry.mjs +14 -0
- package/lib/oracle/dispatch.mjs +81 -0
- package/lib/oracle/execute.mjs +143 -0
- package/lib/oracle/gaps.mjs +76 -0
- package/lib/oracle/index.mjs +84 -0
- package/lib/oracle/issues.mjs +164 -0
- package/lib/oracle/org-graph.mjs +170 -0
- package/lib/oracle/policy.mjs +80 -0
- package/lib/oracle/read-model.mjs +398 -0
- package/lib/oracle/reconcile.mjs +191 -0
- package/lib/oracle/routing.mjs +89 -0
- package/lib/oracle/synthesize.mjs +384 -0
- package/lib/oracle/verdicts.mjs +51 -0
- package/lib/orchestration/worker.mjs +88 -27
- package/lib/orchestration-policy.mjs +50 -0
- package/lib/parity.mjs +96 -2
- package/lib/persona-sections.mjs +66 -0
- package/lib/playwright-demo.mjs +252 -0
- package/lib/project-init-shared.mjs +4 -1
- package/lib/prompt-composer.js +9 -4
- package/lib/prompt-validation-contract.mjs +24 -0
- package/lib/provider-capabilities.js +57 -11
- package/lib/providers/contract/adapters/confluence/index.mjs +181 -0
- package/lib/providers/contract/adapters/git/index.mjs +115 -0
- package/lib/providers/contract/adapters/github/index.mjs +166 -0
- package/lib/providers/contract/adapters/jira/index.mjs +187 -0
- package/lib/providers/contract/adapters/slack/index.mjs +175 -0
- package/lib/providers/contract/contract-tests.mjs +57 -0
- package/lib/providers/contract/errors.mjs +48 -0
- package/lib/providers/contract/interface.mjs +50 -0
- package/lib/providers/contract/registry.mjs +102 -0
- package/lib/providers/copilot-auth.mjs +297 -0
- package/lib/providers/credential-bootstrap.mjs +178 -0
- package/lib/providers/credential-catalog.mjs +46 -0
- package/lib/providers/credential-sources.mjs +63 -0
- package/lib/providers/creds.mjs +5 -2
- package/lib/providers/op-run.mjs +59 -0
- package/lib/providers/secret-resolver.mjs +159 -0
- package/lib/publish-template.mjs +163 -0
- package/lib/publish-tooling.mjs +119 -0
- package/lib/publish.mjs +305 -0
- package/lib/registry/cli.mjs +82 -0
- package/lib/registry/consolidation.mjs +147 -0
- package/lib/registry/generate-docs.mjs +75 -0
- package/lib/registry/skill-verification.mjs +57 -0
- package/lib/registry/surface-map.mjs +76 -0
- package/lib/registry/validate.mjs +135 -0
- package/lib/resources/budget.mjs +82 -0
- package/lib/resources/process-budget.mjs +45 -0
- package/lib/rules-delivery.mjs +9 -2
- package/lib/rules-read.mjs +26 -0
- package/lib/runtime-env.mjs +23 -0
- package/lib/runtime-pressure.mjs +51 -7
- package/lib/schema-infer.mjs +13 -2
- package/lib/server/chat-loop.mjs +622 -0
- package/lib/server/demo-preview.mjs +63 -0
- package/lib/server/index.mjs +229 -8
- package/lib/server/langfuse-login.mjs +3 -3
- package/lib/service-manager.mjs +61 -9
- package/lib/session-store.mjs +1 -1
- package/lib/setup.mjs +102 -2
- package/lib/specialists/prompt-schema.mjs +19 -10
- package/lib/specialists/roster.mjs +43 -0
- package/lib/specialists/scaffold.mjs +56 -0
- package/lib/storage/backend.mjs +6 -6
- package/lib/storage/embeddings-local.mjs +6 -3
- package/lib/storage/file-lock.mjs +18 -11
- package/lib/storage/hybrid-query.mjs +7 -4
- package/lib/storage/state-source.mjs +5 -5
- package/lib/storage/sync.mjs +2 -3
- package/lib/telemetry/rule-calls.mjs +52 -0
- package/lib/template-registry.mjs +2 -2
- package/lib/templates/visual-requirements.mjs +27 -51
- package/lib/test-corpus-inventory.mjs +313 -0
- package/lib/uninstall/uninstall.mjs +19 -7
- package/lib/update.mjs +12 -0
- package/lib/upgrade.mjs +14 -0
- package/lib/wireframe.mjs +20 -14
- package/lib/worker/run.mjs +17 -4
- package/lib/worker/trace.mjs +11 -3
- package/package.json +29 -13
- package/personas/construct.md +13 -13
- package/platforms/claude/settings.template.json +36 -0
- package/rules/common/patterns.md +1 -1
- package/rules/common/release-gates.md +4 -3
- package/scripts/sync-specialists.mjs +187 -60
- package/skills/devops/data-engineering.md +1 -1
- package/skills/docs/adr-workflow.md +1 -0
- package/skills/docs/backlog-proposal-workflow.md +1 -0
- package/skills/docs/codebase-research-workflow.md +40 -0
- package/skills/docs/customer-profile-workflow.md +1 -0
- package/skills/docs/document-ingest-workflow.md +1 -0
- package/skills/docs/evidence-ingest-workflow.md +1 -0
- package/skills/docs/init-docs.md +2 -2
- package/skills/docs/init-project.md +8 -3
- package/skills/docs/prd-workflow.md +24 -1
- package/skills/docs/prfaq-workflow.md +1 -0
- package/skills/docs/product-intelligence-workflow.md +1 -0
- package/skills/docs/product-signal-workflow.md +1 -0
- package/skills/docs/research-workflow.md +54 -37
- package/skills/docs/runbook-workflow.md +1 -0
- package/skills/docs/strategy-workflow.md +1 -0
- package/skills/docs/user-research-workflow.md +40 -0
- package/skills/operating/orchestration-reference.md +1 -1
- package/skills/roles/architect.md +5 -0
- package/skills/roles/operator.docs.md +4 -0
- package/skills/routing.md +4 -2
- package/specialists/artifact-manifest.json +480 -0
- package/specialists/artifact-manifest.schema.json +53 -0
- package/specialists/audit-enrichments.json +454 -0
- package/specialists/contracts.json +37 -25
- package/specialists/prompts/_shared/validation-contract.md +26 -0
- package/specialists/prompts/cx-accessibility.md +21 -2
- package/specialists/prompts/cx-ai-engineer.md +24 -1
- package/specialists/prompts/cx-architect.md +4 -1
- package/specialists/prompts/cx-business-strategist.md +23 -2
- package/specialists/prompts/cx-data-analyst.md +22 -1
- package/specialists/prompts/cx-data-engineer.md +23 -2
- package/specialists/prompts/cx-debugger.md +21 -2
- package/specialists/prompts/cx-designer.md +26 -3
- package/specialists/prompts/cx-devil-advocate.md +19 -2
- package/specialists/prompts/cx-docs-keeper.md +28 -1
- package/specialists/prompts/cx-engineer.md +22 -1
- package/specialists/prompts/cx-evaluator.md +18 -1
- package/specialists/prompts/cx-explorer.md +21 -2
- package/specialists/prompts/cx-legal-compliance.md +21 -2
- package/specialists/prompts/cx-operations.md +21 -2
- package/specialists/prompts/cx-oracle.md +94 -0
- package/specialists/prompts/cx-orchestrator.md +20 -1
- package/specialists/prompts/cx-platform-engineer.md +25 -2
- package/specialists/prompts/cx-product-manager.md +32 -1
- package/specialists/prompts/cx-qa.md +24 -2
- package/specialists/prompts/cx-rd-lead.md +23 -2
- package/specialists/prompts/cx-release-manager.md +23 -2
- package/specialists/prompts/cx-researcher.md +22 -2
- package/specialists/prompts/cx-reviewer.md +18 -1
- package/specialists/prompts/cx-security.md +22 -2
- package/specialists/prompts/cx-sre.md +30 -3
- package/specialists/prompts/cx-test-automation.md +7 -1
- package/specialists/prompts/cx-trace-reviewer.md +22 -3
- package/specialists/prompts/cx-ux-researcher.md +21 -2
- package/specialists/registry.json +52 -173
- package/specialists/tone-profiles.json +42 -0
- package/templates/demos/playwright/demo-recording.config.mjs +47 -0
- package/templates/demos/recordings/agentic-platforms-prd.json +19 -0
- package/templates/demos/scripts/agentic-platforms-prd.json +44 -0
- package/templates/demos/specs/_helpers/scroll-artifact.ts +89 -0
- package/templates/demos/tapes/agentic-platforms-prd.tape +49 -0
- package/templates/demos/tapes/resource-guard-rails.tape +49 -0
- package/templates/demos/vhs/construct-cockpit.json +24 -0
- package/templates/distribution/construct-brand.typ +446 -0
- package/templates/distribution/construct-decision.typ +38 -0
- package/templates/distribution/construct-deck.html +95 -0
- package/templates/distribution/construct-pdf.typ +38 -0
- package/templates/distribution/construct-prd.typ +38 -0
- package/templates/distribution/construct-research.typ +38 -0
- package/templates/distribution/construct-web.html +92 -0
- package/templates/distribution/fonts/Geist-Bold.ttf +0 -0
- package/templates/distribution/fonts/Geist-Medium.ttf +0 -0
- package/templates/distribution/fonts/Geist-Regular.ttf +0 -0
- package/templates/distribution/fonts/Geist-SemiBold.ttf +0 -0
- package/templates/distribution/fonts/GeistMono-Medium.ttf +0 -0
- package/templates/distribution/fonts/GeistMono-Regular.ttf +0 -0
- package/templates/distribution/fonts/GeistMono-SemiBold.ttf +0 -0
- package/templates/distribution/fonts/IBMPlexMono-Regular.otf +0 -0
- package/templates/distribution/fonts/JetBrainsMono-Medium.ttf +0 -0
- package/templates/distribution/fonts/JetBrainsMono-Regular.ttf +0 -0
- package/templates/distribution/fonts/JetBrainsMono-SemiBold.ttf +0 -0
- package/templates/distribution/fonts/PlusJakartaSans-Bold.ttf +0 -0
- package/templates/distribution/fonts/PlusJakartaSans-Medium.ttf +0 -0
- package/templates/distribution/fonts/PlusJakartaSans-Regular.ttf +0 -0
- package/templates/distribution/fonts/PlusJakartaSans-SemiBold.ttf +0 -0
- package/templates/distribution/fonts/README.md +36 -0
- package/templates/distribution/fonts/SpaceGrotesk-Variable.ttf +0 -0
- package/templates/distribution/fonts/handwritten/Caveat.ttf +0 -0
- package/templates/distribution/fonts/legacy/IBMPlexMono-Regular.otf +0 -0
- package/templates/distribution/fonts/legacy/Inter-Medium.otf +0 -0
- package/templates/distribution/fonts/legacy/Inter-Regular.otf +0 -0
- package/templates/distribution/fonts/legacy/Inter-SemiBold.otf +0 -0
- package/templates/distribution/fonts/legacy/InterDisplay-SemiBold.otf +0 -0
- package/templates/distribution/fonts/legacy/SourceSerif4-Regular.otf +0 -0
- package/templates/distribution/fonts/legacy/SourceSerif4-Semibold.otf +0 -0
- package/templates/distribution/icons/activity.svg +15 -0
- package/templates/distribution/icons/alert-triangle.svg +17 -0
- package/templates/distribution/icons/book-open.svg +16 -0
- package/templates/distribution/icons/bot.svg +20 -0
- package/templates/distribution/icons/brain.svg +22 -0
- package/templates/distribution/icons/circle-check.svg +16 -0
- package/templates/distribution/icons/clipboard-check.svg +17 -0
- package/templates/distribution/icons/cpu.svg +28 -0
- package/templates/distribution/icons/database.svg +17 -0
- package/templates/distribution/icons/eye.svg +16 -0
- package/templates/distribution/icons/file-text.svg +19 -0
- package/templates/distribution/icons/gauge.svg +16 -0
- package/templates/distribution/icons/git-branch.svg +17 -0
- package/templates/distribution/icons/key.svg +17 -0
- package/templates/distribution/icons/layers.svg +17 -0
- package/templates/distribution/icons/list-checks.svg +19 -0
- package/templates/distribution/icons/lock.svg +16 -0
- package/templates/distribution/icons/message-square.svg +15 -0
- package/templates/distribution/icons/network.svg +19 -0
- package/templates/distribution/icons/route.svg +17 -0
- package/templates/distribution/icons/scale.svg +19 -0
- package/templates/distribution/icons/search.svg +16 -0
- package/templates/distribution/icons/send.svg +16 -0
- package/templates/distribution/icons/server.svg +18 -0
- package/templates/distribution/icons/shield-check.svg +16 -0
- package/templates/distribution/icons/users.svg +18 -0
- package/templates/distribution/icons/webhook.svg +17 -0
- package/templates/distribution/icons/workflow.svg +17 -0
- package/templates/distribution/icons/wrench.svg +15 -0
- package/templates/distribution/run.mjs +18 -1
- package/templates/docs/adr.md +7 -0
- package/templates/docs/construct_guide.md +10 -10
- package/templates/docs/customer-profile.md +4 -0
- package/templates/docs/one-pager.md +4 -0
- package/templates/docs/postmortem.md +31 -0
- package/templates/docs/prd-platform.md +19 -0
- package/templates/docs/prd.md +15 -0
- package/templates/docs/prfaq.md +7 -0
- package/templates/docs/qa-strategy.md +103 -0
- package/templates/docs/research-brief.md +8 -0
- package/templates/docs/rfc-platform.md +12 -0
- package/templates/docs/test-plan.md +7 -0
- package/lib/ingest/chunker.mjs +0 -94
- package/lib/ingest/pipeline.mjs +0 -53
- package/lib/ingest/store.mjs +0 -82
- package/lib/mode-commands.mjs +0 -122
- package/lib/policy/unified-gates.mjs +0 -96
- package/lib/profiles/validate-custom.mjs +0 -114
- package/lib/services/telemetry-backend.mjs +0 -177
- package/lib/storage/fusion.mjs +0 -95
|
@@ -24,7 +24,9 @@ import path from 'node:path';
|
|
|
24
24
|
import { fileURLToPath } from 'node:url';
|
|
25
25
|
|
|
26
26
|
import { stageProjectAdapters } from '../lib/install/stage-project.mjs';
|
|
27
|
-
import {
|
|
27
|
+
import { syncProjectAdapters } from '../lib/adapters-sync.mjs';
|
|
28
|
+
import { missingIgnorePatterns, isConstructPackageRepo } from '../lib/host-disposition.mjs';
|
|
29
|
+
import { sanitizeNpmSpawnEnv } from '../lib/npm-spawn-env.mjs';
|
|
28
30
|
|
|
29
31
|
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
|
30
32
|
const PKG_ROOT = path.resolve(HERE, '..');
|
|
@@ -59,7 +61,7 @@ const initCwd = process.env.INIT_CWD || process.cwd();
|
|
|
59
61
|
try {
|
|
60
62
|
const pkgRealRoot = statSync(PKG_ROOT).isDirectory() ? PKG_ROOT : null;
|
|
61
63
|
if (pkgRealRoot && pkgRealRoot.startsWith(initCwd) && initCwd === PKG_ROOT) {
|
|
62
|
-
log('
|
|
64
|
+
log('Construct tool repo — syncing project adapters for dogfooding');
|
|
63
65
|
if (existsSync(path.join(PKG_ROOT, '.gitmessage')) && existsSync(path.join(PKG_ROOT, '.git'))) {
|
|
64
66
|
const cfg = spawnSync('git', ['config', 'commit.template', '.gitmessage'], {
|
|
65
67
|
cwd: PKG_ROOT,
|
|
@@ -67,6 +69,32 @@ try {
|
|
|
67
69
|
});
|
|
68
70
|
if (cfg.status === 0) log('configured git commit.template -> .gitmessage');
|
|
69
71
|
}
|
|
72
|
+
try {
|
|
73
|
+
syncProjectAdapters({ projectRoot: PKG_ROOT, packageRoot: PKG_ROOT, log });
|
|
74
|
+
} catch (err) {
|
|
75
|
+
fail(`Tool-repo adapter sync failed: ${err.message}`, 'Run `npm run adapters` manually.');
|
|
76
|
+
}
|
|
77
|
+
const chatBuild = spawnSync('npm', ['run', 'build:chat'], {
|
|
78
|
+
cwd: PKG_ROOT,
|
|
79
|
+
stdio: 'inherit',
|
|
80
|
+
env: sanitizeNpmSpawnEnv(process.env),
|
|
81
|
+
});
|
|
82
|
+
if (chatBuild.status !== 0) {
|
|
83
|
+
fail('Ink TUI build failed', 'Run `npm run build:chat` manually.');
|
|
84
|
+
} else {
|
|
85
|
+
log('built apps/chat/dist/tui.mjs');
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const dashBuild = spawnSync('npm', ['run', 'build:dashboard'], {
|
|
89
|
+
cwd: PKG_ROOT,
|
|
90
|
+
stdio: 'inherit',
|
|
91
|
+
env: sanitizeNpmSpawnEnv(process.env),
|
|
92
|
+
});
|
|
93
|
+
if (dashBuild.status !== 0) {
|
|
94
|
+
fail('Dashboard build failed', 'Run `npm run build:dashboard` manually.');
|
|
95
|
+
} else {
|
|
96
|
+
log('built lib/server/static/ (dashboard)');
|
|
97
|
+
}
|
|
70
98
|
process.exit(0);
|
|
71
99
|
}
|
|
72
100
|
} catch { /* fall through */ }
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Distribution examples
|
|
2
|
+
|
|
3
|
+
Branded PDF, HTML, deck, and PPTX samples generated from typed markdown sources. Use these to preview Construct's publish layouts (Space Grotesk, monochrome ink, hand-drawn figures).
|
|
4
|
+
|
|
5
|
+
## Generate locally
|
|
6
|
+
|
|
7
|
+
Prerequisites: `construct tools detect --figures` must report ready (pandoc, typst, d2, mmdc; pptxgenjs optional for PPTX). The platform PRD demo requires Playwright in `apps/dashboard` (`npm install`, `npx playwright install chromium`, and `ffmpeg` on PATH for MP4). If browsers are installed outside the sandbox cache, set `PLAYWRIGHT_BROWSERS_PATH` to your Playwright cache (e.g. `~/Library/Caches/ms-playwright` on macOS).
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm run examples:distribution
|
|
11
|
+
open .tmp/distribution-examples/index.html
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
This exports PDF/HTML/deck artifacts with constrained figure sizing (58% max width, 2.35in max height) and records `agentic-platforms-prd.mp4` via the shipped Playwright recording manifest (`templates/demos/recordings/agentic-platforms-prd.json`) — cockpit walkthrough, then scroll through `prd-platform.pdf`.
|
|
15
|
+
|
|
16
|
+
Deck-only (legacy):
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm run examples:deck
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Source layout
|
|
23
|
+
|
|
24
|
+
| File | artifactType | Typst / HTML layout |
|
|
25
|
+
|------|--------------|---------------------|
|
|
26
|
+
| `sources/prd-platform.md` | prd-platform | construct-prd.typ |
|
|
27
|
+
| `sources/adr.md` | adr | construct-decision.typ |
|
|
28
|
+
| `sources/research-brief.md` | research-brief | construct-research.typ |
|
|
29
|
+
| `sources/runbook.md` | runbook | construct-prd.typ |
|
|
30
|
+
| `sources/rfc-platform.md` | rfc-platform | construct-decision.typ |
|
|
31
|
+
| `sources/strategy.md` | strategy | construct-prd.typ |
|
|
32
|
+
| `sources/deck-one-pager.md` | one-pager | construct-deck.html + PPTX |
|
|
33
|
+
|
|
34
|
+
Edit sources, then re-run the generator. Outputs land in `.tmp/distribution-examples/` (gitignored).
|
|
35
|
+
|
|
36
|
+
## Single-file export
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
node bin/construct export examples/distribution/sources/adr.md --to=pdf --figures
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
See [branding.md](../../docs/reference/branding.md) and [diagram-and-demo.md](../../docs/cookbook/diagram-and-demo.md).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
{
|
|
2
|
+
"description": "Branded distribution examples — sources for npm run examples:distribution",
|
|
3
|
+
"outputDir": ".tmp/distribution-examples",
|
|
4
|
+
"items": [
|
|
5
|
+
{
|
|
6
|
+
"id": "prd-platform",
|
|
7
|
+
"source": "sources/prd-platform.md",
|
|
8
|
+
"artifactType": "prd-platform",
|
|
9
|
+
"formats": ["pdf", "html"],
|
|
10
|
+
"recording": "agentic-platforms-prd",
|
|
11
|
+
"demo": "agentic-platforms-prd",
|
|
12
|
+
"demoSurface": "playwright",
|
|
13
|
+
"demoArtifact": "prd-platform.pdf",
|
|
14
|
+
"demoFormat": "mp4"
|
|
15
|
+
},
|
|
16
|
+
{
|
|
17
|
+
"id": "adr",
|
|
18
|
+
"source": "sources/adr.md",
|
|
19
|
+
"artifactType": "adr",
|
|
20
|
+
"formats": ["pdf", "html"]
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
"id": "research-brief",
|
|
24
|
+
"source": "sources/research-brief.md",
|
|
25
|
+
"artifactType": "research-brief",
|
|
26
|
+
"formats": ["pdf", "html"]
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"id": "runbook",
|
|
30
|
+
"source": "sources/runbook.md",
|
|
31
|
+
"artifactType": "runbook",
|
|
32
|
+
"formats": ["pdf", "html"]
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
"id": "rfc-platform",
|
|
36
|
+
"source": "sources/rfc-platform.md",
|
|
37
|
+
"artifactType": "rfc-platform",
|
|
38
|
+
"formats": ["pdf", "html"]
|
|
39
|
+
},
|
|
40
|
+
{
|
|
41
|
+
"id": "strategy",
|
|
42
|
+
"source": "sources/strategy.md",
|
|
43
|
+
"artifactType": "strategy",
|
|
44
|
+
"formats": ["pdf", "html"]
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
"id": "deck",
|
|
48
|
+
"source": "sources/deck-one-pager.md",
|
|
49
|
+
"artifactType": "one-pager",
|
|
50
|
+
"formats": ["deck", "pptx"]
|
|
51
|
+
}
|
|
52
|
+
]
|
|
53
|
+
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Distribution example — ADR with decision layout, diagrams, and citations.
|
|
3
|
+
artifactType: adr
|
|
4
|
+
subtitle: Centralize brand tokens for every export surface
|
|
5
|
+
version: "1.0"
|
|
6
|
+
doc_id: ADR-BRAND-001
|
|
7
|
+
classification: internal
|
|
8
|
+
status: accepted
|
|
9
|
+
owner: cx-architect
|
|
10
|
+
last_verified_at: 2026-06-22
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# ADR-0044: Centralize Construct brand tokens for all export surfaces
|
|
14
|
+
|
|
15
|
+
- **Date**: 2026-06-22
|
|
16
|
+
- **Status**: accepted
|
|
17
|
+
- **Deciders**: cx-architect, cx-docs-keeper
|
|
18
|
+
- **Supersedes**: none
|
|
19
|
+
|
|
20
|
+
## Problem
|
|
21
|
+
|
|
22
|
+
Distribution exports (PDF, HTML, deck, PPTX) and dashboard/chat surfaces drifted when typography moved from retired font families to Space Grotesk and JetBrains Mono. Docs and templates cited stale names; some apps still declared unused npm font packages. Operators could not tell which file was canonical for brand behavior.
|
|
23
|
+
|
|
24
|
+
## Context
|
|
25
|
+
|
|
26
|
+
Construct ships a monochrome ink ramp and bundled OFL fonts under `templates/distribution/fonts/`. Chat and dashboard consume the same tokens via `lib/brand-tokens.mjs` and `lib/chat/design-tokens.mjs`. Profile-specific intake terminology flows through `lib/profiles/rebrand.mjs`.
|
|
27
|
+
|
|
28
|
+
```mermaid
|
|
29
|
+
flowchart LR
|
|
30
|
+
A[brand-tokens.mjs] --> B[Typst PDF]
|
|
31
|
+
A --> C[HTML deck]
|
|
32
|
+
A --> D[Dashboard CSS]
|
|
33
|
+
E[rebrand.mjs] --> F[CLI + API labels]
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
```d2
|
|
37
|
+
direction: right
|
|
38
|
+
|
|
39
|
+
tokens: brand-tokens.mjs {
|
|
40
|
+
shape: document
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
pdf: PDF export
|
|
44
|
+
html: HTML export
|
|
45
|
+
dash: Dashboard
|
|
46
|
+
|
|
47
|
+
tokens -> pdf
|
|
48
|
+
tokens -> html
|
|
49
|
+
tokens -> dash
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Decision
|
|
53
|
+
|
|
54
|
+
Adopt `lib/brand-tokens.mjs` as the single source of truth for visual brand primitives. Document naming, voice, tone, and profile rebrand in `docs/reference/branding.md`. Enforce retired-font drift with `scripts/audit/03d-brand.mjs` in the audit ratchet.
|
|
55
|
+
|
|
56
|
+
## Rationale
|
|
57
|
+
|
|
58
|
+
One token module prevents PDF and web surfaces from diverging when typography changes. A human-facing branding index reduces stale references in cookbooks. Mechanical audit catches Plus Jakarta / Geist regressions without blocking every Write hook.
|
|
59
|
+
|
|
60
|
+
Evidence: Construct's own publish pipeline already routes Typst templates through `construct-brand.typ`, which imports numeric Space Grotesk weights only — see `templates/distribution/construct-brand.typ`.
|
|
61
|
+
|
|
62
|
+
## Rejected alternatives
|
|
63
|
+
|
|
64
|
+
**Per-surface CSS only.** Rejected because PPTX and Typst cannot read dashboard CSS variables; duplication would return on the next rebrand.
|
|
65
|
+
|
|
66
|
+
**Blocking PostToolUse brand hook.** Rejected as too noisy; the audit ratchet pattern matches existing `03b-naming` enforcement.
|
|
67
|
+
|
|
68
|
+
## Consequences
|
|
69
|
+
|
|
70
|
+
Easier: onboarding maintainers, regenerating distribution examples, CI drift detection.
|
|
71
|
+
|
|
72
|
+
Harder: any new surface must import tokens or fail `03d-brand`.
|
|
73
|
+
|
|
74
|
+
Locked in: Space Grotesk + JetBrains Mono until an explicit ADR supersedes this one.
|
|
75
|
+
|
|
76
|
+
## Reversibility
|
|
77
|
+
|
|
78
|
+
Two-way door for documentation and audit scope; one-way for shipped PDFs already distributed to customers (they retain the font embedded at export time).
|
|
79
|
+
|
|
80
|
+
## References
|
|
81
|
+
|
|
82
|
+
- `docs/reference/branding.md`
|
|
83
|
+
- `lib/brand-tokens.mjs`
|
|
84
|
+
- https://fonts.google.com/specimen/Space+Grotesk (accessed 2026-06-22)
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Golden slide-deck fixture for branded HTML deck and PPTX export examples.
|
|
3
|
+
artifactType: one-pager
|
|
4
|
+
subtitle: Governed agentic platform — stakeholder deck
|
|
5
|
+
version: "0.1"
|
|
6
|
+
doc_id: DECK-PLATFORM-001
|
|
7
|
+
classification: internal
|
|
8
|
+
status: draft
|
|
9
|
+
owner: cx-product-manager
|
|
10
|
+
last_verified_at: 2026-06-20
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Construct Platform Overview
|
|
14
|
+
|
|
15
|
+
Monochrome ink · Space Grotesk typography · 16:9 slides
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Problem
|
|
20
|
+
|
|
21
|
+
Platform teams orchestrating AI agents lack a **governed operational layer**.
|
|
22
|
+
|
|
23
|
+
- Cold start — context re-discovered each session
|
|
24
|
+
- Artifacts ship without provenance or citations
|
|
25
|
+
- Exports use host styling, not Construct brand
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## What Construct provides
|
|
30
|
+
|
|
31
|
+
1. **Routing** — specialist chains with intent, track, and gates
|
|
32
|
+
2. **Validation** — manifest-enforced structure before distribution
|
|
33
|
+
3. **Document I/O** — many formats in; branded PDF, HTML, deck, PPTX out
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## Document I/O at a glance
|
|
38
|
+
|
|
39
|
+
| Direction | Formats |
|
|
40
|
+
|-----------|---------|
|
|
41
|
+
| **Ingest** | PDF, Office, email, AV |
|
|
42
|
+
| **Author** | Typed markdown artifacts |
|
|
43
|
+
| **Export** | PDF, DOCX, HTML, PPTX |
|
|
44
|
+
|
|
45
|
+
High fidelity: **docling** sidecar (local-first). Fast tier: unpdf/mammoth.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Branded exports
|
|
50
|
+
|
|
51
|
+
One token set across all distributable formats:
|
|
52
|
+
|
|
53
|
+
- Ink ramp `#0a0c10` → `#fafafa`
|
|
54
|
+
- **Space Grotesk** body · **JetBrains Mono** code
|
|
55
|
+
- Hand-drawn diagrams in PDF/HTML (D2 sketch + Mermaid)
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Next steps
|
|
60
|
+
|
|
61
|
+
- Export: `construct export … --to=pptx`
|
|
62
|
+
- Regenerate: `npm run examples:deck`
|
|
63
|
+
- Matrix: [Document I/O reference](/reference/document-io)
|
|
64
|
+
|
|
65
|
+
Review outputs in `.tmp/distribution-examples/`.
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Golden prd-platform fixture for publish release-gate and demo tapes; not production product docs.
|
|
3
|
+
artifactType: prd-platform
|
|
4
|
+
subtitle: Governed agentic platform contract for enterprise IDE hosts
|
|
5
|
+
version: "0.1"
|
|
6
|
+
doc_id: PRD-PLATFORM-001
|
|
7
|
+
classification: internal
|
|
8
|
+
intake: none
|
|
9
|
+
intake_rationale: Golden fixture for publish release-gate and demo tapes; not production product docs.
|
|
10
|
+
status: draft
|
|
11
|
+
owner: cx-product-manager
|
|
12
|
+
last_verified_at: 2026-06-19
|
|
13
|
+
publish:
|
|
14
|
+
demo: agentic-platforms-prd
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# Platform PRD: Enterprise Agentic Platform
|
|
18
|
+
|
|
19
|
+
- **Date**: 2026-06-19
|
|
20
|
+
- **Owner**: cx-product-manager
|
|
21
|
+
- **Status**: draft
|
|
22
|
+
|
|
23
|
+
> Platform teams need a governed layer between IDE hosts and specialist-authored artifacts — not another chat wrapper. Construct routes work through provenanced invoke plans, blocks distribution until validate passes, and exports briefs that read like finished editorial documents with embedded diagrams rather than markdown dumps. This PRD defines that contract for enterprise agentic platforms.
|
|
24
|
+
|
|
25
|
+
## Problem
|
|
26
|
+
|
|
27
|
+
Platform teams orchestrating multiple AI agents lack a governed operational layer. Each coding session starts cold, artifacts ship without provenance, and high-risk writes bypass approval queues. Internal platform consumers (application developers, ops engineers, security admins) currently stitch together ad hoc prompt conventions instead of a durable contract for routing, evidence, and distribution.
|
|
28
|
+
|
|
29
|
+
Three failure modes recur in internal platform reviews:
|
|
30
|
+
|
|
31
|
+
1. **Cold start** — specialists re-discover repo context every session because invoke plans are not durable or replayable.
|
|
32
|
+
2. **Unprovenanced artifacts** — PRDs and ADRs reach stakeholders without citation discipline or manifest-enforced structure.
|
|
33
|
+
3. **Distribution drift** — PDF exports use host-default styling; diagrams lack Construct hand-drawn (Excalidraw-adjacent) styling and bundled typography.
|
|
34
|
+
|
|
35
|
+
## Platform actors
|
|
36
|
+
|
|
37
|
+
Application developers invoke specialist chains from IDE hosts and expect reproducible PRD outputs. Security admins require citation discipline and release gates before PDF distribution. Ops engineers need toolchain detection that fails loud when Pandoc, Typst, D2, or Mermaid renderers are missing.
|
|
38
|
+
|
|
39
|
+
The actor map below shows how each role touches Construct without bypassing the shared gate:
|
|
40
|
+
|
|
41
|
+
```d2
|
|
42
|
+
direction: down
|
|
43
|
+
|
|
44
|
+
developer: Application developer {
|
|
45
|
+
shape: person
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
security: Security admin {
|
|
49
|
+
shape: person
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
ops: Ops engineer {
|
|
53
|
+
shape: person
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
construct: Construct CLI {
|
|
57
|
+
style.fill: "#f5f3ff"
|
|
58
|
+
style.stroke: "#0a0c10"
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
gate: Release gate\nvalidate + citations {
|
|
62
|
+
style.fill: "#ede9fe"
|
|
63
|
+
style.stroke: "#7c3aed"
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export: Publish export\nPDF + figures {
|
|
67
|
+
style.fill: "#0c1018"
|
|
68
|
+
style.font-color: "#e5e7eb"
|
|
69
|
+
style.stroke: "#0a0c10"
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
developer -> construct: invoke + review plan
|
|
73
|
+
security -> gate: citation + reviewer policy
|
|
74
|
+
ops -> export: toolchain detect
|
|
75
|
+
construct -> gate
|
|
76
|
+
gate -> export
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Goals and non-goals
|
|
80
|
+
|
|
81
|
+
**Goals:** Route requests through provenanced workflow invoke plans; block publish until artifact validate passes; export styled PDFs with Construct-branded D2 and Mermaid figures via a single `construct publish` command; ship bundled typography and masthead layout so exports match across machines.
|
|
82
|
+
|
|
83
|
+
**Non-goals:** Replacing host LLM execution (Construct returns plans; specialists author content). Mandating npm dependencies in core CLI per ADR-0001. Mandating cloud rendering — all figures resolve locally via D2 and mermaid-cli at export time.
|
|
84
|
+
|
|
85
|
+
## Platform flow
|
|
86
|
+
|
|
87
|
+
The end-to-end path from IDE host to distributable PDF is linear and fail-closed at validate:
|
|
88
|
+
|
|
89
|
+
```mermaid
|
|
90
|
+
flowchart TD
|
|
91
|
+
A[Host IDE] --> B[construct workflow invoke]
|
|
92
|
+
B --> C[cx-product-manager]
|
|
93
|
+
C --> D[Typed artifact on disk]
|
|
94
|
+
D --> E[construct artifact validate]
|
|
95
|
+
E --> F[construct publish --figures]
|
|
96
|
+
F --> G[Styled PDF with diagrams]
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The architecture diagram below is the same pipeline at the component level — suitable for architecture reviews and onboarding decks:
|
|
100
|
+
|
|
101
|
+
```d2
|
|
102
|
+
direction: down
|
|
103
|
+
|
|
104
|
+
host_ide: Host IDE (session) {
|
|
105
|
+
shape: person
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
invoke: construct workflow invoke
|
|
109
|
+
author: Specialist chain
|
|
110
|
+
artifact: Typed artifact {
|
|
111
|
+
shape: document
|
|
112
|
+
}
|
|
113
|
+
validate: construct artifact validate
|
|
114
|
+
publish: construct publish
|
|
115
|
+
pdf: Branded PDF {
|
|
116
|
+
shape: document
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
host_ide -> invoke -> author -> artifact -> validate -> publish -> pdf
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Functional requirements
|
|
123
|
+
|
|
124
|
+
| ID | Requirement |
|
|
125
|
+
|---|---|
|
|
126
|
+
| FR-1 | `construct publish` runs `validateArtifactRelease` before export when type is known. |
|
|
127
|
+
| FR-2 | Gate failure exits 2 with remediation hints pointing to `prd-workflow`. |
|
|
128
|
+
| FR-3 | PDF export uses bundled Construct Typst template unless `.cx/publish-theme.typ` overrides. |
|
|
129
|
+
| FR-4 | `--figures` renders fenced `d2` and `mermaid` via vendored `pandoc-ext/diagram` with hand-drawn distribution styling (D2 `--sketch`, Mermaid `handDrawn`). |
|
|
130
|
+
| FR-5 | Masthead metadata (`doc_id`, `version`, `classification`) flows from YAML frontmatter — not repeated in body. |
|
|
131
|
+
|
|
132
|
+
## Success metrics
|
|
133
|
+
|
|
134
|
+
Adoption is measured by the share of PRDs that pass release gate on first validate and publish without `--no-gate`. Latency targets cover export with figures under ten seconds on a typical laptop.
|
|
135
|
+
|
|
136
|
+
| Metric | Baseline | Target |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| Gate pass before publish | manual validate | enforced by default |
|
|
139
|
+
| PDF export p95 | n/a | ≤10s with figures |
|
|
140
|
+
| Demo tapes using `--no-gate` | unknown | 0 in CI |
|
|
141
|
+
| Distribution diagram style | ad hoc | D2 `--sketch` + Mermaid `handDrawn` on every publish |
|
|
142
|
+
|
|
143
|
+
## Risks and mitigations
|
|
144
|
+
|
|
145
|
+
| Risk | Likelihood | Impact | Mitigation |
|
|
146
|
+
|---|---|---|---|
|
|
147
|
+
| Draft iteration blocked by hard gate | med | med | PostToolUse advisory hook during Write; gate only at publish |
|
|
148
|
+
| Typst fonts missing on Linux | low | med | Bundled OFL fonts in `templates/distribution/fonts/` |
|
|
149
|
+
| Agents bypass via MCP | med | high | `publish_run` respects gate by default |
|
|
150
|
+
| Figure toolchain missing in CI | med | med | `construct tools detect --figures`; committed demo MP4s as fallback |
|
|
151
|
+
|
|
152
|
+
Evidence for multi-agent orchestration patterns draws on
|
|
153
|
+
https://arxiv.org/abs/2308.08155 (accessed 2026-06-19) and the LangGraph overview at
|
|
154
|
+
https://langchain-ai.github.io/langgraph/ (accessed 2026-06-19).
|
|
155
|
+
|
|
156
|
+
## References
|
|
157
|
+
|
|
158
|
+
- Construct artifact manifest: `specialists/artifact-manifest.json`
|
|
159
|
+
- PRD workflow skill: `skills/docs/prd-workflow.md`
|
|
160
|
+
- Publish cookbook: `docs/cookbook/diagram-and-demo.md`
|
|
161
|
+
- Golden D2 sources: `tests/fixtures/publish/diagrams/`
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Distribution example — research brief with analytics layout and source table.
|
|
3
|
+
artifactType: research-brief
|
|
4
|
+
subtitle: How teams evaluate agent orchestration layers in 2026
|
|
5
|
+
version: "0.2"
|
|
6
|
+
doc_id: RESEARCH-AGENT-ORCH-2026
|
|
7
|
+
classification: internal
|
|
8
|
+
status: complete
|
|
9
|
+
owner: cx-researcher
|
|
10
|
+
last_verified_at: 2026-06-22
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Research Brief: Agent orchestration adoption among platform teams
|
|
14
|
+
|
|
15
|
+
- **Date**: 2026-06-22
|
|
16
|
+
- **Author**: cx-researcher
|
|
17
|
+
- **Domain**: developer-tools
|
|
18
|
+
- **Status**: complete
|
|
19
|
+
- **Recency baseline**: Sources from 2024 and later; oldest source used: 2023-08-01
|
|
20
|
+
|
|
21
|
+
## Question
|
|
22
|
+
|
|
23
|
+
Do platform teams prefer a governed orchestration layer with provenanced artifacts over host-native agent routing when both are available in the same IDE?
|
|
24
|
+
|
|
25
|
+
## Method
|
|
26
|
+
|
|
27
|
+
Searched arXiv and vendor docs (2024–2026), reviewed three internal ADRs on intake routing, and interviewed two construct maintainers. Inclusion: primary or secondary sources with reproducible claims about multi-agent workflows. Exclusion: marketing landing pages without technical depth.
|
|
28
|
+
|
|
29
|
+
## Sources
|
|
30
|
+
|
|
31
|
+
| Title / Path | Class | Reliability | Credibility | Date | URL | Verified | Relevance |
|
|
32
|
+
|---|---|---|---|---|---|---|---|
|
|
33
|
+
| Multi-agent survey | secondary | B | 3 | 2023-08-01 | https://arxiv.org/abs/2308.08155 | yes | Patterns for specialist routing |
|
|
34
|
+
| LangGraph overview | primary | A | 4 | 2025-01-15 | https://langchain-ai.github.io/langgraph/ | yes | Stateful agent graphs |
|
|
35
|
+
| Construct architecture | primary | A | 5 | 2026-06-01 | docs/concepts/architecture.mdx | yes | Internal contract |
|
|
36
|
+
|
|
37
|
+
## Findings
|
|
38
|
+
|
|
39
|
+
### Finding 1: Provenance gates reduce rework
|
|
40
|
+
|
|
41
|
+
**Observation**: Teams that enforce `construct artifact validate` before publish report fewer stakeholder rejections on first review (internal survey, n=12, 2026-Q2).
|
|
42
|
+
|
|
43
|
+
**Inference**: Manifest-enforced structure and citation lint correlate with faster sign-off, not just better prose.
|
|
44
|
+
|
|
45
|
+
**Confidence**: medium — sample is internal and self-reported.
|
|
46
|
+
|
|
47
|
+
**Sources**: Construct architecture; maintainer interviews.
|
|
48
|
+
|
|
49
|
+
### Finding 2: Branded exports improve trust
|
|
50
|
+
|
|
51
|
+
**Observation**: PDF exports with bundled typography and hand-drawn diagrams are perceived as “finished documents” versus raw markdown attachments (user testing, 2026-05).
|
|
52
|
+
|
|
53
|
+
**Inference**: Visual consistency signals the same quality bar as the release gate.
|
|
54
|
+
|
|
55
|
+
**Confidence**: medium — qualitative study only.
|
|
56
|
+
|
|
57
|
+
**Sources**: Construct publish cookbook; diagram-and-demo user notes.
|
|
58
|
+
|
|
59
|
+
```mermaid
|
|
60
|
+
flowchart TD
|
|
61
|
+
Q[Research question] --> S[Source triage]
|
|
62
|
+
S --> F[Findings + confidence]
|
|
63
|
+
F --> R[Recommendation]
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Confidence summary
|
|
67
|
+
|
|
68
|
+
| Theme | Confidence | Gap |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| Provenance gates | medium | Need external customer sample |
|
|
71
|
+
| Branded exports | medium | Quantitative A/B on open-source adopters |
|
|
72
|
+
|
|
73
|
+
## Recommendation
|
|
74
|
+
|
|
75
|
+
Ship distribution examples (`npm run examples:distribution`) so evaluators can compare PRD, ADR, research, and runbook layouts with figures enabled — not markdown stubs alone.
|
|
76
|
+
|
|
77
|
+
## References
|
|
78
|
+
|
|
79
|
+
- https://arxiv.org/abs/2308.08155 (accessed 2026-06-22)
|
|
80
|
+
- `docs/cookbook/diagram-and-demo.md`
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Distribution example — platform RFC with decision layout and component diagram.
|
|
3
|
+
artifactType: rfc-platform
|
|
4
|
+
subtitle: Distribution examples gallery for evaluators and CI
|
|
5
|
+
version: "0.1"
|
|
6
|
+
doc_id: RFC-PLATFORM-EXAMPLES-001
|
|
7
|
+
classification: internal
|
|
8
|
+
status: proposed
|
|
9
|
+
owner: cx-architect
|
|
10
|
+
last_verified_at: 2026-06-22
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# RFC: Distribution examples gallery
|
|
14
|
+
|
|
15
|
+
- **Date**: 2026-06-22
|
|
16
|
+
- **Status**: proposed
|
|
17
|
+
- **Authors**: cx-architect, cx-docs-keeper
|
|
18
|
+
- **Reviewers**: cx-product-manager, cx-sre
|
|
19
|
+
|
|
20
|
+
## Summary
|
|
21
|
+
|
|
22
|
+
Add `examples/distribution/` sources and `npm run examples:distribution` to regenerate branded PDF, HTML, deck, and PPTX outputs under `.tmp/distribution-examples/` with figures enabled.
|
|
23
|
+
|
|
24
|
+
## Motivation
|
|
25
|
+
|
|
26
|
+
Evaluators and maintainers need side-by-side samples of PRD, ADR, research, runbook, and strategy layouts — not certification stubs. Visual richness (Mermaid + D2, metrics tables, severity matrices) demonstrates the publish pipeline under real toolchain conditions.
|
|
27
|
+
|
|
28
|
+
## Detailed design
|
|
29
|
+
|
|
30
|
+
```d2
|
|
31
|
+
direction: right
|
|
32
|
+
|
|
33
|
+
sources: examples/distribution/sources
|
|
34
|
+
script: generate-distribution-examples.mjs
|
|
35
|
+
out: .tmp/distribution-examples
|
|
36
|
+
|
|
37
|
+
sources -> script -> out
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| Artifact type | Typst layout | Example source |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| prd-platform | construct-prd.typ | prd-platform.md |
|
|
43
|
+
| adr | construct-decision.typ | adr.md |
|
|
44
|
+
| research-brief | construct-research.typ | research-brief.md |
|
|
45
|
+
| runbook | construct-prd.typ | runbook.md |
|
|
46
|
+
| strategy | construct-prd.typ | strategy.md |
|
|
47
|
+
| one-pager deck | construct-deck.html | deck-one-pager.md |
|
|
48
|
+
|
|
49
|
+
The generator reads `manifest.json`, calls `exportMarkdown` with `figures: true`, and writes `index.html` linking all outputs.
|
|
50
|
+
|
|
51
|
+
```mermaid
|
|
52
|
+
sequenceDiagram
|
|
53
|
+
participant Dev as Maintainer
|
|
54
|
+
participant Script as examples:distribution
|
|
55
|
+
participant Export as document-export
|
|
56
|
+
participant Out as .tmp/distribution-examples
|
|
57
|
+
|
|
58
|
+
Dev->>Script: npm run examples:distribution
|
|
59
|
+
Script->>Export: exportMarkdown per manifest item
|
|
60
|
+
Export->>Out: PDF + HTML (+ deck/PPTX)
|
|
61
|
+
Script->>Out: index.html gallery
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Drawbacks
|
|
65
|
+
|
|
66
|
+
- Requires local pandoc, typst, d2, mmdc — fails loud when missing (intentional).
|
|
67
|
+
- `.tmp/` is gitignored; CI may commit snapshots separately if needed.
|
|
68
|
+
|
|
69
|
+
## Alternatives considered
|
|
70
|
+
|
|
71
|
+
**Check in binary PDFs.** Rejected — large diffs and stale quickly.
|
|
72
|
+
|
|
73
|
+
**MkDocs-only previews.** Rejected — does not exercise Typst brand templates.
|
|
74
|
+
|
|
75
|
+
## Unresolved questions
|
|
76
|
+
|
|
77
|
+
- Should certification gate regenerate examples on every `release:check`? Deferred — opt-in script for now.
|
|
78
|
+
|
|
79
|
+
## References
|
|
80
|
+
|
|
81
|
+
- `docs/reference/branding.md`
|
|
82
|
+
- `scripts/generate-deck-examples.mjs` (prior art)
|