@beyondwork/docx-react-component 1.0.0 → 1.0.2

package/skills/README.md

@@ -1,48 +0,0 @@
-# Skills
-
-These skills are tailored to the React Word Editor project. They supplement the generic Wave runtime skills with product constraints that future implementation waves must keep front and center.
-
-## Base Skills Used In This Repo
-
-- `wave-core`
-- `repo-coding-rules`
-- `domain-editor-architecture`
-- `domain-docx-compatibility`
-- `domain-legal-review`
-
-Those base bundles should keep every agent aligned on the three core constraints of this project:
-
-1. schema-first structured editing
-2. safe `.docx` round-trip compatibility
-3. legal-review workflows as a first-class product target
-
-## Important Role Skills
-
-- `role-design`
-- `role-implementation`
-- `role-integration`
-- `role-documentation`
-- `role-cont-qa`
-- `role-cont-eval`
-- `role-security`
-
-The generic role skills remain useful, but `repo-coding-rules` and the three domain skills are where the repo-specific product rules live.
-
-## How To Use Skills Here
-
-- Put lasting architecture rules in the domain skills, not in one-off wave prompts.
-- Keep assignment-specific instructions in the wave prompt.
-- If a rule protects Word compatibility, review-state integrity, or preservation guarantees, it belongs in a reusable skill.
-- If a rule is only about a single feature or one wave, keep it out of the base skill stack.
-
-Wave 0 / Wave 1 note:
-
-- The repository scaffold and subsystem inventory live in `src/` and `services/`.
-- The Wave 1 contract-freeze specs under `docs/plans/waves/specs/` are the architectural baseline that these skill bundles are meant to protect.
-- The skill bundles here are intended to keep later implementation waves aligned with those boundaries rather than redefine them ad hoc.
-
-## Further Reading
-
-- [README.md](../README.md)
-- [AGENTS.md](../AGENTS.md)
-- [Repository Guidance](../docs/reference/repository-guidance.md)

package/skills/domain-docx-compatibility/SKILL.md

@@ -1,44 +0,0 @@
-# DOCX Compatibility
-
-Use this skill whenever a change can affect `.docx` interoperability.
-
-## Primary Rule
-
-Open -> edit -> save -> reopen in Word without damage.
-
-If a shortcut makes implementation easier but weakens round-trip safety, reject the shortcut.
-
-## Compatibility Model
-
-Classify features as:
-
-- `supported-roundtrip`
-- `preserve-only`
-- `unsupported-fatal`
-
-Do not blur those states in code or docs.
-
-## Preservation Rules
-
-- If the repo cannot faithfully edit a feature, preserve it whenever possible.
-- If preservation requires the UI to lock or warn, do that instead of silently flattening the content.
-- Preserve unsupported OOXML fragments in a form that can be reattached during export.
-
-## Proof Bias
-
-Strong proof usually includes:
-
-- fixture-driven import tests
-- fixture-driven export tests
-- round-trip comparisons
-- preservation checks for unsupported OOXML
-- explicit Word reopen validation notes for compatibility-critical milestones
-
-## Anti-Patterns
-
-Do not:
-
-- use HTML serialization as the compatibility contract
-- drop unknown OOXML because it is inconvenient
-- claim Word compatibility without a named fixture or validation artifact
-- conflate a visually acceptable browser render with a safe `.docx` export

package/skills/domain-docx-compatibility/skill.json

@@ -1,19 +0,0 @@
-{
-  "id": "domain-docx-compatibility",
-  "title": "DOCX Compatibility",
-  "description": "Rules for OOXML handling, preservation, and Word-safe round-trip behavior.",
-  "version": "1.0.0",
-  "tags": ["docx", "ooxml", "compatibility"],
-  "activation": {
-    "when": "Attach for any work that touches import, export, preservation, validation, or supported feature semantics.",
-    "roles": [],
-    "runtimes": [],
-    "deployKinds": []
-  },
-  "termination": {
-    "when": "Stop when the change preserves or improves Word-safe round-trip behavior and does not silently drop unsupported content."
-  },
-  "trust": {
-    "tier": "repo-owned"
-  }
-}

package/skills/domain-editor-architecture/SKILL.md

@@ -1,49 +0,0 @@
-# Editor Architecture
-
-Use this skill for any work that affects the React Word Editor architecture.
-
-## Core Principles
-
-- The editor is a document system, not an HTML editor.
-- The canonical source of truth is structured state.
-- The runtime owns editing semantics; the DOM is a rendering target.
-- Keep content, review, preservation, validation, and UI concerns separate.
-- `DESIGN.md` is the source of truth for layout, visual system, and interaction style.
-
-## Required Boundaries
-
-- `model` owns canonical document structure.
-- `core` owns commands, transactions, selection, and mapping.
-- `review` owns comments, revisions, and accept/reject behavior.
-- `io` owns `.docx`, OPC, and OOXML translation.
-- `preservation` owns unsupported-content retention.
-- `validation` owns compatibility and round-trip checks.
-- `ui` owns presentation and interaction, not source-of-truth document semantics.
-
-## UI And Design Rules
-
-- keep the document surface central and stable
-- keep toolbar chrome compact and non-ribbon-like
-- keep the right sidebar review-oriented, not app-shell dominant
-- prefer canvas mode by default
-- show advanced controls contextually
-- route styling through semantic tokens and theme overrides
-- keep review markup visible without visual aggression
-
-## Anti-Patterns
-
-Do not:
-
-- use the DOM as the source of truth
-- let UI components directly mutate canonical state without commands
-- collapse preservation data into ad hoc UI placeholders
-- hide architectural coupling behind convenience helpers with unclear ownership
-- introduce worker-based complexity to avoid fixing main-thread design issues
-
-## Preferred Decisions
-
-- prefer explicit transaction objects over scattered state writes
-- prefer deterministic mapping logic over implicit browser selection behavior
-- prefer versioned serializable data formats over ephemeral runtime-only shapes
-- prefer clear subsystem seams over large “editor utils” files that mix domains
-- prefer tokenized design-system primitives over hard-coded component values

package/skills/domain-editor-architecture/skill.json

@@ -1,19 +0,0 @@
-{
-  "id": "domain-editor-architecture",
-  "title": "Editor Architecture",
-  "description": "Product-specific architecture rules for the schema-based React Word Editor.",
-  "version": "1.0.0",
-  "tags": ["editor", "architecture", "schema"],
-  "activation": {
-    "when": "Attach for any work that changes the editor architecture, document model, runtime, or UI behavior.",
-    "roles": [],
-    "runtimes": [],
-    "deployKinds": []
-  },
-  "termination": {
-    "when": "Stop when the change preserves the repo's architecture boundaries and no DOM-as-source-of-truth shortcuts remain."
-  },
-  "trust": {
-    "tier": "repo-owned"
-  }
-}

package/skills/domain-legal-review/SKILL.md

@@ -1,39 +0,0 @@
-# Legal Review Domain
-
-This repo is optimized for contracts, agreements, comments, and redlines.
-
-## Must-Work Surfaces
-
-- comment anchors and threads
-- tracked insertions and deletions
-- accept/reject flows
-- nested lists
-- tables, including merged-cell scenarios
-
-## Product Bias
-
-- review workflows matter more than broad formatting breadth
-- structured correctness matters more than cosmetic fidelity
-- the UI should stay minimal and contextual, not Word-like for its own sake
-
-## Modeling Expectations
-
-- comments need stable anchors through edits
-- revisions need stable semantics through insertions, deletions, and review actions
-- lists and tables need structured representation, not flattened HTML convenience paths
-- legal-review actions should be explicit state transitions, not loosely inferred UI actions
-
-## Review-Safe Decisions
-
-Prefer:
-
-- explicit accept/reject commands
-- stable anchor mapping utilities
-- structured list and table nodes
-- visible warnings when the editor must preserve rather than fully support a feature
-
-Avoid:
-
-- UI-only comment markers with no canonical anchor model
-- revision rendering that cannot map back to structured state
-- flattening complex lists or tables during import just to simplify editing

package/skills/domain-legal-review/skill.json

@@ -1,19 +0,0 @@
-{
-  "id": "domain-legal-review",
-  "title": "Legal Review Domain",
-  "description": "Rules for comment, redline, list, and table behavior in legal-review workflows.",
-  "version": "1.0.0",
-  "tags": ["legal-review", "comments", "redlines"],
-  "activation": {
-    "when": "Attach for any work that changes review workflows, comments, revisions, lists, tables, or user-facing editing behavior.",
-    "roles": [],
-    "runtimes": [],
-    "deployKinds": []
-  },
-  "termination": {
-    "when": "Stop when the change preserves the repo's legal-review use case and keeps comments and tracked changes first-class."
-  },
-  "trust": {
-    "tier": "repo-owned"
-  }
-}

package/skills/provider-aws/SKILL.md

@@ -1,117 +0,0 @@
-# AWS
-
-<!-- CUSTOMIZE: Add your AWS account IDs, regions, service names, and IAM role ARNs below. -->
-
-## Core Rules
-
-- Name the exact AWS service, account, region, and resource involved.
-- Prefer explicit CLI or console-equivalent evidence for deployment and environment state.
-- Separate IAM or identity issues from workload health or rollout issues.
-- If AWS state is inferred indirectly, mark the proof gap instead of implying live verification.
-- Always include the region in verification commands. Do not rely on default region configuration.
-
-## Resource Identification
-
-Every AWS verification must specify:
-
-- **Service type** -- ECS, Lambda, EC2, S3, CloudFront, RDS, DynamoDB, SQS, SNS, etc.
-- **Account ID** -- the 12-digit AWS account number.
-- **Region** -- the AWS region (e.g., `us-east-1`, `eu-west-1`).
-- **Resource identifier** -- ARN, resource name, or resource ID depending on the service.
-
-Do not use shorthand. `the ECS service` is insufficient. `ecs service my-api in cluster prod-cluster, account 123456789012, us-east-1` is correct.
-
-## Verification Procedures
-
-### ECS (Task and Service Status)
-
-```
-aws ecs describe-services --cluster <cluster> --services <service> --region <region>
-aws ecs list-tasks --cluster <cluster> --service-name <service> --region <region>
-aws ecs describe-tasks --cluster <cluster> --tasks <task-arn> --region <region>
-```
-
-Confirm: desired count matches running count, last deployment status is PRIMARY and COMPLETED, no tasks in STOPPED state with error exit codes.
-
-### Lambda
-
-```
-aws lambda get-function --function-name <name> --region <region>
-aws lambda invoke --function-name <name> --payload '{}' /dev/stdout --region <region>
-```
-
-Confirm: function exists, runtime is expected version, last modified timestamp is recent if just deployed, invoke returns expected status code.
-
-### EC2
-
-```
-aws ec2 describe-instances --instance-ids <id> --region <region>
-```
-
-Confirm: instance state is `running`, status checks pass (system and instance), security groups and network configuration match expectations.
-
-### S3
-
-```
-aws s3 ls s3://<bucket>/ --region <region>
-aws s3api head-bucket --bucket <bucket> --region <region>
-```
-
-Confirm: bucket exists, expected objects are present, access permissions are correct.
-
-### CloudWatch Metrics
-
-```
-aws cloudwatch get-metric-statistics --namespace <ns> --metric-name <metric> --dimensions <dims> --start-time <start> --end-time <end> --period 300 --statistics Average --region <region>
-```
-
-Use for: error rate trends, latency baselines, invocation counts, and health signal confirmation.
-
-<!-- CUSTOMIZE: Add verification procedures for additional AWS services used in your project here. -->
-
-## Evidence Format
-
-When recording AWS verification, use this structure:
-
-```
-Service: <aws-service-type>
-Resource: <ARN-or-name>
-Account: <account-id>
-Region: <region>
-Verification Command: <exact-command-run>
-Result: <summary-of-output>
-Status: <healthy|degraded|failed|unknown>
-Timestamp Context: <when-verified>
-```
-
-Omit fields that were not checked. Do not fill in fields with assumed values.
-
-## IAM vs Workload Issues
-
-These are different failure domains with different owners and different fixes:
-
-### IAM / Identity Failures
-
-- Symptom: `AccessDenied`, `UnauthorizedAccess`, `AssumeRolePolicy` errors.
-- Owner: infrastructure role (the agent or team managing IAM policies and roles).
-- Fix: policy update, trust relationship change, or role assumption path correction.
-- Do not conflate with app health. A Lambda may be healthy but unable to reach S3 due to a missing IAM policy.
-
-### Workload / Application Failures
-
-- Symptom: crash loops, OOM kills, health check failures, timeout errors, application-level error responses.
-- Owner: deploy role (the agent or team managing the application code and configuration).
-- Fix: code fix, configuration change, resource scaling, or dependency resolution.
-
-When reporting failures, classify which domain the failure belongs to. If both are present, report them as separate issues with separate owners.
-
-## Customization
-
-<!-- CUSTOMIZE: Override or extend any section above. Common additions:
-  - AWS account IDs: production=<id>, staging=<id>
-  - Primary regions: <comma-separated-list>
-  - Service inventory: <service-type> -> <resource-name> -> <region>
-  - IAM role ARNs: deploy-role=<arn>, infra-role=<arn>
-  - CloudWatch alarm names and thresholds
-  - Custom health check endpoints per service
--->

package/skills/provider-aws/adapters/claude.md

@@ -1 +0,0 @@
-Prefer AWS CLI commands with `--output json` for machine-readable evidence. Use MCP tools for AWS operations when available. Record exact CLI commands and JSON output excerpts as deployment proof. Separate IAM verification from workload health checks — run both but report independently.

package/skills/provider-aws/adapters/codex.md

@@ -1 +0,0 @@
-Use AWS CLI commands with `--output json` for all verification. Network access may be restricted in sandbox — if AWS APIs are unreachable, record the access gap as deploy risk rather than inferring state. Keep CLI invocations deterministic and capture stdout for evidence.

package/skills/provider-aws/references/service-verification.md

@@ -1,39 +0,0 @@
-# AWS Service Verification Patterns
-
-Reference for verifying AWS deployment state per service type.
-
-## ECS (Elastic Container Service)
-- Task status: `aws ecs describe-tasks --cluster <cluster> --tasks <task-arn>`
-- Service status: `aws ecs describe-services --cluster <cluster> --services <service-name>`
-- Key checks: desiredCount == runningCount, no STOPPED tasks with non-zero exit code, deployment in COMPLETED state.
-- Logs: `aws logs get-log-events --log-group-name <group> --log-stream-name <stream>`
-
-## Lambda
-- Function status: `aws lambda get-function --function-name <name>`
-- Invoke test: `aws lambda invoke --function-name <name> --payload '{}' /dev/stdout`
-- Key checks: State is Active, LastUpdateStatus is Successful, invoke returns expected status code.
-
-## EC2
-- Instance status: `aws ec2 describe-instance-status --instance-ids <id>`
-- Key checks: InstanceState is running, SystemStatus and InstanceStatus are ok.
-- Connect test: Verify security groups allow expected ports.
-
-## S3
-- Bucket verification: `aws s3 ls s3://<bucket>/`
-- Key checks: Bucket exists, expected objects are present, ACLs/policies are correct.
-
-## CloudWatch
-- Metrics: `aws cloudwatch get-metric-statistics --namespace <ns> --metric-name <metric> --period 300 --statistics Average`
-- Alarms: `aws cloudwatch describe-alarms --alarm-names <name>`
-- Key checks: No ALARM state, error rate metrics within threshold.
-
-## RDS
-- Instance status: `aws rds describe-db-instances --db-instance-identifier <id>`
-- Key checks: DBInstanceStatus is available, no pending modifications.
-
-## General Pattern
-For any AWS service:
-1. Identify the resource ARN or name.
-2. Use the describe/get API to verify state.
-3. Check for pending operations or degraded status.
-4. Record the region, account, and exact command used as evidence.

package/skills/provider-aws/skill.json

@@ -1,54 +0,0 @@
-{
-  "id": "provider-aws",
-  "title": "AWS",
-  "description": "Guides deploy verification against AWS services: resource identification, per-service health checks, IAM vs workload issue separation, and evidence recording.",
-  "activation": {
-    "when": "Attach when the wave deploy surface is AWS and the agent must reason about AWS-specific rollout or closure state.",
-    "roles": [
-      "deploy",
-      "infra",
-      "integration",
-      "cont-qa"
-    ],
-    "runtimes": [],
-    "deployKinds": [
-      "aws"
-    ]
-  },
-  "termination": "Stop when AWS service evidence is captured or the blocking surface is isolated.",
-  "permissions": {
-    "network": [
-      "amazonaws.com"
-    ],
-    "shell": [
-      "aws"
-    ],
-    "mcpServers": []
-  },
-  "trust": {
-    "tier": "repo-owned"
-  },
-  "evalCases": [
-    {
-      "id": "deploy-aws",
-      "role": "deploy",
-      "runtime": "opencode",
-      "deployKind": "aws",
-      "expectActive": true
-    },
-    {
-      "id": "infra-aws",
-      "role": "infra",
-      "runtime": "claude",
-      "deployKind": "aws",
-      "expectActive": true
-    },
-    {
-      "id": "documentation-aws",
-      "role": "documentation",
-      "runtime": "claude",
-      "deployKind": "aws",
-      "expectActive": false
-    }
-  ]
-}

package/skills/provider-custom-deploy/SKILL.md

