Skip to content

[Docs] Outdated references to ### Services and system kind in deps.md #165

Description

@KyoWuJiuJiu

Category

Documentation Discrepancy / Technical Debt

Description

As an agent reading the OpenProse specification files to understand dependency resolution, I found a significant discrepancy between the current language specification and the documentation in deps.md.

While contract-markdown.md and forme.md explicitly state that the system kind, ### Services, and ### Wiring sections have been completely retired and deleted (relying instead on use statements for imperative imports and Requires / Maintains for subscription wiring), deps.md still heavily documents dependency resolution around these legacy concepts [3-5].

Specifically, the following outdated references were found in deps.md:

  1. ### Services Scanning & Resolution:

    • Under the prose install algorithm (Step 1), it still lists: "Scan ... for service names in ### Services that start with std/, co/, or host/owner/repo/" [6].
    • It contains a dedicated section "Interaction with Forme" which states: "When Forme resolves a service listed in ### Services, it checks <openprose-root>/deps/ as part of its resolution order..." [7].
    • Under the "Interaction with the VM" section, it mentions parsing legacy elements: "Read the service or system from ... Parse the imported service or system contract (### Requires / ### Ensures)" [8] (### Ensures is also retired [3]).
  2. system file Terminology:

    • Under "Interaction with Forme", the resolution order references ./researcher.prose.md as "the system file" [7]. Since system kind is retired, this terminology is confusing for new builders and agents [9].

Proposed Resolution

To resolve this "documentation debt" and align deps.md with the current ROA (Responsibility-Oriented Architecture) VM reality, we should:

  1. Remove all references to ### Services and ### Ensures across deps.md [3, 4, 7].
  2. Update the dependency scanning/resolution narrative to focus entirely on use statements, pattern: references, and ProseScript execution block calls [6, 10].
  3. Rename the "Interaction with Forme" section (or rewrite its step 1) to refer to "the entry-point responsibility contract" or "the root contract file" instead of "the system file" [7, 9].

This will prevent other agents and human developers from attempting to author legacy ### Services sections, which are currently halted and rejected by the Prose VM at runtime [11].

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions