{"name":"Astory Arc authoring instructions","instructionsVersion":1,"schemaVersion":1,"purpose":"Create versioned architectural intent for a repository and evaluate it against observed source code.","workflow":["Read the user’s architecture goal and inspect existing .astory/arcs files before writing intent. Change implementation code only when the user requests it.","Obtain the latest Astory scan and exact observed entity IDs. The source inspector exposes Arc mapping IDs, including the owning service ID. If IDs are unavailable, ask for them or explicitly leave new intent unmapped; never invent observed IDs.","Create .astory/arcs/<arc-id>/<version>.yaml. Use a stable lowercase hyphenated Arc ID and zero-padded numeric filenames such as 001.yaml.","For a new Arc use version 1 and predecessor null. For a revision, add the next numbered file and name the immediately preceding version. Retain prior files unchanged and present in the same revision.","Use base: {type: empty} in the current product. Each version describes its complete intended target, rather than only the difference from its predecessor. Observed snapshot bases are not resolved by the current scan endpoint.","Map existing entities using their exact observed_id and matching entity_type. Display names do not establish identity. A service ID belongs to entity_type service, not component.","Declare intended entities before relationships that reference them. Add explicit requirements for the relationships or source changes that define completion.","Commit the Arc on the intended branch and open or update its pull request only when authorized. Scan that PR in Astory or use its installed GitHub App webhook; select the matching Arc overlay and inspect requirement evidence.","Report the file path, version, mappings, requirements and checks actually executed. Distinguish valid YAML from observed implementation; never claim a scan or requirement passed without its evaluation result."],"contract":{"requiredTopLevelFields":["schema_version","arc","base","operations"],"schema_version":1,"arc":{"id":"Must match the directory name","name":"Human-readable name","version":"Positive integer matching the filename number","predecessor":"null for version 1; version minus one thereafter"},"base":{"type":"empty"},"entityTypes":["service","component","module","datastore","queue","external"],"relationshipTypes":["calls","reads","writes","publishes","consumes","depends_on"],"operationIds":"Unique, nonempty stable identifiers within the operations list. Use lowercase hyphenated IDs.","addEntity":{"type":"add_entity","id":"Local intended entity ID","entity_type":"One of entityTypes","name":"Human-readable name","observed_id":"Optional exact observed entity ID of the same kind","system":"Optional canonical system alias","service":"Required local service ID for component entities; declare that service first"},"addRelationship":{"type":"add_relationship","id":"Unique local relationship ID","from":"Local intended entity ID","to":"Local intended entity ID","relationship_type":"One of relationshipTypes"},"otherOperations":"For the current product, author each complete empty-base target using add_entity and add_relationship. Do not express version-to-version changes with modify/remove operations or assume predecessor operations are inherited; observed-base resolution is unavailable.","requirements":{"common":"Each requirement has a unique id, type and optional required boolean (defaults to true).","architecture":{"id":"Stable requirement ID","type":"architecture","required":true,"relationship":{"from":"Local intended entity ID","to":"Local intended entity ID","type":"One of relationshipTypes"}},"code_change":{"id":"Stable requirement ID","type":"code_change","required":true,"component":"Optional local intended entity ID with a safe observed mapping","paths":["Repository-relative source path or supported glob"],"symbols":["Symbol to find in changed source"]},"codeChangeRules":"code_change needs nonempty paths and/or symbols, plus top-level source_base: {commit: FULL_40_HEX_CHARACTER_BASE_SHA}. Use an existing immutable commit before the implementation change. The current evaluator checks qualifying changed source containing the declared symbol, not semantic correctness.","architectureRules":"The required relationship must exist in the intended operations. Use local entity IDs, not observed IDs, in relationship requirements."},"mappingRules":["Use exact observed_id for an existing entity. Leave a genuinely new entity unmapped until observed.","Canonical aliases can match uniquely observed infrastructure of the same kind: aws-s3 (datastore), aws-dynamodb (datastore), aws-sns (queue), aws-sqs (queue).","Do not merge by display name or guess a mapping when multiple candidates exist. A detached dotted node is unmatched intent, not proof that deployed code is disconnected."]},"example":{"path":".astory/arcs/order-flow/001.yaml","placeholders":{"service:OWNER/REPOSITORY:.":"Replace with the exact observed service ID from the Astory scan. This example ID is not a valid mapping for your repository until replaced."},"yaml":"schema_version: 1\narc:\n  id: order-flow\n  name: Order Flow\n  version: 1\n  predecessor: null\nbase:\n  type: empty\noperations:\n  - type: add_entity\n    id: api\n    entity_type: service\n    name: Orders API\n    observed_id: service:OWNER/REPOSITORY:.\n  - type: add_entity\n    id: orders\n    entity_type: queue\n    name: Orders Queue\n    system: aws-sqs\n  - type: add_relationship\n    id: publish-orders\n    from: api\n    to: orders\n    relationship_type: publishes\nrequirements:\n  - id: orders-are-published\n    type: architecture\n    required: true\n    relationship:\n      from: api\n      to: orders\n      type: publishes\n"},"validation":["Check YAML syntax, schema_version 1, path/Arc ID/version agreement and predecessor continuity.","Check unique operation and requirement IDs, allowed entity/relationship kinds and references to declared local entity IDs.","Check every component has a declared service and every observed mapping has the matching entity kind.","Check source_base.commit is a real immutable 40-character SHA if code_change requirements are present.","Astory discovers Arc files during scans and returns parsing diagnostics and evaluation states. No standalone public validation endpoint or CLI is currently provided.","Review SATISFIED, PARTIAL, OUTSTANDING, DIVERGED or UNKNOWN results and their evidence. YAML validity alone is not implementation completion."],"scannerCoverage":{"defaultLanguages":["JavaScript/TypeScript","Python (boto3)","Java"],"verifiedAwsSystems":["Amazon S3","DynamoDB","Amazon SNS","Amazon SQS"],"limits":"Recognizes supported concrete SDK operations from source. Does not inventory AWS accounts or reconstruct VPC/EC2/ECS/RDS/Lambda deployments. Dynamic wrappers and resource names may remain unresolved; multiple resources can be grouped by AWS system."},"links":{"guide":"https://astory.dev/arc","product":"https://astory.dev/system","instructions":"https://astory.dev/api/arc/instructions"}}