@@ -1,64 +0,0 @@
-# Custom Deploy
-
-<!-- CUSTOMIZE: Add your custom verification commands, health endpoints, deployment scripts, and environment-specific conventions below. -->
-
-## Core Rules
-
-- Make the custom environment contract explicit before treating it as proved.
-- Name the exact verification surface, command, or operator artifact used as evidence.
-- If the environment lacks a stable verification path, record the resulting deploy risk.
-- Do not borrow verification assumptions from standard providers. Custom environments have custom proof requirements.
-- Every claim of "verified" must reference a concrete command, output, or artifact.
-
-## Contract Definition
-
-Before claiming any deploy target is verified in a custom environment, define the contract:
-
-1. **Verification surface** -- what tool, command, API, or artifact serves as the source of truth for this environment's state? Name it exactly.
-2. **Healthy signal** -- what specific output, status code, or artifact state means the deploy is healthy? Define the exact match criteria.
-3. **Degraded signal** -- what output means the deploy is running but not fully healthy? Define the boundary between degraded and healthy.
-4. **Failed signal** -- what output means the deploy has failed? Define the criteria that distinguish failure from degraded.
-5. **Unknown signal** -- if the verification surface is unreachable or returns unexpected output, the state is unknown. Do not default to healthy or failed.
-
-If any of these cannot be defined, record the gap as deploy risk before proceeding.
-
-## Verification Surface
-
-Name the exact verification mechanism:
-
-- **Command-based** -- a CLI command that returns structured output. Preferred. Record the exact command, expected output format, and how to parse healthy/degraded/failed from it.
-- **API-based** -- an HTTP endpoint that returns status. Record the URL, expected status code, expected response body or fields, and authentication method.
-- **Artifact-based** -- a file, database record, or log entry that serves as proof. Record the exact path or query, expected content, and how freshness is determined.
-- **Process-based** -- a running process or service that can be checked. Record the process name, how to check it, and what constitutes healthy state.
-
-Prefer verification surfaces with machine-readable output. If the only evidence is human-readable prose (e.g., a dashboard screenshot), record that as a proof quality limitation.
-
-If no stable verification surface exists for the custom environment, this is itself a deploy risk. Record:
-
-```
-Deploy Risk: No stable verification surface for <environment-name>.
-Attempted: <what-was-tried>
-Observed: <what-was-seen>
-Gap: <what-remains-unknown>
-```
-
-## Risk Recording
-
-When the custom environment lacks standard verification capabilities, record the full state:
-
-1. **What was attempted** -- the exact commands, API calls, or checks that were run.
-2. **What was observed** -- the exact output, including partial or ambiguous results.
-3. **What remains unknown** -- the specific questions that could not be answered.
-4. **Risk assessment** -- how the unknowns affect confidence in the deploy state. Be specific: "cannot confirm database migration ran" is useful; "some things are unclear" is not.
-
-Include this risk record in the `[deploy-status]` marker detail field or as a separate coordination record.
-
-## Customization
-
-<!-- CUSTOMIZE: Override or extend any section above. Common additions:
-  - Custom verification commands: <command> -> <expected-output>
-  - Health endpoints: <url> -> <expected-status> -> <expected-body>
-  - Deployment scripts: <script-path> -> <usage>
-  - Environment-specific conventions: <env-name> -> <verification-approach>
-  - Known proof gaps and accepted risk levels
--->

package/skills/provider-custom-deploy/skill.json

@@ -1,50 +0,0 @@
-{
-  "id": "provider-custom-deploy",
-  "title": "Custom Deploy",
-  "description": "Guides custom environment verification: contract definition, verification surface identification, and deploy risk recording when standard paths are unavailable.",
-  "activation": {
-    "when": "Attach when the wave uses a custom deploy contract and the agent must make the verification surface explicit.",
-    "roles": [
-      "deploy",
-      "infra",
-      "integration",
-      "cont-qa"
-    ],
-    "runtimes": [],
-    "deployKinds": [
-      "custom"
-    ]
-  },
-  "termination": "Stop when the custom deploy contract, evidence, and residual risk are explicitly recorded.",
-  "permissions": {
-    "network": [],
-    "shell": [],
-    "mcpServers": []
-  },
-  "trust": {
-    "tier": "repo-owned"
-  },
-  "evalCases": [
-    {
-      "id": "deploy-custom",
-      "role": "deploy",
-      "runtime": "opencode",
-      "deployKind": "custom",
-      "expectActive": true
-    },
-    {
-      "id": "integration-custom",
-      "role": "integration",
-      "runtime": "claude",
-      "deployKind": "custom",
-      "expectActive": true
-    },
-    {
-      "id": "documentation-custom",
-      "role": "documentation",
-      "runtime": "claude",
-      "deployKind": "custom",
-      "expectActive": false
-    }
-  ]
-}

package/skills/provider-docker-compose/SKILL.md

@@ -1,96 +0,0 @@
-# Docker Compose
-
-<!-- CUSTOMIZE: Add your compose file paths, service names, and health check endpoints below. -->
-
-## Core Rules
-
-- Use compose file names, service names, ports, and health checks exactly.
-- Distinguish local container health from production readiness.
-- Record the exact compose commands or logs used as proof.
-- Make service dependency and readiness ordering explicit when rollout depends on it.
-- Container running is not the same as application healthy. Always verify beyond container state.
-
-## Service Identification
-
-Every Docker Compose verification must specify:
-
-- **Compose file path** -- the exact path to the compose file (e.g., `docker-compose.yml`, `docker-compose.prod.yml`, `compose.yaml`).
-- **Service names** -- exact names as defined in the compose file.
-- **Exposed ports** -- host:container port mappings for each service.
-- **Volume mounts** -- named volumes or bind mounts that carry persistent state.
-- **Network names** -- custom networks defined in the compose file, if any.
-
-Do not use shorthand. `the database service` is insufficient. `service postgres in docker-compose.yml, port 5432:5432, volume pgdata:/var/lib/postgresql/data` is correct.
-
-## Verification Procedures
-
-### Container State
-
-```
-docker compose -f <file> ps
-docker compose -f <file> ps --format json
-```
-
-Confirm: all expected services are listed, state is `running` (not `exited`, `restarting`, or `created`), health status is `healthy` if healthcheck is defined.
-
-### Service Logs
-
-```
-docker compose -f <file> logs <service> --tail=50
-docker compose -f <file> logs <service> --since 5m
-```
-
-Confirm: no fatal errors, startup completed successfully, application-level health indicators are positive.
-
-### Health Checks
-
-```
-docker compose -f <file> exec <service> <health-command>
-curl -s http://localhost:<port>/health
-```
-
-Confirm: health endpoint returns expected status code and body. If the service defines a Docker healthcheck, verify it shows `healthy` in `docker compose ps`.
-
-### Detailed Container State
-
-```
-docker inspect <container-name-or-id>
-docker inspect --format='{{.State.Health.Status}}' <container-name-or-id>
-```
-
-Use for: investigating restart reasons, checking exact health check output, verifying environment variables and mount points inside the container.
-
-<!-- CUSTOMIZE: Add project-specific verification commands or health endpoints here. -->
-
-## Local vs Production
-
-Do not conflate container state with application readiness:
-
-- **Container running** -- the process started. This does not mean it is accepting requests or connected to its dependencies.
-- **Container healthy** -- the Docker healthcheck passed. This confirms a basic liveness check but may not cover all application functionality.
-- **Application healthy** -- the application responds correctly to real requests, is connected to all dependencies, and is processing work as expected.
-- **Production ready** -- the full stack is up, all integration points are verified, and the environment matches production configuration.
-
-When reporting status, be precise about which level of health you verified. If you only confirmed container state, say so.
-
-## Dependency Ordering
-
-Compose services often depend on each other. Verify startup order:
-
-1. **`depends_on` declarations** -- confirm they are present in the compose file for services that need them.
-2. **Healthcheck-based readiness** -- `depends_on` with `condition: service_healthy` ensures the dependency is ready, not just started. Prefer this over bare `depends_on`.
-3. **Startup order verification** -- after `docker compose up`, check logs to confirm services started in the correct order and downstream services did not fail due to missing upstream dependencies.
-4. **Retry behavior** -- if a service connects to a dependency on startup, verify it has retry logic or that the dependency was healthy before the service started.
-
-When dependency ordering issues cause failures, record the exact failure chain: which service failed, which dependency was not ready, and what error appeared.
-
-## Customization
-
-<!-- CUSTOMIZE: Override or extend any section above. Common additions:
-  - Compose file paths: <comma-separated-list>
-  - Service names: <comma-separated-list>
-  - Health check endpoints: <service> -> <url>
-  - Required environment variables per service
-  - Volume backup and restore procedures
-  - Network topology notes
--->